# Canvas Medical Developer Documentation (Full Reference)

> Canvas Medical's developer documentation: the server-side Python SDK, the FHIR API, and implementation guides for building EMR customizations. Patient and staff keys are UUIDs without dashes; other identifiers use standard dashed UUIDs.

# Appointment Metadata Create form

Source: https://docs.canvasmedical.com/sdk/appointment-metadata-create-form-effect/

This allows developers to dynamically display additional fields when scheduling an appointment. For more guidance, see the ["How to add additional fields to the scheduling appointment fields" guide](/guides/appointments-additional_fields/).
Build an `AppointmentsMetadataCreateFormEffect` with the form fields to show, then return its `apply()` from an `APPOINTMENT__FORM__GET_ADDITIONAL_FIELDS` handler.
##  Methods 
###  apply() → Effect 
Displays the form fields on the appointment form.
  - `form_fields` is required.
  - `options` may only be set on fields whose `type` is `InputType.SELECT`.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`form_fields`| `list[``FormField``]`| List of fields.| Yes  
##  FormField 
Attribute| Type| Description  
---|---|---  
`key`| `str`| Unique identifier of the field; the appointment metadata key.  
`label`| `str`| The label displayed on the field.  
`type`| `InputType`| The type of the input: `TEXT`, `SELECT`, or `DATE`. Defaults to `TEXT`.  
`required`| `bool`| Whether the input is required. Defaults to `False`.  
`editable`| `bool`| Whether the input can be edited. Defaults to `True`.  
`options`| `list[str]`| Possible options when the input type is `SELECT`. Only allowed on `SELECT` fields.  
`value`| `str`| Default value for the field.  
##  Example 
    ```python
    from canvas_sdk.effects.appointments_metadata import (
        FormField,
        InputType,
        AppointmentsMetadataCreateFormEffect,
    )
    AppointmentsMetadataCreateFormEffect(form_fields=[
        FormField(
            key='status',
            label='Status',
            type=InputType.SELECT,
            required=False,
            editable=True,
            options=["open", "close"],
            value=""
        ),
    ]).apply()
    ```

---

# Caching API

Source: https://docs.canvasmedical.com/sdk/caching/

The Canvas SDK provides a caching API for plugin developers to store and retrieve temporary data efficiently.
For persistent storage of plugin data, use instead the [Custom Data](/sdk/custom-data/) features.
* * *
##  Getting the Cache Client 
To use the cache in your plugin, simply import and call:
    ```python
    from canvas_sdk.caching.plugins import get_cache
    cache = get_cache()
    ```
* * *
##  TTL and Expiration 
  - By default, all cached keys expire after **14 days**.
  - You can set a shorter TTL when writing to the cache via the `timeout_seconds` parameter.
  - If a longer TTL is provided, a `CachingException` will be raised.
###  Caching an external access token 
When a plugin calls an external API that issues OAuth access tokens, cache the token rather than requesting a new one on every call. Set `timeout_seconds` to the token's lifetime so the plugin fetches a fresh one only after the old one expires. Keep the client credentials in [secrets](/sdk/secrets/).
    ```python
    from canvas_sdk.caching.plugins import get_cache
    from canvas_sdk.utils import Http
    def get_access_token(secrets: dict) -> str:
        cache = get_cache()
        token = cache.get("partner_access_token")
        if token is None:
            response = Http().post(
                "https://auth.example.com/oauth/token",
                data={
                    "grant_type": "client_credentials",
                    "client_id": secrets["PARTNER_CLIENT_ID"],
                    "client_secret": secrets["PARTNER_CLIENT_SECRET"],
                },
            )
            body = response.json()
            token = body["access_token"]
            # Expire a minute early so a token never runs out mid-request.
            cache.set("partner_access_token", token, timeout_seconds=body["expires_in"] - 60)
        return token
    ```
Call it from a handler as `get_access_token(self.secrets)`.
* * *
##  Supported Methods 
###  `get(key: str, default: Any | None = None) -> Any`
Retrieve a value from the cache:
    ```python
    user = cache.get("key")
    ```
You can specify a fallback if the key doesn't exist:
    ```python
    user = cache.get("key", default="default_value")
    ```
* * *
###  `set(key: str, value: Any, timeout_seconds: int | None = None) -> None`
Store a value in the cache:
    ```python
    cache.set("key", {"name": "Alice"}, timeout_seconds=600)
    ```
* * *
###  `get_or_set(key: str, default: Any | Callable, timeout_seconds: int | None = None) -> Any`
Fetch a value or set it if not present:
    ```python
    value = cache.get_or_set("key", default=lambda: compute_value(), timeout_seconds=300)
    ```
* * *
###  `set_many(data: dict[str, Any], timeout_seconds: int | None = None) -> list[str]`
Set multiple values at once:
    ```python
    cache.set_many({
        "key1": {"name": "Alice"},
        "key2": {"name": "Bob"}
    }, timeout_seconds=900)
    ```
* * *
###  `get_many(keys: Iterable[str]) -> dict[str, Any]`
Fetch multiple values in one operation:
    ```python
    users = cache.get_many(["key1", "key2"])
    ```
* * *
###  `delete(key: str) -> None`
Remove a key from the cache:
    ```python
    cache.delete("key")
    ```
* * *
###  `__contains__(key: str) -> bool`
Check if a key exists in cache:
    ```python
    if "key" in cache:
        ...
    ```

---

# Calendar Create

Source: https://docs.canvasmedical.com/sdk/calendar-create-effect/

This allows developers to create calendars for providers in Canvas. Calendars can be either Clinic or Administrative type and can optionally be associated with a location.
Build a `Calendar` with the attributes you want to set, then return its `create()` from your handler.
##  Methods 
###  create() → Effect 
Creates the calendar.
  - `provider` and `type` are required.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`id`| `str \| UUID \| None`| Optional unique identifier for the calendar.| No  
`provider`| `str \| UUID`| The id of the [provider](/sdk/data-staff/).| Yes  
`type`| `CalendarType`| The type of calendar: `CalendarType.Clinic` or `CalendarType.Administrative`.| Yes  
`location`| `str \| UUID \| None`| The id of the [location](/sdk/data-practicelocation/) to associate with the calendar.| No  
`description`| `str \| None`| Description of the calendar's purpose.| No  
##  CalendarType 
An enumeration of calendar types:
Value| Description  
---|---  
`Clinic`| Calendar for clinical appointments  
`Administrative`| Calendar for administrative tasks  
##  Example 
    ```python
    from canvas_sdk.effects.calendar import Calendar, CalendarType
    Calendar(
       provider="provider-uuid",
       type=CalendarType.Clinic,
       location="location-uuid",
       description="Primary clinic calendar"
    ).create()
    ```

---

# Calendar Event Management

Source: https://docs.canvasmedical.com/sdk/calendar-event-management-effects/

This allows developers to create, update, and delete calendar events for providers in Canvas. Events can be one-time or recurring, with support for daily and weekly recurrence patterns.
Build an `Event` with the attributes you want to set, then return one of its methods from your handler: `create()`, `update()`, or `delete()`.
##  Methods 
###  create() → Effect 
Creates the event on a calendar.
  - `calendar_id`, `title`, `starts_at`, and `ends_at` are required.
###  update() → Effect 
Updates an existing event.
  - `event_id`, `title`, `starts_at`, and `ends_at` are required.
###  delete() → Effect 
Deletes an existing event.
  - `event_id` is required.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`calendar_id`| `str \| UUID \| None`| The id of the calendar where the event will be created.| For `create()`  
`event_id`| `str \| UUID \| None`| The id of the event to update or delete.| For `update()` and `delete()`  
`title`| `str \| None`| The title of the event.| For `create()` and `update()`  
`starts_at`| `datetime \| None`| The start date and time of the event.| For `create()` and `update()`  
`ends_at`| `datetime \| None`| The end date and time of the event.| For `create()` and `update()`  
`recurrence_frequency`| `EventRecurrence` `\| None`| The frequency of recurrence: `EventRecurrence.Daily` or `EventRecurrence.Weekly`.| No  
`recurrence_interval`| `int \| None`| The interval between recurrences (for example, 1 for every week, 2 for every other week).| No  
`recurrence_days`| `list[``DaysOfWeek``] \| None`| List of days when the event should recur (used with weekly recurrence).| No  
`recurrence_ends_at`| `datetime \| None`| The date and time when the recurrence pattern ends.| No  
`allowed_note_types`| `list[str] \| None`| List of note types that are allowed for this event.| No  
##  EventRecurrence 
An enumeration of recurrence frequency options:
Value| Description  
---|---  
`Daily`| Event recurs daily  
`Weekly`| Event recurs weekly  
##  DaysOfWeek 
An enumeration of days of the week for recurring events:
Value| Description  
---|---  
`MO`| Monday  
`TU`| Tuesday  
`WE`| Wednesday  
`TH`| Thursday  
`FR`| Friday  
`SA`| Saturday  
`SU`| Sunday  
##  Example 
    ```python
    from canvas_sdk.effects.calendar import Event, EventRecurrence, DaysOfWeek
    from datetime import datetime
    # Create a one-time event
    Event(
        calendar_id="calendar-uuid",
        title="Patient Consultation",
        starts_at=datetime(2025, 1, 15, 9, 0),
        ends_at=datetime(2025, 1, 15, 10, 0)
    ).create()
    # Create a recurring event
    Event(
        calendar_id="calendar-uuid",
        title="Weekly Team Meeting",
        starts_at=datetime(2025, 1, 15, 14, 0),
        ends_at=datetime(2025, 1, 15, 15, 0),
        recurrence_frequency=EventRecurrence.Weekly,
        recurrence_interval=1,
        recurrence_days=[DaysOfWeek.Monday, DaysOfWeek.Wednesday],
        recurrence_ends_at=datetime(2025, 12, 31, 23, 59),
        allowed_note_types=["100", "101"]
    ).create()
    # Update an existing event
    Event(
        event_id="event-uuid",
        title="Updated Meeting Title",
        starts_at=datetime(2025, 1, 15, 15, 0),
        ends_at=datetime(2025, 1, 15, 16, 0)
    ).update()
    # Delete an event
    Event(event_id="event-uuid").delete()
    ```

---

# Canvas CLI

Source: https://docs.canvasmedical.com/sdk/canvas_cli/

> **Warning:** The Canvas CLI signs in with `canvas login` and ships plugins with `canvas deploy`. Instance API credentials in `credentials.ini` and `canvas install` are deprecated, and support for them ends on **December 14, 2026**. See [Moving to Canvas Platform](/guides/moving-to-canvas-platform/).
##  Getting Started 
###  Installation using `pip`
To install the Canvas CLI using `pip`, execute `pip install canvas`. Python 3.11, 3.12, or 3.13 is required.
To upgrade the Canvas CLI if you installed using `pip`, execute `pip install --upgrade canvas`.
###  Installation using `uv`
To install the Canvas CLI using `uv`, execute `uv tool install canvas`. `uv` will find or procure an acceptable Python version.
To upgrade the Canvas CLI if you installed using `uv`, execute `uv tool upgrade canvas`.
###  Signing in to Canvas Platform 
The Canvas CLI signs in to [Canvas Platform](https://platform.canvasmedical.com), which hosts each plugin's git repository and deploys it to the instances your organizations manage. Sign in once per machine:
    ```console
    $ canvas login
    Signed in to https://platform.canvasmedical.com as you@example.com.
      Acme Health (acme): plugin prefix acme__
    ```
`canvas login` opens your browser and also prints the sign-in URL, for a machine without a browser. It lists each organization you belong to with its plugin prefix. The session is stored in `~/.canvas/platform-credentials.json`, readable only by you, and refreshes itself. `canvas logout` revokes it. A CI/CD pipeline signs in with a service account instead.
A plugin deployed through Canvas Platform has a publisher-prefixed name, `<org prefix>__<package>` (for example `acme__intake`), used for the manifest `name`, the package folder and its imports. The prefix decides which organization publishes the plugin.
`canvas login --platform <url>` or the `CANVAS_PLATFORM_URL` environment variable points the CLI at a platform other than https://platform.canvasmedical.com, and later commands keep using the platform you last signed in to.
`canvas whoami` shows which platform the CLI is using, why, and who you are signed in as there:
    ```console
    $ canvas whoami
    Platform: https://platform.canvasmedical.com (from your last `canvas login`)
    Signed in as you@example.com (browser session from `canvas login`)
      Acme Health (acme): plugin prefix acme__, can push, deploy, configure, uninstall
    ```
**You are now ready to use the Canvas CLI.** Continue with `canvas init` and `canvas deploy`.
###  Service accounts for CI/CD 
The Canvas CLI supports service accounts for automated pipelines such as GitHub Actions, GitLab CI or any other CI/CD system. A service account is an identity that belongs to your organization rather than to a person, so a pipeline that publishes and deploys plugins keeps working when the person who set it up leaves, and Canvas Platform's audit log names the service account behind each push and deploy. A pipeline signs in with the account's token instead of `canvas login`, which needs a browser.
**Create a service account.** An Organization admin, Plugin developer or Deploy manager creates one on the Credentials page in Canvas Platform. A service account can hold the Plugin developer and Deploy manager roles. An Organization admin can give it either role; a Plugin developer or Deploy manager can give only the roles they hold, so a Plugin developer cannot create an account that deploys. Its token is shown once and is valid for a year.
**Use it in a pipeline.** Store the token as a secret in your CI/CD system and expose it to the job as the `CANVAS_PLATFORM_TOKEN` environment variable. No `canvas login` step is needed:
    ```yaml
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - run: pip install canvas
    - run: canvas deploy my-plugin/acme__my_plugin --instance acme-staging --yes
      env:
        CANVAS_PLATFORM_TOKEN: ${{ secrets.CANVAS_PLATFORM_TOKEN }}
    ```
  - Check out the full history (`fetch-depth: 0` in GitHub Actions). `canvas deploy` pushes the checkout to the plugin's repository on Canvas Platform, and git refuses to push a shallow clone to a repository that lacks its history.
  - The push to Canvas Platform's `main` is not forced, so it is refused when Canvas Platform's `main` has a commit the checkout lacks, such as one a developer deployed from their machine without pushing it to the repository the pipeline checks out. Once a pipeline deploys a plugin, deploy it only from the pipeline.
  - When `CANVAS_PLATFORM_TOKEN` is set, every command uses it in place of a `canvas login` session, including the git pushes `canvas deploy` makes. It takes precedence over a session already stored on the machine, so a runner always acts as its service account.
  - `--yes` commits uncommitted changes without prompting. A deployment that needs consent for another plugin's custom data exits non-zero and lists the requests, because only a person at a terminal answers those.
  - `CANVAS_PLATFORM_URL` points the job at a platform other than https://platform.canvasmedical.com.
**Rotate or revoke it.** The token does not refresh. Rotating it on the Credentials page ends the old token, and revoking the service account ends it for good; either way the CLI's next request says that Canvas Platform did not accept `CANVAS_PLATFORM_TOKEN`. `canvas logout` signs out only a browser session and leaves the token alone.
###  Instance API credentials (`credentials.ini`): deprecated 
> **Warning:** **Deprecated:** authenticating the Canvas CLI with OAuth client credentials in `~/.canvas/credentials.ini`, and installing plugins with `canvas install`, are deprecated. Support ends on **December 14, 2026**. Sign in with `canvas login` and deploy with `canvas deploy` instead. [Moving to Canvas Platform](/guides/moving-to-canvas-platform/) walks through the switch.
With `credentials.ini`, the CLI authenticates to each instance with an OAuth client registered on that instance. `canvas install`, `enable`, `disable`, `list`, `config list`, `logs` and the `namespace` commands authenticate this way today, as do `config set`, `config unset` and `uninstall` for a plugin Canvas Platform does not manage. Keep `credentials.ini` until the commands you use sign in through Canvas Platform.
A machine can hold both a Canvas Platform sign-in and `credentials.ini` at once; the CLI picks per command and per plugin, as described in Which plugins go through Canvas Platform.
The file has a section for each Canvas instance subdomain, with that instance's `client_id` and `client_secret`. For example, if your Canvas instance URL is `https://buttered-popcorn.canvasmedical.com/`, its section is `[buttered-popcorn]`. [Customer Authentication](/api/customer-authentication/#registering-a-third-party-application-on-canvas) explains how to register a client.
**Example:**
    ```ini
    [buttered-popcorn]
    client_id=butter
    client_secret=salt
    [dev-buttered-popcorn]
    client_id=devbutter
    client_secret=devsalt
    is_default=true
    [localhost]
    client_id=localclientid
    client_secret=localclientsecret
    ```
You can define your default host with `is_default=true`. If no default is explicitly defined, the Canvas CLI will use the first instance in the file as the default for each of the CLI commands.
###  Deprecation notices 
`canvas install` prints a deprecation warning on every run. Separately, at most once a day, any command, `canvas install` included, prints a notice that authentication and deployment are changing, with a link to the migration steps. Both go to standard error, so they do not interfere with piped or redirected output.
###  Which plugins go through Canvas Platform 
`canvas config set`, `canvas config unset` and `canvas uninstall` work for plugins Canvas Platform manages and for plugins installed straight onto an instance, and each decides per plugin:
  - A name without a prefix, or a machine that is not signed in, goes straight to the instance.
  - Otherwise the CLI asks Canvas Platform for the plugin. If Canvas Platform has it, the command goes through Canvas Platform; if not, it goes to the instance.
`--instance` names the target instances for either kind of plugin, and you can repeat it. For a plugin Canvas Platform does not manage, the CLI connects to each `--instance` directly with its `credentials.ini` client. `--host` names a single instance instead, and without either option the command uses the default host from `credentials.ini`; pass `--instance` or `--host`, not both. For a plugin Canvas Platform manages, the CLI refuses `--host`.
An instance accepts direct writes for every plugin, including one Canvas Platform deployed. A `canvas install`, `config set`, `config unset` or `uninstall` that goes straight to the instance changes that instance's copy of the plugin. The next deploy from Canvas Platform installs its own revision over it and replaces the plugin's variables with the values Canvas Platform stores. Canvas Platform can also deploy over a plugin first installed with `canvas install`.
git signs in to Canvas Platform's git server through `canvas git-credential`, a hidden command that `canvas deploy`, `canvas init` and `canvas clone` register as the repository's credential helper. It mints a one-hour git token for the plugin named in the repository path.
##  Update Notifications 
The Canvas CLI automatically checks [PyPI](https://pypi.org/project/canvas/) for newer versions. If an update is available, a notice is printed to standard error after the command output:
    ```shell
    [notice] A newer version of canvas is available (0.112.0 → 0.113.0). Upgrade with: pip install --upgrade canvas
    ```
  - The check runs at most once every 12 hours; the result is cached locally to avoid unnecessary network requests.
  - Because the notice is printed to standard error, it will not interfere with piped or redirected command output.
  - To disable update checks, set the environment variable `CANVAS_NO_UPDATE_CHECK=1`.
##  Checking the SDK/runtime version on an instance 
`canvas --version` reports the version of the locally installed CLI. To find the SDK/runtime version actually running on a given Canvas instance — useful when verifying that an expected SDK change is live — import `version` from `canvas_sdk.handlers.base` inside a plugin running on that instance:
    ```python
    from canvas_sdk.handlers.base import version
    from logger import log
    log.info(f"SDK version: {version}")
    ```
##  Usage 
    ```console
    $ canvas [OPTIONS] COMMAND [ARGS]...
    ```
**Options** :
  - `--version`
  - `--help`: Show this message and exit.
##  Commands 
  - `login`: Sign in to Canvas Platform through your browser
  - `logout`: Sign out of Canvas Platform
  - `whoami`: Show which Canvas Platform you are signed in to, and as whom
  - `init`: Create a new plugin
  - `deploy`: Publish a plugin to Canvas Platform and deploy it
  - `clone`: Clone a plugin's repository from Canvas Platform
  - `uninstall`: Uninstall a plugin
  - `enable`: Enable a plugin from a Canvas instance
  - `disable`: Disable a plugin from a Canvas instance
  - `list`: List all plugins from a Canvas instance
  - `validate`: Validate a plugin's manifest and that all handlers load in the sandbox
  - `validate-manifest`: Validate the Canvas Manifest json file
  - `logs`: Listen and print log streams from a Canvas instance
  - `config list`: List plugin variables on a Canvas instance
  - `config set`: Set plugin variables
  - `config unset`: Clear plugin variables
  - `install`: Install a plugin into a Canvas instance (deprecated; use `deploy`)
###  `canvas login`
Sign in to Canvas Platform through your browser (OAuth authorization code with PKCE). The sign-in URL is also printed, for a machine without a browser. See Signing in to Canvas Platform.
**Usage** :
    ```console
    $ canvas login [OPTIONS]
    ```
**Options** :
  - `--platform TEXT`: Canvas Platform URL. Defaults to `$CANVAS_PLATFORM_URL`, the platform you last signed in to, or https://platform.canvasmedical.com
  - `--help`: Show this message and exit.
###  `canvas logout`
Revoke this machine's Canvas Platform session and delete its stored tokens. A service account token in `CANVAS_PLATFORM_TOKEN` is left alone, and the command says that commands still act as that account.
**Usage** :
    ```console
    $ canvas logout [OPTIONS]
    ```
**Options** :
  - `--platform TEXT`: Canvas Platform URL
  - `--help`: Show this message and exit.
###  `canvas whoami`
Show the Canvas Platform the CLI uses and where that choice came from (`--platform`, `CANVAS_PLATFORM_URL`, your last `canvas login`, or the default), then the account it signs in as, whether the credential is a browser session or a service account token, and each organization's plugin prefix and what you can do there. When `CANVAS_PLATFORM_TOKEN` is set alongside a stored session, it says the token takes precedence.
`whoami` asks Canvas Platform, so a revoked or expired credential is reported rather than shown as signed in. It never prints a token, so it is safe to run in a CI job's log. It exits non-zero when you are not signed in, with the `canvas login` command to run.
**Usage** :
    ```console
    $ canvas whoami [OPTIONS]
    ```
**Options** :
  - `--platform TEXT`: Canvas Platform URL
  - `--help`: Show this message and exit.
###  `canvas init`
Create a new plugin. Signed in to Canvas Platform, the package is named `<org prefix>__<package>`, registered with Canvas Platform, and given a git repository whose `origin` is Canvas Platform, ready for `canvas deploy`. Signed out, it is named from the project name alone and `init` says so: `canvas deploy` refuses such a plugin, so run `canvas login` and `canvas init` again for one you can deploy. Run `canvas whoami` first if you are unsure which platform you are signed in to.
**Usage** :
    ```console
    $ canvas init [OPTIONS] [PLUGIN_TYPE]
    ```
**Arguments** :
  - `PLUGIN_TYPE`: `handler` (default) or `application`
**Options** :
  - `--org TEXT`: Organization that publishes the plugin, when you can publish in several. Without it, `init` asks.
  - `--help`: Show this message and exit.
###  `canvas deploy`
Publish a plugin's code to Canvas Platform and deploy it to one or more instances.
**Usage** :
    ```console
    $ canvas deploy [OPTIONS] PLUGIN_DIR
    ```
**Arguments** :
  - `PLUGIN_DIR`: Path to the plugin package, the folder that holds `CANVAS_MANIFEST.json` [required]
**Options** :
  - `--instance TEXT`: Instance slug to deploy to, repeatable. Without it, `deploy` targets the only instance you can deploy to, and otherwise lists the choices.
  - `--ref TEXT`: Deploy a pushed branch, tag or commit as-is, without pushing.
  - `--no-push`: Deploy the pushed `main` as-is, without pushing.
  - `--push-only`: Push HEAD to `main` without deploying it to any instance, so the plugin's code and its [catalog listing](/sdk/canvas_manifest/#catalog) are updated on Canvas Platform. Takes no `--instance`, `--ref` or `--no-push`.
  - `-y, --yes`: Commit uncommitted changes without prompting, with the default message. Does not approve consent requests.
  - `--help`: Show this message and exit.
**Example** :
    ```console
    $ canvas deploy paperwork-eviscerator/acme__paperwork_eviscerator --instance acme-staging
    ```
**Notes** :
**What`deploy` does**
  1. Checks the manifest `name` is publisher-prefixed and the package folder has the same name, before anything is committed or pushed. Then registers the plugin with Canvas Platform under the organization its prefix names.
  2. Points the repository's `origin` at Canvas Platform, with `canvas` as git's credential helper for it.
  3. Commits uncommitted changes after you confirm. Without a terminal to confirm at, it refuses uncommitted changes unless you pass `--yes`.
  4. Pushes HEAD to `main`, deploys that commit to each instance, and waits for each instance's outcome.
The command exits non-zero unless every instance succeeds, so it can gate a CI job.
**Waiting for the outcome**
For a plugin Canvas Platform manages, `canvas deploy`, `canvas config set`, `canvas config unset` and `canvas uninstall` each create a deployment, wait for it to finish, and print each instance's outcome. They stop waiting after 300 seconds, print a message such as `Deploy of acme__intake is still running after 300s (deployment <id>).`, and exit non-zero. The CLI does not cancel the deployment when it stops waiting.
Canvas Platform sends a plugin only the stored values whose keys the deployed revision's manifest declares in [`variables`](/sdk/canvas_manifest/#variables). When it leaves stored values out, the CLI lists them under that instance's outcome:
    ```text
      acme__intake on acme-staging: succeeded
        Stored values left out because this revision does not declare them: OLD_FLAG
    ```
If the plugin still needs one of these values, declare its key in the manifest and deploy again.
**Plugin repository layout**
Canvas Platform hosts one git repository per plugin, rooted at the directory that contains the package:
    ```text
    paperwork-eviscerator/          # repository root
    ├── acme__paperwork_eviscerator/
    │   ├── CANVAS_MANIFEST.json
    │   ├── OVERVIEW.md             # the plugin's overview in the catalog
    │   └── handlers/
    ├── pyproject.toml
    └── tests/
    ```
`canvas init` creates this layout. If the package is not in a git repository yet, `deploy` offers to create one at its parent directory. A package nested deeper inside a larger repository is refused; move it into its own repository, or `canvas clone` it.
Because `deploy` pushes a git commit, `.gitignore` decides what reaches Canvas Platform. Keep virtual environments, `node_modules` and local secrets out of the repository with it.
**Consent for cross-plugin data access**
A plugin that reads another plugin's [custom data](/sdk/custom-data-sharing-data/) needs consent before it deploys. At a terminal, `deploy` shows each consent request and asks you to answer it. Under `--yes`, or without a terminal, it lists the requests with the deployment id and exits non-zero without answering them.
**Validate first**
Run `canvas validate` before you deploy. It runs the manifest checks, the static lint, and sandbox-load validation locally, where errors are faster to fix than after a push.
###  `canvas clone`
Clone a plugin's repository from Canvas Platform with `origin` and the credential helper set, ready for `canvas deploy`.
**Usage** :
    ```console
    $ canvas clone [OPTIONS] NAME [DIRECTORY]
    ```
**Arguments** :
  - `NAME`: Plugin name, e.g. `acme__intake` [required]
  - `DIRECTORY`: Where to clone it, a directory named after the plugin by default
**Options** :
  - `--help`: Show this message and exit.
###  `canvas install`
> **Warning:** **Deprecated:** `canvas install` uploads a plugin straight onto an instance using `credentials.ini`. Support ends on **December 14, 2026**. Use `canvas deploy`, and see [Moving to Canvas Platform](/guides/moving-to-canvas-platform/).
Install a plugin into a Canvas instance.
**Usage** :
    ```console
    $ canvas install [OPTIONS] PLUGIN_NAME
    ```
**Arguments** :
  - `PLUGIN_NAME`: Path to plugin to install [required]
**Options** :
  - `--variable TEXT`: Non-sensitive variables to set, e.g. Key=value
  - `--secret TEXT`: Sensitive variables to set (treated as sensitive=true), e.g. Key=value
  - `--enable / --disable`: Install the plugin in an enabled or disabled state. Defaults to `--enable`.
  - `--host TEXT`: Canvas instance to connect to
  - `--help`: Show this message and exit.
**Notes** :
**Where to run it**
  - Run it from one directory **above** the plugin folder, the one that holds `CANVAS_MANIFEST.json`, and pass the folder name. If the manifest is at `extensions/encounter_list/CANVAS_MANIFEST.json`, run this from `extensions`:
        ```console
        $ canvas install encounter_list --host your-host
        ```
  - Or run `canvas install .` from inside the plugin folder.
  - The command is `canvas install`. There is no `canvas plugin install`.
**Plugin folder layout**
  - Keep the manifest, the package's `__init__.py`, and the folders it references (such as `routes/` and `protocols/`) in the same directory. Class paths in the manifest, such as `my_plugin.routes.charting`, resolve from there.
  - An extra level of nesting, with the manifest outside the inner package folder, makes those paths resolve one level too deep. The plugin loads, but its SimpleAPI endpoints return an empty 404, often with nothing in `canvas logs`. If that happens, check the folder structure and that every import in the referenced modules resolves.
**Validation before upload**
`canvas install` runs the same checks as `canvas validate` before it uploads anything:
  - Manifest validation (schema, tags, handler resolution)
  - Static lint (scans your source for sandbox-forbidden constructs and Custom Data mistakes)
  - Sandbox-load validation (imports every handler in the sandbox)
If the static lint reports an error, or a handler fails to load (for example, because of a disallowed import like `subprocess`), the install stops before the plugin is built or uploaded. Run `canvas validate` first for detailed per-handler results.
**What gets packaged**
The CLI packages every file in the plugin folder except:
  - `__pycache__` directories
  - `*.pyc` and `*.pyo` files
  - `node_modules` directories
  - Hidden files and directories (for example, `.git` and `.env`)
  - Symlinks
To exclude more files, add a `.canvasignore` file:
  - Put it in the directory you run `canvas install` from. The CLI reads it from the current working directory, not from the plugin folder.
  - It uses [.gitignore](https://git-scm.com/docs/gitignore) syntax, and its patterns match paths relative to the plugin folder.
    ```md
    # Exclude test files
    test_*.py
    ```
The CLI prints a warning, but still installs, when a single file is over 1 MB, the package holds more than 100 files, or its total size is over 1 MB.
**Troubleshooting**
  - **The install fails with an HTTP 500:** the package usually has too many files, most often because a Python virtual environment was created inside the plugin folder. Rename the folder so it starts with a dot (for example, `.canvas-env`), since hidden folders aren't packaged, or list it in `.canvasignore`.
###  `canvas uninstall`
Uninstall a plugin. A plugin Canvas Platform manages is removed by an uninstall deployment from each `--instance`, which is required. Any other plugin is removed from the instance directly, using `credentials.ini` (deprecated; see Instance API credentials).
> **Warning:** Uninstalling a plugin deletes the [banner alerts](/sdk/effect-banner-alerts/) it added to patient charts and [claims](/sdk/effect-claims/#add-banner). Disabling a plugin hides them until it's enabled again.
**Usage** :
    ```console
    $ canvas uninstall [OPTIONS] NAME
    ```
**Arguments** :
  - `NAME`: Plugin name to uninstall [required]
**Options** :
  - `--instance TEXT`: Instance slug to uninstall from, repeatable
  - `--host TEXT`: Canvas instance to connect to, for a plugin Canvas Platform does not manage
  - `--force`: Uninstall an enabled plugin from an instance directly
  - `--help`: Show this message and exit.
###  `canvas enable`
Enable a plugin from a Canvas instance..
**Usage** :
    ```console
    $ canvas enable [OPTIONS] NAME
    ```
**Arguments** :
  - `NAME`: Plugin name to enable [required]
**Options** :
  - `--host TEXT`: Canvas instance to connect to
  - `--help`: Show this message and exit.
###  `canvas disable`
Disable a plugin from a Canvas instance..
**Usage** :
    ```console
    $ canvas disable [OPTIONS] NAME
    ```
**Arguments** :
  - `NAME`: Plugin name to disable [required]
**Options** :
  - `--host TEXT`: Canvas instance to connect to
  - `--help`: Show this message and exit.
###  `canvas list`
List all plugins on a Canvas instance.
**Usage** :
    ```console
    $ canvas list [OPTIONS]
    ```
**Options** :
  - `--host TEXT`: Canvas instance to connect to
  - `--help`: Show this message and exit.
###  `canvas validate`
Validate a plugin's manifest and that all handlers load in the sandbox.
**Usage** :
    ```console
    $ canvas validate [OPTIONS] PLUGIN_NAME
    ```
**Arguments** :
  - `PLUGIN_NAME`: Path to plugin to validate [required]
**Options** :
  - `--help`: Show this message and exit.
This command runs full pre-flight validation combining:
  1. **Manifest validation** — Schema checks, tag validation, handler resolution, and unreferenced handler warnings (everything `validate-manifest` does).
  2. **Static lint** — Scans the plugin's source for sandbox-forbidden constructs and Custom Data mistakes before any code runs.
  3. **Sandbox-load validation** — Imports every handler the way the plugin runner will, catching violations that would otherwise surface only at runtime on the instance.
####  Static lint 
Before it loads any handlers, `canvas validate` scans every `.py` file in the plugin — skipping directories like `tests`, `build`, and `dist` _within_ the plugin — for patterns that compile cleanly but fail, or silently misbehave, once your code runs on the instance. Each finding is reported with a rule code in brackets. Warnings are printed but do not block validation; any error fails the command and exits with code 1.
    ```console
    $ canvas validate my_plugin
      ⚠ my_plugin/handlers/protocol.py:42  [custom-model-id-vs-dbid]  Widget.objects.filter(id=…) — CustomModels use `dbid` as their primary key (only core SDK models have `id`). Use `dbid=…` instead.
    These issues will fail on the instance (sandbox / Custom Data):
      ✗ my_plugin/handlers/protocol.py:18  [type-blocked]  `type()` takes one argument in the sandbox. Declare classes with `class … :` rather than `type(name, bases, dict)`.
    ```
**Sandbox constructs (errors).** These compile under RestrictedPython but are rejected when a handler runs on the instance, so a plain sandbox load can miss them. See [Sandboxing and Allowed Imports](/sdk/sandboxing-and-allowed-imports/#forbidden-constructs) for the full list and the allowed alternatives.
Rule code| Flags  
---|---  
`type-blocked`| A `type()` call with anything other than a single argument, such as `type(name, bases, dict)`. The sandbox's `type` takes one argument, so declare classes with `class …:` instead. `type(x)` is not flagged.  
`augmented-subscript`| Augmented assignment on a subscript, e.g. `d[k] += v` — rewrite as `d[k] = d[k] + v`  
`augmented-attribute`| Augmented assignment on an attribute, e.g. `obj.attr += v` — rewrite as `obj.attr = obj.attr + v`  
`@dataclass(frozen=True)` and `@dataclass(slots=True)` load and run fine in the sandbox and are intentionally not flagged.
**Custom Data (errors).** Both leave tables silently uncreated, so queries fail at runtime. See [Custom Models](/sdk/custom-data-custom-models/) and the [Quick Start](/sdk/custom-data-quick-start/) for setup.
Rule code| Flags  
---|---  
`custom-model-wrong-dir`| A `CustomModel` subclass defined outside `<plugin>/models/` — Canvas only loads models from that directory  
`missing-custom-data-block`| CustomModels are present but the manifest has no `custom_data` block (an empty block counts as missing — it must be non-empty)  
**Custom Data (warnings).** These don't block validation but usually indicate a bug:
Rule code| Flags  
---|---  
`custom-model-id-vs-dbid`| `.filter(id=…)` / `.get(id=…)` on a local CustomModel — CustomModels key on `dbid`, not `id`. Use `dbid=…`  
`lazy-fk-string-ref`| A `ForeignKey`/`OneToOneField`/`ManyToManyField` with a string reference to a CustomModel defined in this plugin — import the class and pass it directly  
####  Sandbox-load validation 
After the static lint passes, sandbox-load validation executes each handler module in the plugin sandbox to catch:
  - **Disallowed imports** — Modules like `subprocess`, `socket`, or `os` that are blocked by the sandbox.
  - **RestrictedPython compile-time errors** — Syntax or constructs that RestrictedPython cannot compile.
  - **Import errors** — Missing dependencies or broken imports.
  - **Refused code in helper modules** — Functions in the modules your handlers import that contain code the sandbox refuses. Every handler fails with a `PluginInstallationError` listing each construct by module and line. See [Helper modules](/sdk/sandboxing-and-allowed-imports/#helper-modules).
For each handler, the output shows whether it loaded successfully:
    ```console
    $ canvas validate my_plugin
    Loading 2 handler(s) in the sandbox:
      ✓ my_plugin.handlers.events:MyHandler
      ✗ my_plugin.handlers.api:APIHandler
        ImportError: 'subprocess' is not an allowed import
    1 of 2 handler(s) failed to load in the sandbox.
    ```
The command exits with code 1 if any handler fails validation.
If your handlers read attributes that don't exist while they load, the output ends with a warning that lists them. In the sandbox those reads return `None` for now, and a future release will raise `AttributeError` instead (see [Attributes that don't exist](/sdk/sandboxing-and-allowed-imports/#attributes-that-dont-exist)). The warning doesn't fail validation:
    ```console
    $ canvas validate my_plugin
    Loading 1 handler(s) in the sandbox:
      ✓ my_plugin.handlers.events:MyHandler
    Warning: these names do not exist. Each reads as None today and will raise an AttributeError in a future release:
      - Settings.retry_limit
    ```
####  Limitations 
A passing `canvas validate` confirms that handlers import cleanly under the sandbox — it does not guarantee the plugin is fully sandbox-clean. RestrictedPython checks attribute and item access inside `compute()` at request time, not at import time, so violations during handler execution won't be caught by this command.
> **Info:** Run `canvas validate` before `canvas deploy` so violations are caught on your machine before they reach an instance.
###  `canvas validate-manifest`
Validate the Canvas Manifest json file.
**Usage** :
    ```console
    $ canvas validate-manifest [OPTIONS] PLUGIN_NAME
    ```
**Arguments** :
  - `PLUGIN_NAME`: Path to plugin to validate [required]
**Options** :
  - `--help`: Show this message and exit.
**Validations performed** :
  1. **Schema validation** — Checks that `CANVAS_MANIFEST.json` contains all required fields and valid values.
  2. **Handler resolution** — Verifies that every handler class declared in the manifest (`protocols`, `applications`, and `handlers`) resolves to a file the plugin runner can find at runtime.
####  Handler resolution and directory layout 
The plugin runner loads handlers by mapping dotted module paths to files relative to the plugin's install directory. For a plugin named `my_plugin` with a handler class `my_plugin.handlers.events:MyHandler`, the runner expects `handlers/events.py` inside the plugin directory — the directory containing `CANVAS_MANIFEST.json`.
A common mistake is placing `CANVAS_MANIFEST.json` in a parent directory above the plugin package. This passes schema validation and works locally, but fails at runtime with `ModuleNotFoundError` — the handler files are nested one level too deep.
**Correct layout:**
    ```text
    my_plugin/
    ├── CANVAS_MANIFEST.json   # ← manifest inside the package
    ├── handlers/
    │   └── events.py
    └── ...
    ```
**Incorrect layout:**
    ```text
    project/
    ├── CANVAS_MANIFEST.json   # ← manifest above the package (wrong!)
    └── my_plugin/
        └── handlers/
            └── events.py
    ```
If `validate-manifest` detects handlers that won't resolve, it reports which classes are affected and the file paths the runner expects:
    ```console
    Error: these handler classes won't be found by the plugin runner with the current directory layout:
      - my_plugin.handlers.events:MyHandler
        runner expects: my_plugin/handlers/events.py
    CANVAS_MANIFEST.json must live inside the plugin's package directory (the directory whose name matches the manifest "name"), alongside the handler packages — not in a parent directory above them.
    ```
> **Info:** Use `canvas validate` before `canvas deploy` for a full pre-flight check: manifest validation, the static lint, and sandbox-load validation, with detailed per-handler output.
###  `canvas logs`
Subscribes to a log stream and prints to your console. Optionally fetches historical logs first.
**Usage** :
    ```console
    $ canvas logs [OPTIONS]
    ```
**Options** :
  - `--host TEXT`: Canvas instance to connect to
  - `--help`: Show this message and exit.
  - `--since TEXT`: Lookback window (e.g. '24h', '2h30m'). Mutually exclusive with –start/–end.
  - `--start TEXT`: Start time (ISO/RFC3339) or 'now'.
  - `--end TEXT`: End time (ISO/RFC3339) or 'now'. Defaults to now if start is provided.
  - `--no-follow`: Historical only; do not stream live logs.
  - `--level TEXT`: Repeatable. –level ERROR –level WARN
  - `--source TEXT`: Filter by source/service.
  - `--plugin TEXT`: Repeatable. –plugin foo –plugin bar.
  - `--handler TEXT`: Repeatable. Qualified handler name (e.g. my_plugin.handlers.Foo).
  - `--page-size INTEGER`: Fetch size per page (historical). [default: 200]
  - `--limit INTEGER`: Max historical logs to print.
  - `--all`: Fetch all pages until exhausted (historical).
  - `--interactive`: After each page, prompt to load more.
  - `--cursor TEXT`: Resume token from a previous run.
  - `--help`: Show this message and exit.
###  `canvas config list`
List plugin variables on a Canvas instance. Each variable is rendered as `[set]` or `[not set]`, with a `(sensitive)` annotation for sensitive variables. Values themselves are never displayed — to read a value, use the Django Admin UI (gated by managing-user permissions).
**Usage** :
    ```console
    $ canvas config list [OPTIONS] PLUGIN
    ```
**Example output** :
    ```console
    $ canvas config list my_plugin
      API_TOKEN  [set]  (sensitive)
      LOG_LEVEL  [not set]
    ```
**Arguments** :
  - `PLUGIN`: Plugin name to list variables for
**Options** :
  - `--host TEXT`: Canvas instance to connect to
  - `--help`: Show this message and exit.
**Example Output** :
    ```console
    $ canvas config list my_plugin
      API_TOKEN = [set]  (sensitive)
      WEBHOOK_URL = [set]
      DEBUG_MODE = [not set]
    ```
###  `canvas config set`
Set (or update) one or more plugin variables. Pass one or more `KEY=value` pairs as positional arguments.
For a plugin Canvas Platform manages, the values are stored in Canvas Platform and a configure deployment brings them to the running plugin on each `--instance`. Without `--instance`, the only instance the plugin is installed on that you can configure is targeted. Values are kept per instance, and a later `canvas deploy` carries them forward for the keys that revision declares; see Waiting for the outcome.
For a plugin Canvas Platform does not manage, the values are written to the instance directly with `credentials.ini` (deprecated; see Instance API credentials).
**Usage** :
    ```console
    $ canvas config set [OPTIONS] PLUGIN [KEY=VALUE]...
    ```
**Examples** :
Set a single variable:
    ```console
    $ canvas config set acme__my_plugin API_TOKEN=your_api_token_value --instance acme-staging
    ```
Set multiple variables in one call:
    ```console
    $ canvas config set acme__my_plugin API_TOKEN=abc123 LOG_LEVEL=info --instance acme-staging
    ```
Set a variable whose value is a list with one entry per line — for example a redirect allowlist (see the [Redirect effect](/sdk/effect-redirect/)). The value is newline-delimited (not comma-separated), so use your shell's newline quoting to preserve the line breaks. In bash/zsh, ANSI-C quoting (`$'…'`) turns `\n` into a real newline:
    ```console
    $ canvas config set acme__my_plugin $'REDIRECT_ALLOWLIST_INTERNAL=/panel\n/patient' --instance acme-staging
    ```
**Arguments** :
  - `PLUGIN`: Plugin name to set variables for
  - `KEY=VALUE...`: Variables to set, keeping each one's declared sensitivity
**Options** :
  - `--instance TEXT`: Instance slug to configure, repeatable
  - `--secret KEY=VALUE`: Set a sensitive value for a key no revision of the manifest declares, repeatable
  - `--variable KEY=VALUE`: Set a non-sensitive value for a key no revision of the manifest declares, repeatable
  - `--host TEXT`: Canvas instance to connect to, for a plugin Canvas Platform does not manage
  - `--help`: Show this message and exit.
> Whether each value is treated as sensitive is determined by the plugin's `CANVAS_MANIFEST.json` (`variables: [{name, sensitive}]`) — `canvas config set` does not change the sensitive flag of a declared variable.
###  `canvas config unset`
Clear one or more plugin variables. For a plugin Canvas Platform manages, the values are cleared in Canvas Platform and a configure deployment removes them from the running plugin. For any other plugin, each value is set to empty on the instance directly.
**Usage** :
    ```console
    $ canvas config unset [OPTIONS] PLUGIN KEY...
    ```
**Arguments** :
  - `PLUGIN`: Plugin name to clear variables for
  - `KEY...`: Variable keys to clear, e.g. `API_KEY`
**Options** :
  - `--instance TEXT`: Instance slug to configure, repeatable
  - `--host TEXT`: Canvas instance to connect to, for a plugin Canvas Platform does not manage
  - `--help`: Show this message and exit.

---

# Canvas Manifest

Source: https://docs.canvasmedical.com/sdk/canvas_manifest/

Every plugin has a `CANVAS_MANIFEST.json` file at the root of its package. The manifest names the plugin, lists the handlers and applications Canvas loads, and declares the variables, URL permissions, and custom data namespace the plugin needs.
The manifest is validated against a JSON schema when you run [`canvas validate`](/sdk/canvas_cli/#canvas-validate), or [`canvas validate-manifest`](/sdk/canvas_cli/#canvas-validate-manifest), and Canvas Platform checks it again on every [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy) push. Unknown top-level keys and unknown component types fail validation.
##  Where the manifest lives 
[`canvas init`](/sdk/canvas_cli/#canvas-init) creates a project with the plugin package inside it. The manifest sits at the top of the package directory, next to the plugin's code, and every path in the manifest (handler classes, icons, templates, the README) is relative to that directory.
    ```text
    my_plugin/                       # project directory
    ├── pyproject.toml
    ├── tests/
    │   └── test_event_handlers.py
    └── acme__my_plugin/             # plugin package
        ├── CANVAS_MANIFEST.json
        ├── OVERVIEW.md
        ├── README.md
        ├── __init__.py
        ├── assets/
        │   └── icon.png
        ├── handlers/
        │   ├── __init__.py
        │   └── event_handlers.py
        └── templates/
            └── intake_form.yml
    ```
A handler in `acme__my_plugin/handlers/event_handlers.py` is referenced as `acme__my_plugin.handlers.event_handlers:ClassName`, and the icon as `assets/icon.png`. Pass the package directory, the one that holds `CANVAS_MANIFEST.json`, to `canvas validate` and `canvas deploy`: `canvas validate my_plugin/acme__my_plugin` from outside the project, or `canvas validate acme__my_plugin` from inside it.
Canvas runs only the handlers and applications the manifest lists. A handler class in the package that the manifest doesn't reference is never loaded, and `canvas validate` warns about each one it finds. Every other file in the package directory still ships with the plugin, so your handlers can import your own modules and read templates and assets without listing them in the manifest. `canvas deploy` ships the files committed to the plugin's git repository, so `.gitignore` decides what is left out. See [Plugin repository layout](/sdk/canvas_cli/#canvas-deploy).
##  Basic structure 
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "0.0.1",
      "name": "acme__my_plugin",
      "description": "A description of what this plugin does",
      "components": {
        "handlers": [],
        "applications": [],
        "commands": [],
        "questionnaires": []
      },
      "variables": [],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
##  Top-level fields 
Field| Type| Required| Description  
---|---|---|---  
`sdk_version`| string| Yes| The Canvas SDK version the plugin was built against.  
`plugin_version`| string| Yes| The plugin's version. Must not be empty. Increase it on every deploy. See Versioning your plugin.  
`name`| string| Yes| The plugin's name, which is also its package folder name. For a plugin deployed through Canvas Platform it is publisher-prefixed, `<org prefix>__<package>` (for example `acme__intake`): lowercase letters, digits and underscores, starting with a letter on both sides of the double underscore. `canvas login` lists your organizations' prefixes.  
`description`| string| Yes| What the plugin does, in one sentence. The Canvas Platform catalog shows it under the plugin's title and on its card.  
`components`| object| Yes| The handlers, applications, commands, and questionnaires the plugin provides. Must contain at least one component type. See Components.  
`tags`| object| Yes| Categorization tags. Can be empty (`{}`). See Tags.  
`license`| string| Yes| A license identifier such as `"MIT"`, or an empty string.  
`readme`| string or boolean| Yes| Path to the plugin's README, or `false`.  
`variables`| array| No| Configuration values and secrets the plugin reads at runtime. See Variables.  
`secrets`| array| No| Deprecated. Use `variables` instead.  
`url_permissions`| array| No| External URLs the plugin's iframes may load, and what each may do. See URL permissions.  
`origins`| object| No| Legacy form of `url_permissions`.  
`custom_data`| object| No| The custom data namespace the plugin uses. See Custom data.  
`catalog`| object| No| The plugin's listing in the Canvas Platform plugin catalog. See Catalog.  
`references`| array of strings| No| Links to related documentation or resources.  
`diagram`| string or boolean| No| Path to an architecture or workflow diagram, or `false`.  
###  Versioning your plugin 
Change `plugin_version` every time you deploy a new build, including builds sent only to a test instance. Canvas accepts a redeploy with an unchanged version, so the version is the only way to tell which build an instance is running. It appears in:
  - the Plugins list in the Canvas Admin
  - `canvas list`, as `name@version`
  - the log lines written when the plugin is installed and loaded, for example `Successfully loaded plugin "acme__my_plugin", version 1.4.0`
Use [semantic versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`):
Change| Bump| Example  
---|---|---  
A fix that doesn't change behavior users rely on| `PATCH`| `1.4.0` → `1.4.1`  
New functionality that leaves existing behavior in place| `MINOR`| `1.4.1` → `1.5.0`  
A change that breaks existing behavior, such as a renamed variable, a removed handler, or a changed custom data model| `MAJOR`| `1.5.0` → `2.0.0`  
####  Versioning with git 
`canvas deploy` deploys a commit pushed to the plugin's git repository on Canvas Platform, so every build on an instance maps to a commit. Tie each version to that history:
  - **Bump the version in the commit or pull request that changes the code.** Each merged change then carries its own version, and a reviewer can see what the new number ships.
  - **Tag the commit you release** (for example `git tag v1.5.0`, then `git push origin v1.5.0`). A version seen in the logs or the Admin then leads straight to the source that produced it, `git diff v1.4.1 v1.5.0` shows what changed between two releases, and `canvas deploy <package dir> --ref v1.5.0 --instance <instance>` deploys exactly that tag.
To tell test builds apart without spending release numbers, add a pre-release suffix such as `1.5.0-rc.1` or `1.5.0-dev.3`, and drop the suffix for the build you release.
##  Components 
The `components` object groups everything Canvas loads from your plugin. Each key holds a list, and the object must contain at least one key.
Key| Holds  
---|---  
`handlers`| Classes that respond to Canvas events and serve plugin APIs.  
`applications`| Applications that appear in the Canvas UI.  
`commands`| Custom commands the plugin adds to notes.  
`questionnaires`| Questionnaire templates Canvas creates on install.  
###  Handlers 
Handlers respond to Canvas events: [event handlers](/sdk/handlers-basehandler/), [SimpleAPI](/sdk/handlers-simple-api/) endpoints, [CronTasks](/sdk/handlers-crontask/), [action buttons](/sdk/handlers-action-buttons/), [embedded applications](/sdk/handlers-embedded-applications/), and the rest of the [handler types](/sdk/handlers/).
`protocols` is deprecated in favor of `handlers`. Canvas still loads classes listed under `protocols`, so existing plugins keep working, but new plugins should use `handlers`. To migrate, rename the key. The entries inside it stay the same.
Field| Type| Required| Description  
---|---|---|---  
`class`| string| Yes| Import path to the handler class, in `package.module:ClassName` form.  
`description`| string| Yes| What the handler does.  
`meta`| object| No| Handler metadata. Used by clinical quality measure protocols.  
`data_access`| object| No| Accepted by the schema with `event`, `read`, and `write` keys, but not enforced. A handler's data access is not limited by this field.  
    ```json
    {
      "components": {
        "handlers": [
          {
            "class": "acme__my_plugin.handlers.patient_sync:PatientSync",
            "description": "Sends patient updates to an external system"
          }
        ]
      }
    }
    ```
###  Applications 
Applications add entry points to the Canvas UI. See [Applications](/sdk/handlers-applications/) for where each one appears and the handler that runs when a user opens it.
Field| Type| Required| Description  
---|---|---|---  
`class`| string| Yes| Import path to the `Application` subclass, in `package.module:ClassName` form.  
`name`| string| Yes| Display name. Up to 32 characters.  
`description`| string| Yes| What the application does. Up to 256 characters.  
`icon`| string| Yes| Path to an image inside the plugin package, or an `https://` URL to one. Rendered at 48 × 48 px.  
`scope`| string| Yes| Where the application appears. See [Application Scopes](/sdk/handlers-applications/#application-scopes) for the values.  
`menu_position`| string| No| `"top"` or `"bottom"`. Defaults to `"top"`.  
`menu_order`| integer| No| Order of the application within its menu position. Lower numbers appear first.  
`show_in_panel`| boolean| No| Shows the application alongside the panel buttons instead of in the app drawer. Defaults to `false`.  
`panel_priority`| integer| No| Order of the application among panel applications.  
    ```json
    {
      "components": {
        "applications": [
          {
            "class": "acme__my_plugin.applications.risk_calculator:RiskCalculator",
            "name": "Risk Calculator",
            "description": "Calculates cardiovascular risk for the open patient",
            "icon": "assets/risk_calculator.png",
            "scope": "patient_specific",
            "show_in_panel": true,
            "panel_priority": 100
          }
        ]
      }
    }
    ```
Embedded applications (note applications, scheduling applications, and docked applications) are declared under `handlers`, not `applications`, and take no `scope` or `icon`. See [Embedded Applications](/sdk/handlers-embedded-applications/).
###  Commands 
The `commands` list declares [custom commands](/sdk/commands-custom-command/): commands with plugin-rendered HTML content that can be added to a note.
Field| Type| Required| Description  
---|---|---|---  
`name`| string| Yes| Unique name for the command.  
`schema_key`| string| Yes| Identifier the `CustomCommand` effect uses to refer to this command. Must be unique across every plugin installed on the instance, or installation fails.  
`label`| string| No| Label shown in the Canvas UI.  
`section`| string| No| Note section the command belongs to: `subjective`, `objective`, `assessment`, `plan`, `procedures`, `history`, or `internal`.  
    ```json
    {
      "components": {
        "commands": [
          {
            "name": "RiskAssessment",
            "label": "Risk Assessment",
            "schema_key": "myPluginRiskAssessment",
            "section": "assessment"
          }
        ]
      }
    }
    ```
###  Questionnaires 
The `questionnaires` list points at YAML templates in the plugin package. Canvas creates each questionnaire when the plugin is installed. See [Questionnaires](/sdk/effect-questionnaires/#manifest-yaml-template) for the template format.
Field| Type| Required| Description  
---|---|---|---  
`template`| string| Yes| Path to the questionnaire's YAML template inside the plugin package.  
    ```json
    {
      "components": {
        "questionnaires": [
          {
            "template": "templates/intake_form.yml"
          }
        ]
      }
    }
    ```
###  Content, effects, and views 
`content`, `effects`, and `views` are accepted for compatibility and have no effect. `canvas init` adds them as empty lists, and you can remove them.
##  Variables 
`variables` declares the configuration values and secrets a plugin reads from `self.secrets` at runtime. Values are set per instance with [`canvas config set`](/sdk/canvas_cli/#canvas-config-set). See [Managing Variables](/sdk/secrets/).
`namespace_read_access_key` and `namespace_read_write_access_key` are reserved for a plugin deployed through Canvas Platform: Canvas Platform supplies them to plugins entitled to a custom data namespace, and refuses a manifest that declares them.
Field| Type| Required| Description  
---|---|---|---  
`name`| string| Yes| The key the value is read under in `self.secrets`.  
`sensitive`| boolean| No| When `true`, the value is hidden in the Admin UI and CLI listings. Defaults to `false`.  
`default`| string| No| Accepted by the schema for non-sensitive variables only. Canvas does not pre-fill the variable with it, so set the value with `canvas config set`.  
    ```json
    {
      "variables": [
        {"name": "API_TOKEN", "sensitive": true},
        {"name": "API_BASE_URL"}
      ]
    }
    ```
The older `secrets` field is a list of names, each treated as a non-sensitive variable. `canvas validate-manifest` prints a deprecation warning when a manifest uses it.
    ```json
    {
      "secrets": ["API_TOKEN"]
    }
    ```
##  URL permissions 
A [`LaunchModalEffect` or `PortalWidget`](/sdk/layout-effect/#additional-configuration) only loads URLs and external scripts listed in `url_permissions`. Each entry names a URL and the iframe capabilities it is granted.
Field| Type| Required| Description  
---|---|---|---  
`url`| string| Yes| The URL to allow, in [CSP host-source](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source) format.  
`permissions`| array of strings| Yes| Capabilities granted to the URL. Can be empty.  
Permission| Grants  
---|---  
`SCRIPTS`| JavaScript execution  
`ALLOW_SAME_ORIGIN`| Same-origin access  
`MICROPHONE`| Microphone access  
`CAMERA`| Camera access  
`CLIPBOARD_READ`| Reading from the clipboard  
`CLIPBOARD_WRITE`| Writing to the clipboard  
    ```json
    {
      "url_permissions": [
        {
          "url": "https://example.com",
          "permissions": ["SCRIPTS", "ALLOW_SAME_ORIGIN", "MICROPHONE"]
        }
      ]
    }
    ```
See [Additional Configuration](/sdk/layout-effect/#additional-configuration) on the layout effects page for when each permission is needed.
###  Origins (legacy) 
`origins` is the older form of `url_permissions`. A manifest can use one or the other, not both. Canvas converts each `urls` entry to a URL with no permissions and each `scripts` entry to a URL with `SCRIPTS`.
    ```json
    {
      "origins": {
        "urls": ["https://example.com"],
        "scripts": ["https://cdn.example.com"]
      }
    }
    ```
##  Custom data 
`custom_data` declares the namespace a plugin stores [custom data](/sdk/custom-data/) in, and whether it can write to it. See the [Custom Data Quick Start](/sdk/custom-data-quick-start/).
Field| Type| Required| Description  
---|---|---|---  
`namespace`| string| Yes| Namespace name in `org__name` form: lowercase letters, digits, and underscores, with a double underscore between the two parts. Up to 63 characters.  
`access`| string| Yes| `"read"` for read-only access, or `"read_write"`.  
    ```json
    {
      "custom_data": {
        "namespace": "my_org__my_plugin",
        "access": "read_write"
      }
    }
    ```
##  Catalog 
`catalog` is the plugin's listing in the Canvas Platform plugin catalog. Canvas Platform reads it from the manifest each time a push moves the plugin's `main` branch, so the listing ships with the code it describes; pushes to other branches and tags leave the catalog as it is. It refuses a push whose listing breaks the rules below. [`canvas deploy --push-only`](/sdk/canvas_cli/#canvas-deploy) updates the listing without deploying to an instance, and `canvas validate` checks it locally.
    ```json
    {
      "catalog": {
        "title": "Intake Summary",
        "kind": "plugin",
        "category": "Charting",
        "surfaces": ["Note"],
        "keywords": ["intake", "summary"],
        "screenshots": [
          {"path": "assets/summary.png", "caption": "In the note", "alt": "An intake summary in a note"}
        ],
        "pricing": [
          {"unit": "visit", "price_per_unit": "1.50"},
          {"unit": "token"}
        ],
        "vendors": [
          {"name": "Twilio", "relationship": "self_managed", "additional_fees": true}
        ],
        "icon": "assets/icon.png",
        "setup_guide": "setup_guide.md",
        "setup_instructions": "setup_instructions.md",
        "release_notes": {"kind": "fix", "title": "Summaries keep their line breaks"}
      }
    }
    ```
Field| Type| Required| Description  
---|---|---|---  
`title`| string| Yes| The name on the plugin's card and page. At most 64 characters.  
`category`| string| Yes| One of `Billing & RCM`, `Charting`, `Decision support`, `Interoperability`, `Labs & devices`, `Operations`, `Patient engagement`, `Population health`, `Prescribing`, `Scheduling`.  
`surfaces`| array| Yes| Every place in Canvas the plugin's work shows up, at least one and none repeated: `Note`, `Chart app`, `Command`, `Background`, `Patient portal`, `Waffle`.  
`kind`| string| No| `agent` for a plugin that calls a model and acts with latitude, or `plugin` for a deterministic one. Defaults to `plugin`.  
`agent`| object| When `kind` is `agent`| The agent's boundary: `does`, `does_not`, `runs_when` (text) and `models` (at least one model name). A `plugin` must leave it out.  
`keywords`| array| No| Free search terms, separate from Tags: lowercase letters, digits and hyphens, up to 32 characters each.  
`screenshots`| array| No| Up to eight images, in display order. Each has a `path` ending in `.png`, `.jpg`, `.jpeg` or `.webp` in lowercase, a required `alt` of at most 200 characters, and an optional `caption` of at most 40.  
`pricing`| array| No| What Canvas charges, up to 10 components in the order the plugin's page lists them. Each has a `unit` in the singular (at most 40 characters, named once) and a `price_per_unit`: a string of US dollars such as `"5.75"`, with at most four decimal places. The `token` unit takes no price, because the inference gateway prices tokens by model. Leave `pricing` out for a plugin with no charge.  
`vendors`| array| No| The third parties the plugin depends on, up to 10. Each has a `name` (at most 64 characters, named once), a `relationship` of `canvas_managed` (Canvas sets up the account) or `self_managed` (the customer does), and `additional_fees`: `true` when the vendor bills the customer directly for its own fees, separately from Canvas.  
`icon`| string| No| Path to the image shown beside the title on the plugin's card, ending in `.png`, `.jpg`, `.jpeg` or `.webp` in lowercase.  
`setup_guide`| string| No| Path to a markdown file describing setup for the person deciding whether to install the plugin: what to have ready, the steps, how long it takes. The plugin's page shows it under How setup works.  
`setup_instructions`| string| No| Path to a file that Studio's agent reads when an organization installs the plugin. It is not shown on the plugin's page.  
`release_notes`| object| No| What changed in this `plugin_version`: `kind` (`fix`, `performance` or `breaking`), `title`, and an optional `body`. Canvas Platform assembles the history from every pushed revision.  
Every path is inside the package folder: no leading `/`, no `..` anywhere in it, and no backslash. Unknown fields are refused at every level, and optional fields are left out rather than set to `null`.
Someone holding the Publisher role in the plugin's organization can also edit the listing from the plugin's page in the Canvas Platform catalog, including the `description`. Saving there is a commit to `main` with the listing changed and a patch bump of `plugin_version`, so pull before your next push. The edit is refused unless `plugin_version` on `main` is a plain `MAJOR.MINOR.PATCH` version, so a pre-release suffix such as `1.5.0-rc.1` blocks it.
An `OVERVIEW.md` file beside `CANVAS_MANIFEST.json` in the package folder is the plugin's overview, and needs no field in `catalog`. When it is there, the plugin's page shows it as rendered markdown beside the plugin's pricing and setup. `canvas init` creates one to start from.
##  Tags 
Tags categorize a plugin. Unrecognized tag categories and values produce warnings during validation rather than errors.
Category| Allowed values  
---|---  
`patient_sourcing_and_intake`| `symptom_triage`, `coverage_capture`  
`interaction_modes_and_utilization`| `supply_policies`, `demand_policies`, `auto_followup`  
`content`| `patient_intake`  
`diagnostic_range_and_inputs`| None yet. Use an empty list.  
`pricing_and_payments`| None yet. Use an empty list.  
`care_team_composition`| None yet. Use an empty list.  
`interventions_and_safety`| None yet. Use an empty list.  
    ```json
    {
      "tags": {
        "patient_sourcing_and_intake": ["symptom_triage"]
      }
    }
    ```
##  Complete example 
A plugin with a patient chart application, the SimpleAPI handler that serves it, a custom command, and a sensitive variable:
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "1.0.0",
      "name": "risk_calculator",
      "description": "Calculates clinical risk scores for patients",
      "url_permissions": [
        {
          "url": "https://risk.example.com",
          "permissions": ["SCRIPTS", "ALLOW_SAME_ORIGIN"]
        }
      ],
      "components": {
        "applications": [
          {
            "class": "risk_calculator.applications.calculator:RiskCalculatorApp",
            "name": "Risk Calculator",
            "description": "Calculates cardiovascular risk for the open patient",
            "icon": "assets/risk_calculator.png",
            "scope": "patient_specific",
            "show_in_panel": true,
            "panel_priority": 100
          }
        ],
        "handlers": [
          {
            "class": "risk_calculator.handlers.api:RiskCalculatorAPI",
            "description": "Serves the calculator page and its data"
          }
        ],
        "commands": [
          {
            "name": "RiskAssessment",
            "label": "Risk Assessment",
            "schema_key": "riskCalculatorAssessment",
            "section": "assessment"
          }
        ]
      },
      "variables": [
        {"name": "RISK_API_TOKEN", "sensitive": true}
      ],
      "tags": {},
      "references": [],
      "license": "MIT",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
##  Validation 
Validate a manifest with the [Canvas CLI](/sdk/canvas_cli/):
    ```bash
    canvas validate acme__my_plugin
    ```
`canvas validate` checks the manifest against the schema and then loads every handler in the plugin sandbox, which catches disallowed imports and other errors that only appear on the instance. `canvas validate-manifest my_plugin` runs the manifest checks alone.

---

# AWS S3

Source: https://docs.canvasmedical.com/sdk/clients-aws-s3/

The Canvas SDK AWS S3 client provides a simple interface for interacting with Amazon S3 storage, including uploading, downloading, listing, and deleting objects, as well as generating presigned URLs for temporary access.
##  Requirements 
  - **AWS Access Key ID** : Your AWS access key
  - **AWS Secret Access Key** : Your AWS secret key
  - **AWS Region** : The region where your bucket is located (e.g., `us-east-1`)
  - **S3 Bucket Name** : The name of your S3 bucket
##  Imports 
The AWS S3 client is included in the Canvas SDK. Import the necessary components:
    ```python
    from canvas_sdk.clients.aws import S3, Credentials, S3Item
    ```
Or import from specific modules:
    ```python
    from canvas_sdk.clients.aws.libraries import S3
    from canvas_sdk.clients.aws.structures import Credentials, S3Item
    ```
##  Initialize the Client 
    ```python
    from canvas_sdk.clients.aws import S3, Credentials
    credentials = Credentials(
        key="your_aws_access_key_id",
        secret="your_aws_secret_access_key",
        region="us-east-1",
        bucket="your-bucket-name"
    )
    client = S3(credentials)
    ```
##  Check if Client is Ready 
    ```python
    if client.is_ready():
        print("S3 client is configured and ready")
    else:
        print("Missing credentials")
    ```
##  Upload a Text File 
    ```python
    from canvas_sdk.clients.aws import S3, Credentials
    credentials = Credentials(
        key="your_access_key",
        secret="your_secret_key",
        region="us-east-1",
        bucket="my-bucket"
    )
    client = S3(credentials)
    # Upload text content
    response = client.upload_text_to_s3("path/to/file.txt", "Hello, World!")
    if response and response.status_code == 200:
        print("Text file uploaded successfully!")
    ```
##  Upload a Binary File 
    ```python
    # Upload binary content (e.g., an image)
    with open("local_image.png", "rb") as f:
        binary_data = f.read()
    response = client.upload_binary_to_s3(
        "images/uploaded_image.png",
        binary_data,
        "image/png"
    )
    if response and response.status_code == 200:
        print("Binary file uploaded successfully!")
    ```
##  Download a File 
    ```python
    response = client.access_s3_object("path/to/file.txt")
    if response:
        content = response.content
        print(f"Downloaded content: {content.decode('utf-8')}")
    ```
##  List Objects in Bucket 
    ```python
    # List all objects with a prefix
    items = client.list_s3_objects("documents/")
    if items:
        for item in items:
            print(f"Key: {item.key}, Size: {item.size} bytes, Modified: {item.last_modified}")
    ```
##  Delete an Object 
    ```python
    response = client.delete_object("path/to/file.txt")
    if response and response.status_code == 204:
        print("Object deleted successfully!")
    ```
##  Generate a Presigned URL 
    ```python
    # Generate a URL valid for 1 hour (3600 seconds)
    url = client.generate_presigned_url("path/to/file.txt", expiration=3600)
    if url:
        print(f"Presigned URL: {url}")
    ```
##  S3 
The main class for interacting with AWS S3.
###  Constructor 
    ```python
    S3(credentials: Credentials)
    ```
Parameter| Type| Description  
---|---|---  
`credentials`| `Credentials`| AWS credentials for S3 access  
###  Methods 
####  `is_ready() -> bool`
Check if all required credentials are provided.
**Returns:** `True` if all credentials (key, secret, region, bucket) are non-empty, `False` otherwise.
####  `access_s3_object(object_key: str) -> Response | None`
Download an object from S3.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`object_key`| `str`| S3 object key (path) to access  
**Returns:** `requests.Response` containing the object data, or `None` if credentials are not ready.
####  `upload_text_to_s3(object_key: str, data: str) -> Response | None`
Upload text data to S3 as `text/plain`.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`object_key`| `str`| S3 object key (path) to create/update  
`data`| `str`| Text content to upload  
**Returns:** `requests.Response` from S3, or `None` if credentials are not ready.
####  `upload_binary_to_s3(object_key: str, binary_data: bytes, content_type: str) -> Response | None`
Upload binary data to S3.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`object_key`| `str`| S3 object key (path) to create/update  
`binary_data`| `bytes`| Binary content to upload  
`content_type`| `str`| MIME type (e.g., `image/png`)  
**Returns:** `requests.Response` from S3, or `None` if credentials are not ready.
####  `delete_object(object_key: str) -> Response | None`
Delete an object from S3.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`object_key`| `str`| S3 object key (path) to delete  
**Returns:** `requests.Response` from S3, or `None` if credentials are not ready.
####  `list_s3_objects(prefix: str) -> list[S3Item] | None`
List all objects in S3 with the given prefix. Handles pagination automatically.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`prefix`| `str`| S3 key prefix to filter objects  
**Returns:** List of `S3Item` objects with metadata, or `None` if credentials are not ready.
**Raises:** `Exception` if S3 returns a non-200 status code.
####  `generate_presigned_url(object_key: str, expiration: int) -> str | None`
Generate a presigned URL for temporary access to an S3 object.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`object_key`| `str`| S3 object key (path)  
`expiration`| `int`| URL expiration time in seconds  
**Returns:** Presigned URL string, or `None` if credentials are not ready.
##  Data Structures 
###  Credentials 
AWS credentials for S3 access.
Field| Type| Description  
---|---|---  
`key`| `str`| AWS access key ID  
`secret`| `str`| AWS secret access key  
`region`| `str`| AWS region (e.g., `us-east-1`)  
`bucket`| `str`| S3 bucket name  
**Example:**
    ```python
    from canvas_sdk.clients.aws import Credentials
    credentials = Credentials(
        key="AKIAIOSFODNN7EXAMPLE",
        secret="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        region="us-west-2",
        bucket="my-application-bucket"
    )
    ```
###  S3Item 
S3 object metadata returned by `list_s3_objects`.
Field| Type| Description  
---|---|---  
`key`| `str`| Object key (path) in the S3 bucket  
`size`| `int`| Object size in bytes  
`last_modified`| `datetime`| Timestamp of the last modification  
**Example:**
    ```python
    items = client.list_s3_objects("documents/")
    for item in items:
        print(f"File: {item.key}")
        print(f"Size: {item.size} bytes")
        print(f"Last Modified: {item.last_modified}")
    ```
##  Complete Plugin Example 
Here's a complete example of using the S3 client in a Canvas plugin:
    ```python
    from http import HTTPStatus
    from canvas_sdk.clients.aws import S3, Credentials
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, PlainTextResponse, Response
    from canvas_sdk.handlers.simple_api import Credentials as APICredentials, SimpleAPI, api
    class S3Handler(SimpleAPI):
        """Simple API handler for S3 operations."""
        def authenticate(self, credentials: APICredentials) -> bool:
            return True
        def _s3_client(self) -> S3:
            """Create S3 client from plugin secrets."""
            return S3(
                Credentials(
                    key=self.secrets["S3Key"],
                    secret=self.secrets["S3Secret"],
                    region=self.secrets["S3Region"],
                    bucket=self.secrets["S3Bucket"],
                )
            )
        @api.get("/list")
        def list_files(self) -> list[Response | Effect]:
            """List all files in the bucket."""
            client = self._s3_client()
            if client.is_ready():
                items = client.list_s3_objects("")
                content = [{"key": p.key, "size": p.size} for p in items]
                return [JSONResponse(content, status_code=HTTPStatus.OK)]
            return []
        @api.get("/download/<file_key>")
        def download_file(self) -> list[Response | Effect]:
            """Download a file by key."""
            file_key = self.request.path_params["file_key"]
            client = self._s3_client()
            if client.is_ready() and file_key:
                response = client.access_s3_object(file_key)
                return [Response(response.content, status_code=HTTPStatus.OK)]
            return []
        @api.post("/upload/<file_key>")
        def upload_file(self) -> list[Response | Effect]:
            """Upload a file."""
            file_key = self.request.path_params["file_key"]
            client = self._s3_client()
            content = self.request.body
            content_type = self.request.content_type
            if client.is_ready() and file_key:
                if content_type == "text/plain":
                    response = client.upload_text_to_s3(file_key, content.decode("utf-8"))
                else:
                    response = client.upload_binary_to_s3(file_key, content, content_type)
                return [Response(response.content, status_code=response.status_code)]
            return []
        @api.delete("/delete/<file_key>")
        def delete_file(self) -> list[Response | Effect]:
            """Delete a file by key."""
            file_key = self.request.path_params["file_key"]
            client = self._s3_client()
            if client.is_ready() and file_key:
                response = client.delete_object(file_key)
                return [Response(response.content, status_code=HTTPStatus.OK)]
            return []
        @api.get("/presigned/<file_key>")
        def get_presigned_url(self) -> list[Response | Effect]:
            """Generate a presigned URL for temporary access."""
            file_key = self.request.path_params["file_key"]
            client = self._s3_client()
            if client.is_ready() and file_key:
                url = client.generate_presigned_url(file_key, 3600)  # 1 hour
                return [PlainTextResponse(url, status_code=HTTPStatus.OK)]
            return []
    ```
##  Error Handling 
The S3 client methods return `None` when credentials are not ready. For list operations, an `Exception` is raised if S3 returns an error status code.
    ```python
    # Check credentials before operations
    if not client.is_ready():
        print("S3 credentials are not configured")
        return
    # Handle list errors
    try:
        items = client.list_s3_objects("prefix/")
    except Exception as e:
        print(f"S3 error: {e}")
    # Check response status for uploads/downloads
    response = client.upload_text_to_s3("file.txt", "content")
    if response:
        if response.status_code == 200:
            print("Upload successful")
        else:
            print(f"Upload failed with status {response.status_code}")
    else:
        print("Credentials not ready")
    ```
##  AWS Signature V4 Authentication 
The S3 client implements AWS Signature Version 4 for request authentication. This is handled automatically - you only need to provide valid credentials. The client:
  - Signs all requests with HMAC-SHA256
  - Generates proper canonical requests
  - Handles date/time formatting for AWS
  - Supports presigned URLs for temporary access
##  Additional Resources 
  - [AWS S3 Documentation](https://docs.aws.amazon.com/s3/)
  - [AWS Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)
  - [S3 REST API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)
  - [Example Plugin](/sdk/example-aws_s3/) \- Documentation for the example plugin
  - [Source Code](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/aws_s3) \- View the source on GitHub

---

# Canvas FHIR

Source: https://docs.canvasmedical.com/sdk/clients-canvas-fhir/

The Canvas SDK FHIR client provides a simple interface for interacting with the [Canvas FHIR API](/api/), supporting CRUD operations on FHIR resources such as Coverages, DocumentReferences, AllergyIntolerances, and more. It handles OAuth client credentials authentication and token caching automatically.
##  Requirements 
  - **Canvas FHIR Client ID** : An OAuth client ID for your Canvas environment
  - **Canvas FHIR Client Secret** : The corresponding OAuth client secret
These credentials should be stored as [plugin secrets](/sdk/secrets/) and grant access to the Canvas FHIR API for your environment.
##  Imports 
The Canvas FHIR client is included in the Canvas SDK. Import the client:
    ```python
    from canvas_sdk.clients.canvas_fhir import CanvasFhir
    ```
##  Initialize the Client 
    ```python
    # Declare these secrets in the CANVAS_MANIFEST.json and set the values on the
    # plugin configuration page.
    client_id = self.secrets["CANVAS_FHIR_CLIENT_ID"]
    client_secret = self.secrets["CANVAS_FHIR_CLIENT_SECRET"]
    client = CanvasFhir(client_id, client_secret)
    ```
On initialization, the client will:
  1. Authenticate using the OAuth client credentials flow against your Canvas environment's token endpoint.
  2. Cache the access token using the plugin cache system, keyed by `client_id`, with automatic expiration.
  3. Determine the FHIR API base URL from the environment's `CUSTOMER_IDENTIFIER` setting (e.g., `https://fumage-{CUSTOMER_IDENTIFIER}.canvasmedical.com`).
##  CanvasFhir 
The main class for interacting with the Canvas FHIR API.
###  Constructor 
    ```python
    CanvasFhir(client_id: str, client_secret: str)
    ```
Parameter| Type| Description  
---|---|---  
`client_id`| `str`| OAuth client ID for the Canvas API  
`client_secret`| `str`| OAuth client secret  
###  Methods 
####  `search(resource_type: str, parameters: dict) -> dict`
Search for FHIR resources matching the given parameters.
    ```python
    # Search for a patient's allergy intolerances
    results = client.search("AllergyIntolerance", {"patient": "Patient/abc123"})
    for entry in results.get("entry", []):
        resource = entry["resource"]
        print(f"Allergy: {resource['code']['coding'][0]['display']}")
    ```
Parameter| Type| Description  
---|---|---  
`resource_type`| `str`| FHIR resource type (e.g., `Patient`, `Coverage`)  
`parameters`| `dict`| Search parameters as key-value pairs  
**Returns:** FHIR Bundle `dict` containing matching resources.
**Raises:** `requests.HTTPError` if the API returns an error status code.
####  `read(resource_type: str, resource_id: str) -> dict`
Read a single FHIR resource by its ID.
    ```python
    # Read a specific resource by ID
    allergy = client.read("AllergyIntolerance", "allergy-id-123")
    print(f"Status: {allergy['clinicalStatus']['coding'][0]['code']}")
    ```
Parameter| Type| Description  
---|---|---  
`resource_type`| `str`| FHIR resource type  
`resource_id`| `str`| ID of the resource to read  
**Returns:** FHIR resource `dict`.
**Raises:** `requests.HTTPError` if the API returns an error status code.
####  `create(resource_type: str, data: dict) -> dict`
Create a new FHIR resource.
    ```python
    # Create a new Coverage resource
    coverage = client.create("Coverage", {
        "resourceType": "Coverage",
        "status": "active",
        "beneficiary": {"reference": "Patient/abc123"},
        "payor": [{"reference": "Organization/org-456"}],
    })
    print(f"Created Coverage: {coverage['id']}")
    ```
Parameter| Type| Description  
---|---|---  
`resource_type`| `str`| FHIR resource type  
`data`| `dict`| FHIR resource data to create  
**Returns:** Created FHIR resource `dict` (including server-assigned `id`).
**Raises:** `requests.HTTPError` if the API returns an error status code.
####  `update(resource_type: str, resource_id: str, data: dict) -> dict`
Update an existing FHIR resource.
    ```python
    # Update an existing resource
    updated = client.update("Coverage", "coverage-id-789", {
        "resourceType": "Coverage",
        "id": "coverage-id-789",
        "status": "cancelled",
        "beneficiary": {"reference": "Patient/abc123"},
        "payor": [{"reference": "Organization/org-456"}],
    })
    print(f"Updated Coverage status: {updated['status']}")
    ```
Parameter| Type| Description  
---|---|---  
`resource_type`| `str`| FHIR resource type  
`resource_id`| `str`| ID of the resource to update  
`data`| `dict`| Complete FHIR resource data  
**Returns:** Updated FHIR resource `dict`.
**Raises:** `requests.HTTPError` if the API returns an error status code.
###  Sending other requests 
The methods above parse every response as JSON. When you need a request they don't cover, or the raw response, send it yourself with the [`Http`](/sdk/utils/) util. Build the request from the client's `base_url` and `get_headers()`:
    ```python
    from canvas_sdk.utils import Http
    response = Http().post(
        f"{client.base_url}/Coverage",
        headers=client.get_headers(),
        json=coverage,
    )
    response.raise_for_status()
    # The raw response is yours to read, including an empty body.
    result = response.json() if response.text.strip() else {}
    ```
Member| Type| Description  
---|---|---  
`base_url`| `str`| The FHIR API base URL for your environment, such as `https://fumage-{CUSTOMER_IDENTIFIER}.canvasmedical.com`.  
`get_headers()`| `dict`| The headers a FHIR API request needs. These are a bearer `Authorization` header carrying the client's access token, and `Content-Type: application/json`.  
##  Authentication 
The client uses the OAuth 2.0 client credentials flow to authenticate with the Canvas API. Token management is handled automatically:
  - On first use, the client exchanges the `client_id` and `client_secret` for an access token via the Canvas token endpoint.
  - The token is cached using the plugin cache system with the key `canvas_fhir_credentials_{client_id}`.
  - The cached token expires 60 seconds before the actual token expiration to avoid using stale credentials.
  - Subsequent requests reuse the cached token until it expires.
##  Error Handling 
The Canvas FHIR client uses `raise_for_status()` on all HTTP responses, which raises `requests.HTTPError` for non-successful status codes.
    ```python
    from requests import HTTPError
    try:
        result = client.read("Patient", "nonexistent-id")
    except HTTPError as e:
        print(f"HTTP {e.response.status_code}: {e.response.text}")
    ```
##  Complete Plugin Example 
Here's a complete example of using the Canvas FHIR client in an ActionButton handler:
    ```python
    from canvas_sdk.clients.canvas_fhir import CanvasFhir
    from canvas_sdk.effects import Effect
    from canvas_sdk.handlers.action_button import ActionButton
    from logger import log
    class FhirRequestHandler(ActionButton):
        """Handler that queries the FHIR API when a button is clicked."""
        BUTTON_TITLE = "Trigger FHIR Request"
        BUTTON_KEY = "TRIGGER_FHIR_REQUEST"
        BUTTON_LOCATION = ActionButton.ButtonLocation.CHART_SUMMARY_ALLERGIES_SECTION
        def handle(self) -> list[Effect]:
            """Handle the button click."""
            client_id = self.secrets["CANVAS_FHIR_CLIENT_ID"]
            client_secret = self.secrets["CANVAS_FHIR_CLIENT_SECRET"]
            patient_id = self.event.target.id
            client = CanvasFhir(client_id, client_secret)
            # Search for the patient's allergy intolerances
            search_response = client.search(
                "AllergyIntolerance",
                {"patient": f"Patient/{patient_id}"},
            )
            log.info(f"Search: {search_response}")
            # Read the first result
            first_entry = search_response["entry"][0]["resource"]
            read_response = client.read("AllergyIntolerance", first_entry["id"])
            log.info(f"Read: {read_response}")
            return []
    ```
##  Additional Resources 
  - [Canvas FHIR API Documentation](/api/)
  - [Example Plugin Source Code](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/canvas_fhir_client)

---

# Extend AI

Source: https://docs.canvasmedical.com/sdk/clients-extend-ai/

The Canvas SDK Extend AI client provides an interface for document processing using AI-powered extraction, classification, and splitting capabilities through the Extend AI API.
##  Requirements 
  - **Extend AI API Key** : Obtain from your [Extend AI dashboard](https://app.extend.ai/)
##  What is Extend AI? 
Extend AI provides intelligent document processing (IDP) capabilities:
  - **Extraction** : Extract structured data from documents based on a defined schema
  - **Classification** : Classify documents into predefined categories
  - **Splitting** : Split multi-page documents into logical sections
##  Imports 
The Extend AI client is included in the Canvas SDK. Import the necessary components:
    ```python
    from canvas_sdk.clients.extend_ai.libraries import Client
    from canvas_sdk.clients.extend_ai.constants import RunStatus, VersionName
    from canvas_sdk.clients.extend_ai.structures import RequestFailed
    ```
##  Initialize the Client 
    ```python
    client = Client(key="your_extend_ai_api_key")
    ```
##  Extract Data from a Document (Using an Existing Processor) 
The most common use case is running an existing processor on a document. Here's a complete example:
    ```python
    import time
    from canvas_sdk.clients.extend_ai.libraries import Client
    from canvas_sdk.clients.extend_ai.constants import RunStatus
    from canvas_sdk.clients.extend_ai.structures import RequestFailed
    # Initialize the client
    client = Client(key="your_api_key")
    # Your processor ID (created in the Extend AI dashboard)
    processor_id = "proc_xxxxxxxxxxxxxxxxx"
    # URL to the document (must be publicly accessible)
    document_url = "https://your-bucket.s3.amazonaws.com/document.pdf"
    try:
        # Start the processor run
        run = client.run_processor(
            processor_id=processor_id,
            file_name="my-document.pdf",
            file_url=document_url,
            config=None,  # Use processor's default configuration
        )
        print(f"Run started! ID: {run.id}, Status: {run.status.value}")
        # Poll for completion
        while run.status in (RunStatus.PENDING, RunStatus.PROCESSING):
            time.sleep(2)  # Wait 2 seconds between checks
            run = client.run_status(run.id)
            print(f"Status: {run.status.value}")
        # Check result
        if run.status == RunStatus.PROCESSED:
            print("Extraction successful!")
            print(f"Extracted data: {run.output.value}")
        else:
            print(f"Processing failed with status: {run.status.value}")
    except RequestFailed as e:
        print(f"Error: {e.message} (HTTP {e.status_code})")
    ```
##  List Available Processors 
    ```python
    # List all processors in your account
    for processor in client.list_processors():
        print(f"ID: {processor.id}")
        print(f"Name: {processor.name}")
        print(f"Type: {processor.type.value}")
        print("---")
    ```
##  Get Processor Configuration 
    ```python
    from canvas_sdk.clients.extend_ai.constants import VersionName
    # Get the draft version of a processor
    processor_version = client.processor(
        processor_id="proc_xxxxxxxxxxxxxxxxx",
        version=VersionName.DRAFT.value
    )
    print(f"Processor: {processor_version.processor.name}")
    print(f"Version: {processor_version.version}")
    print(f"Type: {processor_version.processor.type.value}")
    # Access the schema (for extraction processors)
    if hasattr(processor_version.config, 'schema'):
        print(f"Schema: {processor_version.config.schema}")
    ```
##  Check Run Status and Get Results 
    ```python
    # Check the status of a run
    run = client.run_status("run_xxxxxxxxxxxxxxxxx")
    print(f"Status: {run.status.value}")
    print(f"Credits used: {run.usage}")
    if run.status == RunStatus.PROCESSED:
        # For extraction processors
        if hasattr(run.output, 'value'):
            extracted_data = run.output.value
            print(f"Extracted: {extracted_data}")
        # For classification processors
        if hasattr(run.output, 'type'):
            print(f"Classification: {run.output.type}")
            print(f"Confidence: {run.output.confidence}")
        # For splitter processors
        if hasattr(run.output, 'splits'):
            for split in run.output.splits:
                print(f"Split: {split.type}, Pages {split.startPage}-{split.endPage}")
    ```
##  Clean Up Files After Processing 
    ```python
    # After processing, delete the uploaded files to save storage
    run = client.run_status("run_xxxxxxxxxxxxxxxxx")
    if run.status == RunStatus.PROCESSED:
        for file in run.files:
            deleted = client.delete_file(file.id)
            print(f"Deleted file {file.name}: {deleted}")
    ```
##  Complete Workflow Example 
    ```python
    import time
    from canvas_sdk.clients.extend_ai.libraries import Client
    from canvas_sdk.clients.extend_ai.constants import RunStatus
    from canvas_sdk.clients.extend_ai.structures import RequestFailed
    def extract_from_document(api_key: str, processor_id: str, document_url: str) -> dict:
        """
        Extract structured data from a document using Extend AI.
        Args:
            api_key: Your Extend AI API key
            processor_id: The processor ID to use
            document_url: Public URL to the document
        Returns:
            Dictionary containing the extracted data
        Raises:
            RequestFailed: If the API request fails
            RuntimeError: If processing fails or times out
        """
        client = Client(key=api_key)
        # Start processing
        run = client.run_processor(
            processor_id=processor_id,
            file_name="document.pdf",
            file_url=document_url,
            config=None,
        )
        # Wait for completion (with timeout)
        max_attempts = 30  # 60 seconds max
        attempts = 0
        while run.status in (RunStatus.PENDING, RunStatus.PROCESSING):
            if attempts >= max_attempts:
                raise RuntimeError("Processing timed out")
            time.sleep(2)
            run = client.run_status(run.id)
            attempts += 1
        # Handle result
        if run.status == RunStatus.PROCESSED:
            # Clean up files
            for file in run.files:
                client.delete_file(file.id)
            return run.output.value if hasattr(run.output, 'value') else run.output.to_dict()
        raise RuntimeError(f"Processing failed: {run.status.value}")
    # Usage
    result = extract_from_document(
        api_key="your_api_key",
        processor_id="proc_xxxxxxxxxxxxxxxxx",
        document_url="https://example.com/document.pdf"
    )
    print(result)
    ```
##  Client 
The main class for interacting with the Extend AI API.
###  Constructor 
    ```python
    Client(key: str)
    ```
Parameter| Type| Description  
---|---|---  
`key`| `str`| Extend AI API key  
###  File Management 
####  `list_files() -> Iterator[StoredFile]`
List all files stored in Extend AI.
    ```python
    for file in client.list_files():
        print(f"{file.id}: {file.name} ({file.type})")
    ```
**Returns:** Iterator of `StoredFile` objects
**Raises:** `RequestFailed` on error
####  `delete_file(file_id: str) -> bool`
Delete a file from Extend AI storage.
    ```python
    deleted = client.delete_file("file_xxxxxxxxxxxxxxxxx")
    print(f"Deleted: {deleted}")
    ```
Parameter| Type| Description  
---|---|---  
`file_id`| `str`| Unique identifier of the file  
**Returns:** `True` on success
**Raises:** `RequestFailed` on error
###  Processor Management 
####  `list_processors() -> Iterator[ProcessorMeta]`
List all processors in the account.
    ```python
    for processor in client.list_processors():
        print(f"{processor.name}: {processor.type.value}")
    ```
**Returns:** Iterator of `ProcessorMeta` objects
**Raises:** `RequestFailed` on error
####  `processor(processor_id: str, version: str) -> ProcessorVersion`
Get details for a specific processor version.
    ```python
    from canvas_sdk.clients.extend_ai.constants import VersionName
    # Get draft version
    processor = client.processor("proc_xxx", VersionName.DRAFT.value)
    # Get latest published version
    processor = client.processor("proc_xxx", VersionName.LATEST.value)
    # Get specific version
    processor = client.processor("proc_xxx", "v1")
    ```
Parameter| Type| Description  
---|---|---  
`processor_id`| `str`| Unique identifier of the processor  
`version`| `str`| Version name (`draft`, `latest`, or `vN`)  
**Returns:** `ProcessorVersion` object
**Raises:** `RequestFailed` on error
####  `create_processor(name: str, config: ConfigBase) -> ProcessorMeta`
Create a new processor with the specified configuration.
    ```python
    from canvas_sdk.clients.extend_ai.constants import BaseProcessor
    from canvas_sdk.clients.extend_ai.structures.config import (
        ConfigExtraction,
        AdvancedOptionsExtraction,
        Parser,
    )
    config = ConfigExtraction(
        base_processor=BaseProcessor.EXTRACTION_PERFORMANCE,
        extraction_rule="Extract all relevant fields",
        schema={
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "date": {"type": "string"},
                "amount": {"type": "number"},
            }
        },
        advanced_options=AdvancedOptionsExtraction.from_dict({}),
        parser=Parser.from_dict({}),
    )
    processor = client.create_processor("Invoice Extractor", config)
    print(f"Created: {processor.id}")
    ```
Parameter| Type| Description  
---|---|---  
`name`| `str`| Name for the new processor  
`config`| `ConfigBase`| Processor configuration object  
**Returns:** `ProcessorMeta` object
**Raises:** `RequestFailed` on error
###  Running Processors 
####  `run_processor(processor_id, file_name, file_url, config) -> ProcessorRun`
Execute a processor on a document.
    ```python
    run = client.run_processor(
        processor_id="proc_xxxxxxxxxxxxxxxxx",
        file_name="invoice.pdf",
        file_url="https://bucket.s3.amazonaws.com/invoice.pdf",
        config=None,  # Use processor defaults
    )
    print(f"Run ID: {run.id}, Status: {run.status.value}")
    ```
Parameter| Type| Description  
---|---|---  
`processor_id`| `str`| Processor to run  
`file_name`| `str`| Name for the file  
`file_url`| `str`| Public URL to the document  
`config`| `ConfigExtraction \| None`| Optional config override (extraction only)  
**Returns:** `ProcessorRun` object with initial status
**Raises:** `RequestFailed` on error
####  `run_status(run_id: str) -> ProcessorRun`
Get the current status and results of a processor run.
    ```python
    run = client.run_status("run_xxxxxxxxxxxxxxxxx")
    if run.status == RunStatus.PROCESSED:
        print(f"Result: {run.output.to_dict()}")
    elif run.status == RunStatus.FAILED:
        print("Processing failed")
    else:
        print(f"Still processing: {run.status.value}")
    ```
Parameter| Type| Description  
---|---|---  
`run_id`| `str`| Unique identifier of the run  
**Returns:** `ProcessorRun` object with current status and results
**Raises:** `RequestFailed` on error
##  Data Structures 
###  ProcessorMeta 
Metadata about a processor.
Field| Type| Description  
---|---|---  
`id`| `str`| Unique processor identifier  
`name`| `str`| Processor name  
`type`| `ProcessorType`| Type (EXTRACT, CLASSIFY, SPLITTER)  
`created_at`| `datetime \| None`| Creation timestamp  
`updated_at`| `datetime \| None`| Last update timestamp  
###  ProcessorVersion 
A specific version of a processor with full configuration.
Field| Type| Description  
---|---|---  
`id`| `str`| Version identifier  
`version`| `str`| Version name (draft, v1, etc.)  
`description`| `str`| Version description  
`processor`| `ProcessorMeta`| Processor metadata  
`config`| `ConfigClassification \| ConfigExtraction \| ConfigSplitter`| Processor configuration  
`created_at`| `datetime`| Creation timestamp  
`updated_at`| `datetime`| Last update timestamp  
###  ProcessorRun 
Represents a single execution of a processor.
Field| Type| Description  
---|---|---  
`id`| `str`| Run identifier  
`processor`| `ProcessorMeta`| Processor that was executed  
`output`| `ResultClassification \| ResultExtraction \| ResultSplitter \| None`| Processing results  
`status`| `RunStatus`| Current run status  
`files`| `list[StoredFile]`| Associated files  
`usage`| `int`| Total credits consumed  
###  StoredFile 
A file stored in Extend AI.
Field| Type| Description  
---|---|---  
`id`| `str`| Unique file identifier  
`type`| `str`| MIME type / file type  
`name`| `str`| File name  
###  Classification 
A classification category definition.
Field| Type| Description  
---|---|---  
`id`| `str`| Classification identifier  
`type`| `str`| Classification type/category name  
`description`| `str`| Description of this classification  
##  Result Structures 
###  ResultExtraction 
Output from an extraction processor.
Field| Type| Description  
---|---|---  
`value`| `dict`| Dictionary of extracted field values  
**Example:**
    ```python
    if run.status == RunStatus.PROCESSED:
        extracted = run.output.value
        print(f"Name: {extracted.get('name')}")
        print(f"Amount: {extracted.get('amount')}")
    ```
###  ResultClassification 
Output from a classification processor.
Field| Type| Description  
---|---|---  
`type`| `str`| Assigned classification type  
`confidence`| `float`| Confidence score (0.0 to 1.0)  
`insights`| `list[Insight]`| Extracted insights  
**Example:**
    ```python
    if run.status == RunStatus.PROCESSED:
        print(f"Type: {run.output.type}")
        print(f"Confidence: {run.output.confidence:.2%}")
        for insight in run.output.insights:
            print(f"  {insight.type}: {insight.content}")
    ```
###  ResultSplitter 
Output from a splitter processor.
Field| Type| Description  
---|---|---  
`splits`| `list[Split]`| List of identified splits  
**Example:**
    ```python
    if run.status == RunStatus.PROCESSED:
        for split in run.output.splits:
            print(f"Section: {split.type}")
            print(f"  Pages: {split.startPage} - {split.endPage}")
            print(f"  Observation: {split.observation}")
    ```
###  Split 
A document split/section identified by a splitter.
Field| Type| Description  
---|---|---  
`id`| `str`| Split identifier  
`type`| `str`| Split type/category  
`observation`| `str`| Observations about this split  
`identifier`| `str`| Unique identifier  
`startPage`| `int`| Starting page number  
`endPage`| `int`| Ending page number  
`classificationId`| `str`| Associated classification ID  
`fileId`| `str`| File this split belongs to  
`name`| `str`| Split name  
###  Insight 
An insight extracted during classification.
Field| Type| Description  
---|---|---  
`type`| `str`| Insight type/category  
`content`| `str`| Insight text content  
##  Configuration Structures 
###  ConfigExtraction 
Configuration for extraction processors.
Field| Type| Description  
---|---|---  
`base_processor`| `BaseProcessor`| Performance or light variant  
`extraction_rule`| `str`| Custom extraction instructions  
`schema`| `dict`| JSON Schema for extracted data  
`advanced_options`| `AdvancedOptionsExtraction`| Advanced settings  
`parser`| `Parser`| Document parser settings  
###  ConfigClassification 
Configuration for classification processors.
Field| Type| Description  
---|---|---  
`classifications`| `list[Classification]`| Possible classification categories  
`base_processor`| `BaseProcessor`| Performance or light variant  
`classification_rule`| `str`| Custom classification rules  
`advanced_options`| `AdvancedOptionsClassification`| Advanced settings  
`parser`| `Parser`| Document parser settings  
###  ConfigSplitter 
Configuration for splitter processors.
Field| Type| Description  
---|---|---  
`split_classifications`| `list[Classification]`| Classification categories for splits  
`base_processor`| `BaseProcessor`| Performance or light variant  
`split_rules`| `str`| Custom splitting rules  
`advanced_options`| `AdvancedOptionsSplitter`| Advanced settings  
`parser`| `Parser`| Document parser settings  
##  Constants (Enums) 
###  ProcessorType 
Types of processors available.
Value| Description  
---|---  
`EXTRACT`| Extracts structured data based on a schema  
`CLASSIFY`| Classifies documents into categories  
`SPLITTER`| Splits documents into sections  
###  RunStatus 
Status values for processor runs.
Value| Description  
---|---  
`PENDING`| Run is queued and waiting to start  
`PROCESSING`| Run is currently being processed  
`PROCESSED`| Run completed successfully  
`FAILED`| Run encountered an error  
`CANCELLED`| Run was cancelled before completion  
###  VersionName 
Standard version names for processors.
Value| Description  
---|---  
`LATEST`| Latest published version  
`DRAFT`| Draft/working version  
###  BaseProcessor 
Base processor variants (performance vs speed trade-off).
Value| Description  
---|---  
`CLASSIFICATION_PERFORMANCE`| High accuracy classification  
`CLASSIFICATION_LIGHT`| Fast classification  
`EXTRACTION_PERFORMANCE`| High accuracy extraction  
`EXTRACTION_LIGHT`| Fast extraction  
`SPLITTING_PERFORMANCE`| High accuracy splitting  
`SPLITTING_LIGHT`| Fast splitting  
##  Error Handling 
###  RequestFailed 
Exception raised when an Extend AI API request fails (extends `RuntimeError`).
Attribute| Type| Description  
---|---|---  
`status_code`| `int`| HTTP status code  
`message`| `str`| Error message from Extend AI  
**Example:**
    ```python
    try:
        run = client.run_processor(...)
    except RequestFailed as e:
        print(f"API Error {e.status_code}: {e.message}")
    ```
##  Polling Pattern 
Since document processing is asynchronous, use this pattern to wait for results:
    ```python
    import time
    from canvas_sdk.clients.extend_ai.constants import RunStatus
    def wait_for_completion(client, run_id: str, timeout_seconds: int = 120) -> ProcessorRun:
        """
        Wait for a processor run to complete.
        Args:
            client: Extend AI client instance
            run_id: The run ID to monitor
            timeout_seconds: Maximum time to wait
        Returns:
            ProcessorRun with final status
        Raises:
            TimeoutError: If processing exceeds timeout
        """
        start_time = time.time()
        poll_interval = 2  # seconds
        while True:
            run = client.run_status(run_id)
            # Check if done
            if run.status not in (RunStatus.PENDING, RunStatus.PROCESSING):
                return run
            # Check timeout
            if time.time() - start_time > timeout_seconds:
                raise TimeoutError(f"Processing timed out after {timeout_seconds}s")
            time.sleep(poll_interval)
    # Usage
    run = client.run_processor(processor_id, file_name, file_url, None)
    final_run = wait_for_completion(client, run.id)
    if final_run.status == RunStatus.PROCESSED:
        print(final_run.output.to_dict())
    ```
##  Additional Resources 
  - [Extend AI Documentation](https://docs.extend.ai/)
  - [Example Plugin](/sdk/example-extend_ai_pdf/) \- Documentation for the example plugin
  - [Source Code](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/extend_ai_pdf) \- View the source on GitHub

---

# LLMs

Source: https://docs.canvasmedical.com/sdk/clients-llms/

The Canvas SDK LLMs client provides a unified interface for interacting with multiple Large Language Model (LLM) providers including OpenAI (GPT Models), Anthropic (Claude), and Google (Gemini). It supports text conversations, file attachments (images, PDFs, text), and structured JSON output.
##  Requirements 
Depending on which LLM provider you use:
  - **OpenAI** : API key from https://platform.openai.com/api-keys
  - **Anthropic** : API key from https://console.anthropic.com/settings/keys
  - **Google** : API key from https://aistudio.google.com/apikey
##  Imports 
The LLMs client is included in the Canvas SDK. Import the necessary components:
    ```python
    from canvas_sdk.clients.llms import (
        LlmOpenai,
        LlmAnthropic,
        LlmGoogle,
        LlmResponse,
        LlmTokens,
        LlmTurn,
    )
    from canvas_sdk.clients.llms.structures.settings import (
        LlmSettingsGpt4,
        LlmSettingsAnthropic,
        LlmSettingsGemini,
    )
    from canvas_sdk.clients.llms.constants import FileType
    from canvas_sdk.clients.llms.structures import LlmFileUrl, FileContent, BaseModelLlmJson
    ```
##  Initialize the Clients 
###  OpenAI (GPT Models) 
    ```python
    from canvas_sdk.clients.llms import LlmOpenai
    from canvas_sdk.clients.llms.structures.settings import LlmSettingsGpt4
    client = LlmOpenai(LlmSettingsGpt4(
        api_key="your_openai_api_key",
        model="gpt-4o",
        temperature=0.7,
    ))
    ```
###  Anthropic (Claude) 
    ```python
    from canvas_sdk.clients.llms import LlmAnthropic
    from canvas_sdk.clients.llms.structures.settings import LlmSettingsAnthropic
    client = LlmAnthropic(LlmSettingsAnthropic(
        api_key="your_anthropic_api_key",
        model="claude-sonnet-4-5-20250929",
        temperature=0.7,
        max_tokens=8192,
    ))
    ```
###  Google (Gemini) 
    ```python
    from canvas_sdk.clients.llms import LlmGoogle
    from canvas_sdk.clients.llms.structures.settings import LlmSettingsGemini
    client = LlmGoogle(LlmSettingsGemini(
        api_key="your_google_api_key",
        model="models/gemini-2.0-flash",
        temperature=0.7,
    ))
    ```
##  Simple Text Conversation 
    ```python
    from http import HTTPStatus
    from canvas_sdk.clients.llms import LlmOpenai
    from canvas_sdk.clients.llms.structures.settings import LlmSettingsGpt4
    # Initialize client
    client = LlmOpenai(LlmSettingsGpt4(
        api_key="your_api_key",
        model="gpt-4o",
        temperature=0.7,
    ))
    # Set up the conversation
    client.set_system_prompt(["You are a helpful assistant."])
    client.set_user_prompt(["What is the capital of France?"])
    # Make the request
    response = client.request()
    if response.code == HTTPStatus.OK:
        print(f"Response: {response.response}")
        print(f"Tokens used - Prompt: {response.tokens.prompt}, Generated: {response.tokens.generated}")
    else:
        print(f"Error: {response.response}")
    ```
##  Multi-turn Conversation 
    ```python
    # Initialize client
    client = LlmOpenai(LlmSettingsGpt4(
        api_key="your_api_key",
        model="gpt-4o",
        temperature=0.7,
    ))
    # Build a multi-turn conversation
    client.set_system_prompt(["You are a helpful math tutor."])
    client.set_user_prompt(["What is 2 + 2?"])
    client.set_model_prompt(["2 + 2 equals 4."])
    client.set_user_prompt(["And what is that multiplied by 3?"])
    # Get the response
    response = client.request()
    print(response.response)  # "4 multiplied by 3 equals 12."
    ```
##  Using Retry Logic 
    ```python
    # Attempt multiple requests until success or max attempts
    responses = client.attempt_requests(attempts=3)
    # Check the last response
    last_response = responses[-1]
    if last_response.code == HTTPStatus.OK:
        print(f"Success: {last_response.response}")
    else:
        print(f"Failed after {len(responses)} attempts")
    ```
##  Analyze an Image 
    ```python
    from canvas_sdk.clients.llms import LlmOpenai
    from canvas_sdk.clients.llms.structures.settings import LlmSettingsGpt4
    from canvas_sdk.clients.llms.constants import FileType
    from canvas_sdk.clients.llms.structures import LlmFileUrl
    client = LlmOpenai(LlmSettingsGpt4(
        api_key="your_api_key",
        model="gpt-4o",
        temperature=0.5,
    ))
    # Set up prompts
    client.set_system_prompt(["You are an image analysis assistant."])
    client.set_user_prompt(["Describe what you see in this image."])
    # Add an image file
    client.add_url_file(LlmFileUrl(
        url="https://example.com/image.jpg",
        type=FileType.IMAGE
    ))
    # Get the analysis
    response = client.request()
    print(response.response)
    ```
##  Analyze a PDF Document 
    ```python
    from canvas_sdk.clients.llms import LlmAnthropic
    from canvas_sdk.clients.llms.structures.settings import LlmSettingsAnthropic
    from canvas_sdk.clients.llms.constants import FileType
    from canvas_sdk.clients.llms.structures import LlmFileUrl
    client = LlmAnthropic(LlmSettingsAnthropic(
        api_key="your_api_key",
        model="claude-sonnet-4-5-20250929",
        temperature=0.5,
        max_tokens=4096,
    ))
    # Set up prompts
    client.set_system_prompt(["You are a document analysis assistant."])
    client.set_user_prompt(["Summarize the key points in this document."])
    # Add a PDF file
    client.add_url_file(LlmFileUrl(
        url="https://example.com/document.pdf",
        type=FileType.PDF
    ))
    # Get the summary
    response = client.request()
    print(response.response)
    ```
##  Upload File Content Directly 
Instead of providing a URL, you can upload file content directly using `FileContent`. This is useful when you have the file data in memory (e.g., from a form upload).
    ```python
    import base64
    from canvas_sdk.clients.llms import LlmOpenai
    from canvas_sdk.clients.llms.structures.settings import LlmSettingsGpt4
    from canvas_sdk.clients.llms.structures import FileContent
    client = LlmOpenai(LlmSettingsGpt4(
        api_key="your_api_key",
        model="gpt-4o",
        temperature=0.5,
    ))
    # Read file content from disk or form upload
    with open("document.pdf", "rb") as f:
        file_bytes = f.read()
    # Create FileContent with base64-encoded data
    file_content = FileContent(
        mime_type="application/pdf",
        content=base64.b64encode(file_bytes),
        size=len(file_bytes),
    )
    # Add to the client's file_content list
    client.file_content.append(file_content)
    # Set up prompts
    client.set_system_prompt(["Analyze the provided document."])
    client.set_user_prompt(["What are the main topics covered in this document?"])
    # Get the analysis
    response = client.request()
    print(response.response)
    ```
**Supported MIME types for direct file content:**
MIME Type Pattern| Description  
---|---  
`image/*`| Images (PNG, JPEG, GIF, etc.)  
`application/pdf`| PDF documents  
`text/*`| Text files (Anthropic only)  
##  Structured JSON Output 
    ```python
    from pydantic import Field
    from canvas_sdk.clients.llms import LlmOpenai
    from canvas_sdk.clients.llms.structures.settings import LlmSettingsGpt4
    from canvas_sdk.clients.llms.structures import BaseModelLlmJson
    # Define your response schema
    class PersonInfo(BaseModelLlmJson):
        name: str = Field(description="The person's full name")
        age: int = Field(description="The person's age in years")
        occupation: str = Field(description="The person's job or profession")
    # Initialize client
    client = LlmOpenai(LlmSettingsGpt4(
        api_key="your_api_key",
        model="gpt-4o",
        temperature=0.3,
    ))
    # Set the schema for structured output
    client.set_schema(PersonInfo)
    # Set up prompts
    client.set_system_prompt(["Extract person information from the text."])
    client.set_user_prompt(["John Smith is a 35-year-old software engineer."])
    # Get structured response
    response = client.request()
    # Response will be valid JSON matching the PersonInfo schema
    print(response.response)  # {"name": "John Smith", "age": 35, "occupation": "software engineer"}
    ```
##  Nested Structured Output 
    ```python
    from pydantic import Field
    from canvas_sdk.clients.llms.structures import BaseModelLlmJson
    # Define nested schemas (all must extend BaseModelLlmJson)
    class Address(BaseModelLlmJson):
        street: str = Field(description="Street address")
        city: str = Field(description="City name")
        country: str = Field(description="Country name")
    class Person(BaseModelLlmJson):
        name: str = Field(description="Full name")
        address: Address = Field(description="Home address")
    # Use with client
    client.set_schema(Person)
    client.set_system_prompt(["Extract person and address information."])
    client.set_user_prompt(["Jane Doe lives at 123 Main St, New York, USA."])
    response = client.request()
    ```
##  LLM Clients 
All LLM clients inherit from `LlmApi` and share the same interface.
###  Available Clients 
Client| Provider| Settings Class| API Endpoint  
---|---|---|---  
`LlmOpenai`| OpenAI| `LlmSettingsGpt4`| `https://us.api.openai.com`  
`LlmAnthropic`| Anthropic| `LlmSettingsAnthropic`| `https://api.anthropic.com`  
`LlmGoogle`| Google| `LlmSettingsGemini`| `https://generativelanguage.googleapis.com`  
###  Constructor 
    ```python
    LlmOpenai(settings: LlmSettingsGpt4)
    LlmAnthropic(settings: LlmSettingsAnthropic)
    LlmGoogle(settings: LlmSettingsGemini)
    ```
###  Attributes 
Attribute| Type| Description  
---|---|---  
`settings`| `LlmSettings`| Configuration settings for the LLM API  
`prompts`| `list[LlmTurn]`| List of conversation turns  
`file_urls`| `list[LlmFileUrl]`| Files to attach via URL (use `add_url_file()`)  
`file_content`| `list[FileContent]`| Files to attach via direct content  
`schema`| `type[BaseModelLlmJson]`| Schema for structured JSON output  
###  Methods 
####  `set_system_prompt(text: list[str]) -> None`
Set or replace the system prompt. The system prompt is always placed at the beginning of the conversation.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`text`| `list[str]`| List of text strings for the prompt  
####  `set_user_prompt(text: list[str]) -> None`
Add a user message to the conversation.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`text`| `list[str]`| List of text strings for the prompt  
####  `set_model_prompt(text: list[str]) -> None`
Add a model/assistant response to the conversation history.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`text`| `list[str]`| List of text strings for the response  
####  `add_prompt(prompt: LlmTurn) -> None`
Add a conversation turn using an `LlmTurn` object.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`prompt`| `LlmTurn`| The conversation turn to add  
####  `add_url_file(url_file: LlmFileUrl) -> None`
Add a file attachment to the next user message.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`url_file`| `LlmFileUrl`| File URL and type information  
####  `set_schema(schema: type[BaseModelLlmJson] | None) -> None`
Set a schema for structured JSON output. Pass `None` to disable structured output.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`schema`| `type[BaseModelLlmJson] | None`| Pydantic model for JSON schema  
####  `reset_prompts() -> None`
Clear all stored prompts from the conversation.
####  `request() -> LlmResponse`
Make a single request to the LLM API.
**Returns:** `LlmResponse` containing status code, response text, and token usage.
####  `attempt_requests(attempts: int) -> list[LlmResponse]`
Attempt multiple requests until success or max attempts reached.
**Parameters:**
Parameter| Type| Description  
---|---|---  
`attempts`| `int`| Maximum number of request attempts  
**Returns:** List of all `LlmResponse` objects from each attempt.
##  Settings Classes 
###  LlmSettings (Base) 
Base configuration class for LLM APIs.
Field| Type| Description  
---|---|---  
`api_key`| `str`| API authentication key  
`model`| `str`| Model name or identifier  
###  LlmSettingsGpt4 
Settings for OpenAI API.
Field| Type| Description  
---|---|---  
`api_key`| `str`| OpenAI API key  
`model`| `str`| Model name (e.g., `gpt-4o`, `gpt-4-turbo`)  
`temperature`| `float`| Randomness control (0.0-2.0)  
**Example:**
    ```python
    LlmSettingsGpt4(
        api_key="sk-...",
        model="gpt-4o",
        temperature=0.7,
    )
    ```
###  LlmSettingsAnthropic 
Settings for Anthropic Claude API.
Field| Type| Description  
---|---|---  
`api_key`| `str`| Anthropic API key  
`model`| `str`| Model name (e.g., `claude-sonnet-4-5-20250929`)  
`temperature`| `float`| Randomness control (0.0-1.0)  
`max_tokens`| `float`| Maximum tokens to generate  
**Example:**
    ```python
    LlmSettingsAnthropic(
        api_key="sk-ant-...",
        model="claude-sonnet-4-5-20250929",
        temperature=0.7,
        max_tokens=8192,
    )
    ```
###  LlmSettingsGemini 
Settings for Google Gemini API.
Field| Type| Description  
---|---|---  
`api_key`| `str`| Google API key  
`model`| `str`| Model name (e.g., `models/gemini-2.0-flash`)  
`temperature`| `float`| Randomness control (0.0-2.0)  
**Example:**
    ```python
    LlmSettingsGemini(
        api_key="AIza...",
        model="models/gemini-2.0-flash",
        temperature=0.7,
    )
    ```
##  Data Structures 
###  LlmResponse 
Response from an LLM API call.
Field| Type| Description  
---|---|---  
`code`| `HTTPStatus`| HTTP status code of the response  
`response`| `str`| Text content returned by the LLM  
`tokens`| `LlmTokens`| Token usage information  
**Methods:**
Method| Returns| Description  
---|---|---  
`to_dict()`| `dict`| Convert response to dictionary  
###  LlmTokens 
Token usage information for LLM API calls.
Field| Type| Description  
---|---|---  
`prompt`| `int`| Number of tokens in the prompt  
`generated`| `int`| Number of tokens in the generated response  
**Methods:**
Method| Returns| Description  
---|---|---  
`add(counts)`| `None`| Add token counts from another instance  
`to_dict()`| `dict`| Convert to dictionary  
###  LlmTurn 
A single conversation turn in an LLM interaction.
Field| Type| Description  
---|---|---  
`role`| `str`| Role of the speaker (`system`, `user`, `model`)  
`text`| `list[str]`| List of text strings for this turn  
**Methods:**
Method| Returns| Description  
---|---|---  
`to_dict()`| `dict`| Convert turn to dictionary  
`load_from_dict(dict_list)`| `list[LlmTurn]`| Create turns from list of dicts  
###  LlmFileUrl 
Container for file URL and type information.
Field| Type| Description  
---|---|---  
`url`| `str`| URL where the file can be accessed  
`type`| `FileType`| Type of file (IMAGE, PDF, TEXT)  
###  FileContent 
Container for file content, used for direct file uploads to LLM providers. Add instances to `client.file_content` list.
Field| Type| Description  
---|---|---  
`mime_type`| `str`| MIME type of the content (e.g., `image/png`)  
`content`| `bytes`| Base64-encoded file content  
`size`| `int`| Size of the original file in bytes  
**Example:**
    ```python
    import base64
    from canvas_sdk.clients.llms.structures import FileContent
    # From file bytes
    with open("image.png", "rb") as f:
        file_bytes = f.read()
    file_content = FileContent(
        mime_type="image/png",
        content=base64.b64encode(file_bytes),
        size=len(file_bytes),
    )
    # Add to client
    client.file_contents.append(file_content)
    ```
###  BaseModelLlmJson 
Base class for structured JSON output schemas. Extends Pydantic's `BaseModel` with:
  - `additionalProperties: false` in JSON schema
  - Automatic camelCase field name conversion
**Usage:**
    ```python
    from pydantic import Field
    from canvas_sdk.clients.llms.structures import BaseModelLlmJson
    class MySchema(BaseModelLlmJson):
        field_name: str = Field(description="Description for the LLM")
        another_field: int = Field(description="Another description")
    ```
##  Constants (Enums) 
###  FileType 
Supported file types for LLM file attachments.
Value| Description  
---|---  
`IMAGE`| Image files (PNG, JPEG, GIF)  
`PDF`| PDF documents  
`TEXT`| Plain text files  
###  Role Constants 
Available on all LLM client classes:
Constant| Value| Description  
---|---|---  
`ROLE_SYSTEM`| `"system"`| System/instruction role  
`ROLE_USER`| `"user"`| User message role  
`ROLE_MODEL`| `"model"`| Model/assistant response role  
##  Complete Plugin Example 
Here's a complete example of using the LLMs client in a Canvas plugin:
    ```python
    import base64
    from http import HTTPStatus
    from pydantic import Field
    from canvas_sdk.clients.llms import LlmOpenai
    from canvas_sdk.clients.llms.constants import FileType
    from canvas_sdk.clients.llms.structures import BaseModelLlmJson, FileContent, LlmFileUrl
    from canvas_sdk.clients.llms.structures.settings import LlmSettingsGpt4
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, PlainTextResponse, Response
    from canvas_sdk.handlers.simple_api import Credentials, SimpleAPI, api
    from canvas_sdk.handlers.simple_api.api import FileFormPart, StringFormPart
    class AnimalCount(BaseModelLlmJson):
        """Structured response for animal counting."""
        dogs: int = Field(description="Number of dogs in the image")
        cats: int = Field(description="Number of cats in the image")
        total: int = Field(description="Total number of animals")
    class LlmHandler(SimpleAPI):
        """Simple API handler for LLM operations."""
        def authenticate(self, credentials: Credentials) -> bool:
            return True
        def _llm_client(self) -> LlmOpenai:
            """Create LLM client from plugin secrets."""
            return LlmOpenai(LlmSettingsGpt4(
                api_key=self.secrets["LlmKey"],
                model="gpt-4o",
                temperature=0.5,
            ))
        @api.post("/chat")
        def chat(self) -> list[Response | Effect]:
            """Handle a chat conversation."""
            client = self._llm_client()
            # Process conversation turns from request
            for turn in self.request.json():
                if turn.get("role") == "system":
                    client.set_system_prompt([turn.get("prompt", "")])
                elif turn.get("role") == "user":
                    client.set_user_prompt([turn.get("prompt", "")])
                else:
                    client.set_model_prompt([turn.get("prompt", "")])
            response = client.attempt_requests(attempts=2)[0]
            return [PlainTextResponse(response.response, status_code=response.code)]
        @api.post("/analyze_image")
        def analyze_image(self) -> list[Response | Effect]:
            """Analyze an image for animal content via URL."""
            client = self._llm_client()
            url = self.request.json().get("url")
            if not url:
                return [JSONResponse({"error": "URL required"}, status_code=HTTPStatus.BAD_REQUEST)]
            # Set up structured output
            client.set_schema(AnimalCount)
            client.set_system_prompt(["Count the animals in the provided image."])
            client.set_user_prompt(["Identify and count all animals in this image."])
            client.add_url_file(LlmFileUrl(url=url, type=FileType.IMAGE))
            responses = client.attempt_requests(attempts=2)
            content = [r.to_dict() for r in responses]
            return [JSONResponse(content, status_code=HTTPStatus.OK)]
        @api.post("/file")
        def file(self) -> list[Response | Effect]:
            """Analyze uploaded file content using LLM.
            Accepts multipart form data with 'file' and 'input' fields.
            """
            content = b""
            mime_type = ""
            user_input = ""
            # Parse form data
            form_data = self.request.form_data()
            if "file" in form_data and isinstance(form_data["file"], FileFormPart):
                content = form_data["file"].content
                mime_type = form_data["file"].content_type
            if "input" in form_data and isinstance(form_data["input"], StringFormPart):
                user_input = form_data["input"].value
            if not (content and mime_type and user_input):
                return [PlainTextResponse("Missing file or input", status_code=HTTPStatus.BAD_REQUEST)]
            client = self._llm_client()
            # Create FileContent with base64-encoded data
            file = FileContent(
                mime_type=mime_type,
                content=base64.b64encode(content),
                size=len(content),
            )
            client.file_content.append(file)
            client.set_system_prompt(["Answer the question about the file clearly and concisely."])
            client.set_user_prompt([user_input])
            response = client.attempt_requests(attempts=1)[0]
            return [PlainTextResponse(response.response, status_code=response.code)]
    ```
##  Error Handling 
The LLM clients return `LlmResponse` objects with HTTP status codes indicating success or failure.
    ```python
    from http import HTTPStatus
    response = client.request()
    if response.code == HTTPStatus.OK:
        print(f"Success: {response.response}")
    elif response.code == HTTPStatus.TOO_MANY_REQUESTS:
        print("Rate limited - try again later")
    elif response.code == HTTPStatus.UNAUTHORIZED:
        print("Invalid API key")
    elif response.code == HTTPStatus.BAD_REQUEST:
        print(f"Bad request: {response.response}")
    else:
        print(f"Error {response.code}: {response.response}")
    ```
When using `attempt_requests`, the method will automatically retry on failure:
    ```python
    responses = client.attempt_requests(attempts=3)
    # Check if any attempt succeeded
    successful = [r for r in responses if r.code == HTTPStatus.OK]
    if successful:
        print(f"Success after {len(responses)} attempt(s)")
    else:
        print(f"All {len(responses)} attempts failed")
    ```
##  Provider-Specific Notes 
###  OpenAI 
  - Uses the Responses API (`/v1/responses`)
  - Supports images and PDFs via URL (`add_url_file`) or direct content (`file_content`)
  - System prompts are sent as `instructions`
  - Direct file content uses `input_image` for images and `input_file` for PDFs
###  Anthropic 
  - Uses the Messages API (`/v1/messages`)
  - Supports images, PDFs, and text files via URL or direct content
  - Text files are base64-decoded and sent as plain text
  - Structured output uses tool calling
###  Google Gemini 
  - Uses the Generative Language API
  - Files via URL are downloaded and converted to base64 automatically
  - Supports both URL-based and direct file content
  - Maximum file size limit of 10MB per request (combined)
  - Structured output uses `responseJsonSchema`
##  Additional Resources 
  - [OpenAI API Documentation](https://platform.openai.com/docs/api-reference)
  - [Anthropic API Documentation](https://docs.anthropic.com/en/api)
  - [Google Gemini API Documentation](https://ai.google.dev/gemini-api/docs)
  - [Example Plugin](/sdk/example-llm/) \- Documentation for the example plugin
  - [Source Code](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/llm) \- View the source on GitHub

---

# SendGrid

Source: https://docs.canvasmedical.com/sdk/clients-sendgrid/

The Canvas SDK SendGrid client provides a simple interface for sending emails, managing webhooks, and querying email logs using the SendGrid API.
##  Requirements 
  - **SendGrid API Key** : Create one at https://app.sendgrid.com/settings/api_keys
  - **Authenticated Domain** : Configure at https://app.sendgrid.com/settings/sender_auth
##  Imports 
The SendGrid client is included in the Canvas SDK. Import the necessary components:
    ```python
    from canvas_sdk.clients.sendgrid.libraries import EmailClient
    from canvas_sdk.clients.sendgrid.constants import RecipientType
    from canvas_sdk.clients.sendgrid.structures import (
        Address,
        BodyContent,
        Email,
        Recipient,
        RequestFailed,
        Settings,
    )
    ```
##  Initialize the Client 
    ```python
    client = EmailClient(Settings(key="your_sendgrid_api_key"))
    ```
##  Send a Simple Text Email 
    ```python
    from canvas_sdk.clients.sendgrid.libraries import EmailClient
    from canvas_sdk.clients.sendgrid.constants import RecipientType
    from canvas_sdk.clients.sendgrid.structures import (
        Address, BodyContent, Email, Recipient, RequestFailed, Settings
    )
    client = EmailClient(Settings(key="your_api_key"))
    email = Email(
        sender=Address(email="sender@example.com", name="Sender Name"),
        reply_tos=[Address(email="reply@example.com", name="Reply To")],
        recipients=[
            Recipient(address=Address(email="recipient@example.com", name="Recipient"), type=RecipientType.TO)
        ],
        subject="Hello from Canvas SDK",
        bodies=[BodyContent(type="text/plain", value="This is a test email.")],
        attachments=[],
        send_at=Email.now(),
    )
    try:
        client.simple_send(email)
        print("Email sent successfully!")
    except RequestFailed as e:
        print(f"Failed to send email: {e.message} (HTTP {e.status_code})")
    ```
##  Send an HTML Email with CC 
    ```python
    email = Email(
        sender=Address(email="sender@example.com", name="Sender"),
        reply_tos=[Address(email="reply@example.com", name="Reply To")],
        recipients=[
            Recipient(address=Address(email="to@example.com", name="To"), type=RecipientType.TO),
            Recipient(address=Address(email="cc@example.com", name="CC"), type=RecipientType.CC),
        ],
        subject="HTML Email Example",
        bodies=[
            BodyContent(type="text/plain", value="Plain text fallback"),
            BodyContent(type="text/html", value="<html><body><h1>Hello!</h1><p>This is HTML content.</p></body></html>"),
        ],
        attachments=[],
        send_at=Email.now(),
    )
    client.simple_send(email)
    ```
##  Send an Email with Attachment 
    ```python
    from canvas_sdk.clients.sendgrid.structures import Attachment
    # Create attachment from URL
    attachment = Attachment.from_url(
        url="https://example.com/document.pdf",
        headers={},
        filename="document.pdf"
    )
    email = Email(
        sender=Address(email="sender@example.com", name="Sender"),
        reply_tos=[Address(email="reply@example.com", name="Reply To")],
        recipients=[
            Recipient(address=Address(email="to@example.com", name="To"), type=RecipientType.TO)
        ],
        subject="Email with Attachment",
        bodies=[BodyContent(type="text/plain", value="Please find attached document.")],
        attachments=[attachment],
        send_at=Email.now(),
    )
    client.simple_send(email)
    ```
##  Send an Email with Inline Image 
    ```python
    # Create inline image attachment
    inline_image = Attachment.from_url_inline(
        url="https://example.com/logo.png",
        headers={},
        filename="logo.png",
        content_id="logo123"
    )
    email = Email(
        sender=Address(email="sender@example.com", name="Sender"),
        reply_tos=[Address(email="reply@example.com", name="Reply To")],
        recipients=[
            Recipient(address=Address(email="to@example.com", name="To"), type=RecipientType.TO)
        ],
        subject="Email with Inline Image",
        bodies=[
            BodyContent(type="text/plain", value="See image in HTML version"),
            BodyContent(type="text/html", value='<html><body><img src="cid:logo123" width="200"/></body></html>'),
        ],
        attachments=[inline_image],
        send_at=Email.now(),
    )
    client.simple_send(email)
    ```
##  Query Sent Emails 
    ```python
    from datetime import datetime
    from canvas_sdk.clients.sendgrid.constants import CriterionOperation
    from canvas_sdk.clients.sendgrid.structures import CriterionDatetime, LoggedEmailCriteria
    criteria = LoggedEmailCriteria(
        message_id="",
        subject="",
        to_email="recipient@example.com",
        reason="",
        status=[],
        message_created_at=[
            CriterionDatetime(
                date_time=datetime(2024, 1, 1),
                operation=CriterionOperation.GREATER_THAN_OR_EQUAL
            )
        ],
    )
    for email in client.logged_emails(criteria, up_to=10):
        print(f"Subject: {email.subject}, Status: {email.status.value}")
    ```
##  EmailClient 
The main class for interacting with the SendGrid API.
###  Constructor 
    ```python
    EmailClient(settings: Settings)
    ```
Parameter| Type| Description  
---|---|---  
`settings`| `Settings`| Configuration object containing the API key  
###  Sending Emails 
####  `simple_send(email: Email) -> bool`
Send an email using a structured `Email` object. This is the recommended method for most use cases.
**Returns:** `True` on success
**Raises:** `RequestFailed` on error
####  `prepared_send(data: dict) -> bool`
Send an email using a raw dictionary following SendGrid's API schema. Use this for advanced cases not covered by `simple_send`.
**Parameters:**
  - `data`: Dictionary following [SendGrid's mail send schema](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send#request-body)
**Returns:** `True` on success
**Raises:** `RequestFailed` on error
###  Email Logs 
####  `logged_emails(criteria: LoggedEmailCriteria, up_to: int) -> Iterator[SentEmail]`
Query sent emails matching the specified criteria.
**Parameters:**
  - `criteria`: Filter criteria for the query
  - `up_to`: Maximum number of results to return
**Returns:** Iterator of `SentEmail` objects
####  `logged_email(message_id: str) -> SentEmailDetail`
Get detailed information about a specific email including its event history.
**Parameters:**
  - `message_id`: The SendGrid message ID
**Returns:** `SentEmailDetail` object with full event history
###  Inbound Parse Webhooks 
Configure webhooks to receive incoming emails.
Method| Description  
---|---  
`parser_setting_add(setting: ParseSetting) -> ParseSetting`| Create a new inbound parse webhook  
`parser_setting_delete(hostname: str) -> bool`| Delete a webhook by hostname  
`parser_setting_get(hostname: str) -> ParseSetting`| Get webhook configuration by hostname  
`parser_setting_list() -> Iterator[ParseSetting]`| List all inbound parse webhooks  
Requires MX record setup pointing to `mx.sendgrid.net`, for example:
host| type| priority| TTL| value  
---|---|---|---|---  
`canvas`| `MX`| 10| 1 hr| `mx.sendgrid.net`  
###  Event Webhooks 
Configure webhooks to receive email delivery status notifications.
Method| Description  
---|---  
`event_webhook_add(event: EventWebhook) -> EventWebhookRecord`| Create a new event webhook  
`event_webhook_delete(event_webhook_id: str) -> bool`| Delete a webhook by ID  
`event_webhook_get(event_webhook_id: str) -> EventWebhookRecord`| Get webhook by ID  
`event_webhook_list() -> Iterator[EventWebhookRecord]`| List all event webhooks  
`event_webhook_sign(event_webhook_id: str, enabled: bool) -> str`| Enable/disable signature verification, returns public key  
##  Data Structures 
###  Settings 
Configuration for the EmailClient.
Field| Type| Description  
---|---|---  
`key`| `str`| SendGrid API key  
###  Address 
Represents an email address with display name.
Field| Type| Description  
---|---|---  
`email`| `str`| Email address  
`name`| `str`| Display name  
###  Recipient 
Represents an email recipient with type.
Field| Type| Description  
---|---|---  
`address`| `Address`| Email address object  
`type`| `RecipientType`| TO, CC, or BCC  
###  BodyContent 
Represents email body content with MIME type.
Field| Type| Description  
---|---|---  
`type`| `str`| MIME type (e.g., `text/plain`, `text/html`)  
`value`| `str`| Content  
###  Email 
Complete email message structure.
Field| Type| Description  
---|---|---  
`sender`| `Address`| Sender email address  
`reply_tos`| `list[Address]`| Reply-to addresses  
`recipients`| `list[Recipient]`| List of recipients (TO/CC/BCC)  
`subject`| `str`| Email subject line  
`bodies`| `list[BodyContent]`| Email body content(s)  
`attachments`| `list[Attachment]`| File attachments  
`send_at`| `int`| Unix timestamp for sending  
**Class Methods:**
Method| Description  
---|---  
`Email.now() -> int`| Get current timestamp for immediate send  
`Email.timestamp(dt: datetime) -> int`| Convert datetime to Unix timestamp  
###  Attachment 
Represents an email attachment.
Field| Type| Description  
---|---|---  
`content_id`| `str`| ID for inline references  
`content`| `str`| Base64 encoded content  
`type`| `str`| MIME type  
`filename`| `str`| Filename  
`disposition`| `AttachmentDisposition`| ATTACHMENT or INLINE  
**Class Methods:**
Method| Description  
---|---  
`Attachment.from_url(url, headers, filename) -> Attachment`| Create attachment from URL  
`Attachment.from_url_inline(url, headers, filename, content_id) -> Attachment`| Create inline attachment from URL  
###  LoggedEmailCriteria 
Search criteria for querying sent emails.
Field| Type| Description  
---|---|---  
`message_id`| `str`| Filter by message ID  
`subject`| `str`| Filter by subject  
`to_email`| `str`| Filter by recipient email  
`reason`| `str`| Filter by reason  
`status`| `list[StatusEmail]`| Filter by status(es)  
`message_created_at`| `list[CriterionDatetime]`| Filter by creation date/time  
###  CriterionDatetime 
DateTime comparison for email queries.
Field| Type| Description  
---|---|---  
`date_time`| `datetime`| Date/time to compare  
`operation`| `CriterionOperation`| Comparison operator  
###  SentEmail 
Basic information about a sent email (returned by `logged_emails`).
Field| Type| Description  
---|---|---  
`from_email`| `str`| Sender email address  
`message_id`| `str`| SendGrid message ID  
`subject`| `str`| Email subject  
`to_email`| `str`| Recipient email address  
`reason`| `str`| Delivery failure reason  
`status`| `StatusEmail`| Delivery status  
`created_at`| `datetime`| Creation timestamp  
###  SentEmailDetail 
Detailed sent email information with event history (returned by `logged_email`).
Field| Type| Description  
---|---|---  
`from_email`| `str`| Sender email address  
`message_id`| `str`| SendGrid message ID  
`subject`| `str`| Email subject  
`to_email`| `str`| Recipient email address  
`status`| `StatusEmail`| Current delivery status  
`events`| `list[EmailEvent]`| List of lifecycle events  
###  EmailEvent 
Represents an event in an email's lifecycle.
Field| Type| Description  
---|---|---  
`event`| `EventEmail`| Event type  
`email`| `str`| Recipient email address  
`message_id`| `str`| SendGrid message ID  
`event_id`| `str`| Unique event ID  
`on_datetime`| `datetime`| Event timestamp  
`reason`| `str`| Reason (for bounce, dropped events)  
`response`| `str`| Server response (for delivered events)  
`url`| `str`| Clicked/opened URL (for click, open)  
`attempt`| `int`| Delivery attempt number (for deferred)  
###  ParseSetting 
Configuration for inbound email parsing.
Field| Type| Description  
---|---|---  
`url`| `str`| Webhook URL to receive parsed emails  
`hostname`| `str`| Domain to receive emails (requires MX record)  
`spam_check`| `bool`| Enable spam filtering  
`send_raw`| `bool`| Send raw MIME message instead of parsed  
###  EventWebhook 
Configuration for outbound email event notifications.
Field| Type| Description  
---|---|---  
`enabled`| `bool`| Whether webhook is active  
`url`| `str`| Webhook URL  
`friendly_name`| `str`| Display name  
`delivered`| `bool`| Track delivered events  
`bounce`| `bool`| Track bounce events  
`dropped`| `bool`| Track dropped events  
`spam_report`| `bool`| Track spam report events  
`processed`| `bool`| Track processed events  
`open`| `bool`| Track open events  
`click`| `bool`| Track click events  
`unsubscribe`| `bool`| Track unsubscribe events  
`group_resubscribe`| `bool`| Track group resubscribe events  
`group_unsubscribe`| `bool`| Track group unsubscribe events  
###  EventWebhookRecord 
Stored event webhook with metadata (extends EventWebhook).
Field| Type| Description  
---|---|---  
 _(all fields from EventWebhook)_|  |   
`id`| `str`| Webhook ID  
`public_key`| `str`| Public key for signature verification  
`created_date`| `datetime`| Creation timestamp  
`updated_date`| `datetime`| Last update timestamp  
###  ParsedEmail 
Represents an inbound email received via the Inbound Parse webhook.
Field| Type| Description  
---|---|---  
`headers`| `list[ParsedHeader]`| Email headers  
`charsets`| `dict[str, str]`| Character set mappings  
`envelope`| `ParsedEnvelope`| SMTP envelope information  
`email_from`| `str`| Sender address  
`email_to`| `str`| Recipient address  
`subject`| `str`| Email subject  
`text`| `str`| Plain text body  
`html`| `str`| HTML body  
`attachments`| `int`| Number of attachments  
`attachment_info`| `dict[str, ParsedAttachment]`| Attachment metadata  
`content_ids`| `dict[str, str]`| Content ID mappings  
`spf`| `str`| SPF verification result  
`dkim`| `str`| DKIM verification result  
`spam_report`| `list[str]`| Spam analysis report  
`spam_score`| `float`| Spam score  
##  Constants (Enums) 
###  RecipientType 
Value| Description  
---|---  
`TO`| Primary recipient  
`CC`| Carbon copy  
`BCC`| Blind carbon copy  
###  AttachmentDisposition 
Value| Description  
---|---  
`ATTACHMENT`| Standard file attachment  
`INLINE`| Embedded in email body  
###  StatusEmail 
Email delivery status values.
Value| Description  
---|---  
`PROCESSED`| Email processed by SendGrid  
`DELIVERED`| Successfully delivered  
`NOT_DELIVERED`| Delivery failed  
`DEFERRED`| Temporarily delayed  
`DROPPED`| Dropped by SendGrid  
`BOUNCED`| Bounced back  
`BLOCKED`| Blocked by recipient  
###  EventEmail 
Email event types for webhooks.
Value| Description  
---|---  
`BOUNCE`| Email bounced  
`CLICK`| Link clicked  
`DEFERRED`| Delivery deferred  
`DELIVERED`| Email delivered  
`DROPPED`| Email dropped  
`CANCEL_DROP`| Drop cancelled  
`OPEN`| Email opened  
`PROCESSED`| Email processed  
`RECEIVED`| Inbound email received  
`SPAM_REPORT`| Reported as spam  
`GROUP_UNSUBSCRIBE`| Unsubscribed from group  
`GROUP_RESUBSCRIBE`| Resubscribed to group  
`UNSUBSCRIBE`| Unsubscribed  
###  CriterionOperation 
Comparison operators for email log queries.
Value| Symbol| Description  
---|---|---  
`GREATER_THAN`| `>`| Greater than  
`GREATER_THAN_OR_EQUAL`| `>=`| Greater than or equal  
`LOWER_THAN`| `<`| Less than  
`LOWER_THAN_OR_EQUAL`| `<=`| Less than or equal  
`EQUAL`| `=`| Equal to  
##  Error Handling 
###  RequestFailed 
Exception raised when a SendGrid API request fails (extends `RuntimeError`).
Attribute| Type| Description  
---|---|---  
`status_code`| `int`| HTTP status code  
`message`| `str`| Error message from SendGrid  
**Example:**
    ```python
    try:
        client.simple_send(email)
    except RequestFailed as e:
        print(f"Error {e.status_code}: {e.message}")
    ```
##  Webhook Setup Examples 
###  Inbound Parse Webhook (Receive Incoming Emails) 
    ```python
    from canvas_sdk.clients.sendgrid.structures import ParseSetting
    # Note: Requires MX record for the hostname pointing to mx.sendgrid.net
    setting = ParseSetting(
        url="https://your-app.com/api/incoming-email",
        hostname="mail.yourdomain.com",
        spam_check=True,
        send_raw=False,
    )
    try:
        created = client.parser_setting_add(setting)
        print(f"Inbound webhook created for {created.hostname}")
    except RequestFailed as e:
        print(f"Failed: {e.message}")
    ```
###  Event Webhook (Track Outbound Email Status) 
    ```python
    from canvas_sdk.clients.sendgrid.structures import EventWebhook
    webhook = EventWebhook(
        url="https://your-app.com/api/email-events",
        enabled=True,
        friendly_name="My Email Tracker",
        delivered=True,
        bounce=True,
        dropped=True,
        spam_report=True,
        processed=True,
        open=True,
        click=True,
        unsubscribe=False,
        group_resubscribe=False,
        group_unsubscribe=False,
    )
    try:
        created = client.event_webhook_add(webhook)
        print(f"Event webhook created with ID: {created.id}")
    except RequestFailed as e:
        print(f"Failed: {e.message}")
    ```
##  Additional Resources 
  - [SendGrid API Documentation](https://www.twilio.com/docs/sendgrid/api-reference)
  - [Inbound Parse Webhook Setup](https://www.twilio.com/docs/sendgrid/for-developers/parsing-email/inbound-email)
  - [Event Webhook Documentation](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/event)
  - [Example Plugin](/sdk/example-sendgrid_email/) \- Documentation for the example plugin
  - [Source Code](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/sendgrid_email) \- View the source on GitHub

---

# Twilio

Source: https://docs.canvasmedical.com/sdk/clients-twilio/

The Canvas SDK Twilio client provides a simple interface for sending SMS and MMS messages, managing phone numbers, and handling webhooks using the Twilio API.
##  Requirements 
  - **Twilio Account SID** : Found in your [Twilio Console](https://console.twilio.com/)
  - **Twilio API Key and Secret** : Create at [API Keys](https://console.twilio.com/us1/account/keys-credentials/api-keys)
  - **Twilio Phone Number** : Purchase at [Phone Numbers](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming)
##  Imports 
The Twilio client is included in the Canvas SDK. Import the necessary components:
    ```python
    from canvas_sdk.clients.twilio.libraries import SmsClient
    from canvas_sdk.clients.twilio.structures import Settings, SmsMms, RequestFailed
    ```
##  Initialize the Client 
    ```python
    settings = Settings(
        account_sid="your_account_sid",
        key="your_api_key",
        secret="your_api_secret",
    )
    client = SmsClient(settings)
    ```
##  Send a Simple SMS 
    ```python
    from canvas_sdk.clients.twilio.libraries import SmsClient
    from canvas_sdk.clients.twilio.structures import Settings, SmsMms, RequestFailed
    # Initialize the client
    settings = Settings(
        account_sid="ACxxxxxxxxxxxxxxxxx",
        key="SKxxxxxxxxxxxxxxxxx",
        secret="your_api_secret",
    )
    client = SmsClient(settings)
    # First, get your phone number SID
    phones = list(client.account_phone_numbers())
    phone = phones[0]  # Use the first phone number
    print(f"Using phone: {phone.phone_number} (SID: {phone.sid})")
    # Create and send the SMS
    sms = SmsMms(
        number_from=phone.phone_number,
        number_from_sid=phone.sid,
        number_to="+1234567890",
        message="Hello from Canvas SDK!",
        media_url="",
        status_callback_url="",
    )
    try:
        message = client.send_sms_mms(sms)
        print(f"Message sent! SID: {message.sid}, Status: {message.status.value}")
    except RequestFailed as e:
        print(f"Failed to send: {e.message} (HTTP {e.status_code})")
    ```
##  Send an MMS with Image 
    ```python
    # Create an MMS with an image attachment
    mms = SmsMms(
        number_from=phone.phone_number,
        number_from_sid=phone.sid,
        number_to="+1234567890",
        message="Check out this image!",
        media_url="https://example.com/image.jpg",
        status_callback_url="",
    )
    try:
        message = client.send_sms_mms(mms)
        print(f"MMS sent! SID: {message.sid}")
    except RequestFailed as e:
        print(f"Failed to send: {e.message}")
    ```
##  Send SMS with Status Callback 
    ```python
    # Send SMS with a callback URL to track delivery status
    sms = SmsMms(
        number_from=phone.phone_number,
        number_from_sid=phone.sid,
        number_to="+1234567890",
        message="Message with tracking",
        media_url="",
        status_callback_url="https://your-app.com/api/sms-status",
    )
    message = client.send_sms_mms(sms)
    print(f"Message queued with callback. SID: {message.sid}")
    ```
##  Retrieve Message History 
    ```python
    from canvas_sdk.clients.twilio.constants import DateOperation
    # Get all messages (no filters)
    for message in client.retrieve_all_sms("", "", "", DateOperation.ON_EXACTLY):
        print(f"{message.date_sent}: {message.number_from} -> {message.number_to}: {message.body}")
    # Get messages sent to a specific number
    for message in client.retrieve_all_sms("+1234567890", "", "", DateOperation.ON_EXACTLY):
        print(f"To {message.number_to}: {message.body}")
    # Get messages from a specific date onwards
    for message in client.retrieve_all_sms("", "", "2024-01-01", DateOperation.ON_AND_AFTER):
        print(f"{message.date_sent}: {message.body}")
    ```
##  Handle Inbound Messages (Webhook) 
When Twilio receives an SMS to your number, it can call your webhook. Parse the callback data:
    ```python
    from canvas_sdk.clients.twilio.structures import StatusInbound, TwiMlMessage
    def handle_inbound_sms(raw_body: str) -> str:
        """Process incoming SMS and return TwiML response."""
        # Parse the incoming message
        inbound = StatusInbound.callback_inbound(raw_body)
        print(f"Received from {inbound.number_from}: {inbound.body}")
        # Create a reply using TwiML
        if "hello" in inbound.body.lower():
            reply = TwiMlMessage.instance("Hello! Nice to hear from you!")
        else:
            reply = TwiMlMessage.instance("Thanks for your message!")
        return reply.to_xml()
    ```
##  Reply with MMS (TwiML) 
    ```python
    from canvas_sdk.clients.twilio.structures import TwiMlMessage
    # Create a TwiML response with text and image
    reply = TwiMlMessage.instance_with_media(
        message_text="Here's a picture for you!",
        media_url="https://example.com/image.jpg"
    )
    xml_response = reply.to_xml()
    # Returns TwiML like:
    # <?xml version="1.0" encoding="UTF-8"?>
    # <Response><Message><Body>Here's a picture for you!</Body><Media>https://example.com/image.jpg</Media></Message></Response>
    ```
##  SmsClient 
The main class for interacting with the Twilio SMS/MMS API.
###  Constructor 
    ```python
    SmsClient(settings: Settings)
    ```
Parameter| Type| Description  
---|---|---  
`settings`| `Settings`| Configuration object with Twilio credentials  
###  Phone Number Management 
####  `account_phone_numbers() -> Iterator[Phone]`
Retrieve all phone numbers associated with the Twilio account.
    ```python
    for phone in client.account_phone_numbers():
        print(f"{phone.friendly_name}: {phone.phone_number}")
        print(f"  SMS: {phone.capabilities.sms}, MMS: {phone.capabilities.mms}")
    ```
**Returns:** Iterator of `Phone` objects
**Raises:** `RequestFailed` on error
####  `account_phone_number(phone_sid: str) -> Phone`
Retrieve details for a specific phone number by its SID.
    ```python
    phone = client.account_phone_number("PNxxxxxxxxxxxxxxxxx")
    print(f"Phone: {phone.phone_number}, Status: {phone.status}")
    ```
Parameter| Type| Description  
---|---|---  
`phone_sid`| `str`| The Twilio SID of the phone  
**Returns:** `Phone` object
**Raises:** `RequestFailed` on error
####  `set_inbound_webhook(phone_sid: str, webhook_url: str, method: HttpMethod) -> bool`
Configure the webhook URL for receiving inbound messages on a phone number.
    ```python
    from canvas_sdk.clients.twilio.constants import HttpMethod
    success = client.set_inbound_webhook(
        phone_sid="PNxxxxxxxxxxxxxxxxx",
        webhook_url="https://your-app.com/api/inbound-sms",
        method=HttpMethod.POST
    )
    ```
Parameter| Type| Description  
---|---|---  
`phone_sid`| `str`| The Twilio SID of the phone  
`webhook_url`| `str`| URL to receive inbound messages  
`method`| `HttpMethod`| HTTP method (GET or POST)  
**Returns:** `True` on success
**Raises:** `RequestFailed` on error
###  Sending Messages 
####  `send_sms_mms(sms_mms: SmsMms) -> Message`
Send an SMS or MMS message. The method automatically validates phone capabilities.
    ```python
    sms = SmsMms(
        number_from="+15551234567",
        number_from_sid="PNxxxxxxxxxxxxxxxxx",
        number_to="+15559876543",
        message="Hello!",
        media_url="",  # Empty for SMS, URL for MMS
        status_callback_url="https://your-app.com/status",
    )
    message = client.send_sms_mms(sms)
    print(f"Sent! SID: {message.sid}, Status: {message.status.value}")
    ```
Parameter| Type| Description  
---|---|---  
`sms_mms`| `SmsMms`| Message details to send  
**Returns:** `Message` object with sent message details
**Raises:** `RequestFailed` if the phone lacks required capabilities or API fails
###  Retrieving Messages 
####  `retrieve_sms(message_id: str) -> Message`
Get details for a specific message by its SID.
    ```python
    message = client.retrieve_sms("SMxxxxxxxxxxxxxxxxx")
    print(f"Status: {message.status.value}")
    print(f"Body: {message.body}")
    print(f"Sent: {message.date_sent}")
    ```
Parameter| Type| Description  
---|---|---  
`message_id`| `str`| The Twilio message SID  
**Returns:** `Message` object
**Raises:** `RequestFailed` on error
####  `retrieve_all_sms(number_to, number_from, date_sent, date_operation) -> Iterator[Message]`
Retrieve messages with optional filtering.
    ```python
    from canvas_sdk.clients.twilio.constants import DateOperation
    # All messages
    for msg in client.retrieve_all_sms("", "", "", DateOperation.ON_EXACTLY):
        print(msg.body)
    # Messages to a specific number
    for msg in client.retrieve_all_sms("+15551234567", "", "", DateOperation.ON_EXACTLY):
        print(msg.body)
    # Messages from a specific date
    for msg in client.retrieve_all_sms("", "", "2024-06-01", DateOperation.ON_AND_AFTER):
        print(f"{msg.date_sent}: {msg.body}")
    ```
Parameter| Type| Description  
---|---|---  
`number_to`| `str`| Filter by recipient (empty = no filter)  
`number_from`| `str`| Filter by sender (empty = no filter)  
`date_sent`| `str`| Date to filter by (YYYY-MM-DD format)  
`date_operation`| `DateOperation`| How to compare the date  
**Returns:** Iterator of `Message` objects
**Raises:** `RequestFailed` on error
####  `delete_sms(message_id: str) -> bool`
Delete a message from Twilio.
    ```python
    deleted = client.delete_sms("SMxxxxxxxxxxxxxxxxx")
    print(f"Deleted: {deleted}")
    ```
Parameter| Type| Description  
---|---|---  
`message_id`| `str`| The Twilio message SID  
**Returns:** `True` on success
**Raises:** `RequestFailed` on error
###  Media Handling 
####  `retrieve_media_list(message_id: str) -> Iterator[Media]`
Get all media attachments for a message.
    ```python
    for media in client.retrieve_media_list("SMxxxxxxxxxxxxxxxxx"):
        print(f"Media SID: {media.sid}")
        print(f"Content Type: {media.content_type}")
    ```
Parameter| Type| Description  
---|---|---  
`message_id`| `str`| The Twilio message SID  
**Returns:** Iterator of `Media` objects
**Raises:** `RequestFailed` on error
####  `retrieve_raw_media(message_id: str, media_sid: str) -> bytes`
Download the raw binary content of a media attachment.
    ```python
    for media in client.retrieve_media_list(message_sid):
        content = client.retrieve_raw_media(message_sid, media.sid)
        # Save to file
        with open(f"media_{media.sid}.jpg", "wb") as f:
            f.write(content)
    ```
Parameter| Type| Description  
---|---|---  
`message_id`| `str`| The Twilio message SID  
`media_sid`| `str`| The Twilio media SID  
**Returns:** Raw binary content (`bytes`)
**Raises:** `RequestFailed` on error
##  Data Structures 
###  Settings 
Configuration for the SmsClient.
Field| Type| Description  
---|---|---  
`account_sid`| `str`| Twilio Account SID  
`key`| `str`| Twilio API Key SID  
`secret`| `str`| Twilio API Key Secret  
###  SmsMms 
Represents an SMS or MMS message to send.
Field| Type| Description  
---|---|---  
`number_from`| `str`| Sender phone number (E.164 format)  
`number_from_sid`| `str`| Twilio SID of the sender phone number  
`number_to`| `str`| Recipient phone number (E.164 format)  
`message`| `str`| Text content of the message  
`media_url`| `str`| URL of media to attach (empty for SMS)  
`status_callback_url`| `str`| URL to receive delivery status updates  
###  Message 
Represents a Twilio message with full metadata.
Field| Type| Description  
---|---|---  
`sid`| `str`| Unique message identifier  
`body`| `str`| Message text content  
`date_created`| `datetime`| When the message was created  
`date_sent`| `datetime \| None`| When the message was sent  
`date_updated`| `datetime`| When the message was last updated  
`direction`| `MessageDirection`| Message direction  
`number_from`| `str`| Sender phone number  
`number_to`| `str`| Recipient phone number  
`price`| `str \| None`| Cost of the message  
`price_unit`| `str`| Currency of the price  
`error_code`| `int \| None`| Error code if failed  
`error_message`| `str \| None`| Error description if failed  
`uri`| `str`| API URI for this resource  
`count_media`| `int \| None`| Number of media attachments  
`count_segments`| `int`| Number of SMS segments  
`status`| `MessageStatus`| Current message status  
`sub_resource_uris`| `dict[str, str] \| None`| URIs to related resources  
###  Phone 
Represents a Twilio phone number with configuration.
Field| Type| Description  
---|---|---  
`account_sid`| `str`| Twilio Account SID  
`capabilities`| `Capabilities`| Phone capabilities (SMS, MMS, etc.)  
`date_created`| `datetime`| When added to account  
`date_updated`| `datetime`| Last configuration update  
`friendly_name`| `str`| User-defined name  
`phone_number`| `str`| Phone number in E.164 format  
`sid`| `str`| Unique phone number identifier  
`sms_fallback_method`| `HttpMethod`| HTTP method for fallback URL  
`sms_fallback_url`| `str`| Fallback URL if primary fails  
`sms_method`| `HttpMethod`| HTTP method for SMS webhook  
`sms_url`| `str`| Webhook URL for inbound SMS  
`status_callback_method`| `HttpMethod`| HTTP method for status callbacks  
`status_callback`| `str`| URL for status updates  
`status`| `str`| Current phone number status  
###  Capabilities 
Phone number communication capabilities.
Field| Type| Description  
---|---|---  
`fax`| `bool`| Supports fax  
`mms`| `bool`| Supports MMS (multimedia)  
`sms`| `bool`| Supports SMS (text)  
`voice`| `bool`| Supports voice calls  
###  Media 
Represents media attached to a message.
Field| Type| Description  
---|---|---  
`sid`| `str`| Unique media identifier  
`content_type`| `str`| MIME type (e.g., `image/jpeg`)  
`date_created`| `datetime`| When the media was created  
`date_updated`| `datetime`| When the media was last updated  
`parent_sid`| `str`| Message SID this media belongs to  
`uri`| `str`| API URI for this resource  
###  StatusInbound 
Parsed data from an inbound message webhook callback.
Field| Type| Description  
---|---|---  
`account_sid`| `str`| Twilio Account SID  
`message_sid`| `str`| Message SID  
`messaging_service_sid`| `str`| Messaging Service SID  
`sms_message_sid`| `str`| SMS Message SID  
`sms_sid`| `str`| SMS SID  
`sms_status`| `MessageStatus`| Message status  
`to_country`| `str`| Recipient country  
`to_zip`| `str`| Recipient ZIP code  
`to_state`| `str`| Recipient state  
`to_city`| `str`| Recipient city  
`from_country`| `str`| Sender country  
`from_zip`| `str`| Sender ZIP code  
`from_state`| `str`| Sender state  
`from_city`| `str`| Sender city  
`number_to`| `str`| Recipient phone number  
`number_from`| `str`| Sender phone number  
`body`| `str`| Message text  
`count_media`| `int`| Number of media attachments  
`count_segments`| `int`| Number of SMS segments  
`media_content_type`| `list[str]`| MIME types of attached media  
`media_url`| `list[str]`| URLs of attached media  
**Class Methods:**
Method| Description  
---|---  
`StatusInbound.callback_inbound(raw_body)`| Parse URL-encoded webhook body  
###  StatusOutboundApi 
Parsed data from an outbound message status callback.
Field| Type| Description  
---|---|---  
`account_sid`| `str`| Twilio Account SID  
`message_sid`| `str`| Message SID  
`sms_sid`| `str`| SMS SID  
`sms_status`| `MessageStatus`| SMS status  
`message_status`| `MessageStatus`| Message status  
`number_to`| `str`| Recipient phone number  
`number_from`| `str`| Sender phone number  
**Class Methods:**
Method| Description  
---|---  
`StatusOutboundApi.callback_outbound_api(raw_body)`| Parse URL-encoded webhook body  
###  TwiMlMessage 
Generates TwiML XML for responding to inbound messages.
Field| Type| Description  
---|---|---  
`number_to`| `str`| Recipient (optional in response)  
`number_from`| `str`| Sender (optional in response)  
`status_callback_url`| `str`| Status callback URL  
`message_text`| `str`| Message text content  
`media_url`| `str`| Media URL to attach  
`method`| `HttpMethod\|None`| HTTP method for callbacks  
**Class Methods:**
Method| Description  
---|---  
`TwiMlMessage.instance(message_text) -> TwiMlMessage`| Create text-only TwiML message  
`TwiMlMessage.instance_with_media(message_text, media_url) -> TwiMlMessage`| Create TwiML with media  
**Instance Methods:**
Method| Description  
---|---  
`to_xml() -> str`| Generate TwiML XML string  
**Example:**
    ```python
    # Simple text reply
    reply = TwiMlMessage.instance("Thanks for your message!")
    xml = reply.to_xml()
    # Reply with media
    reply = TwiMlMessage.instance_with_media("Check this out!", "https://example.com/image.jpg")
    xml = reply.to_xml()
    ```
##  Constants (Enums) 
###  MessageStatus 
Message lifecycle status values.
Value| Description  
---|---  
`ACCEPTED`| Message accepted by Twilio  
`SCHEDULED`| Message scheduled for future delivery  
`CANCELED`| Scheduled message was canceled  
`QUEUED`| Message queued for sending  
`SENDING`| Message is being sent  
`SENT`| Message sent to carrier  
`FAILED`| Message failed to send  
`DELIVERED`| Message delivered to recipient  
`UNDELIVERED`| Message could not be delivered  
`PARTIALLY_DELIVERED`| Some recipients received the message  
`RECEIVING`| Inbound message being received  
`RECEIVED`| Inbound message received  
`READ`| Message was read (WhatsApp only)  
###  MessageDirection 
Message direction types.
Value| Description  
---|---  
`INBOUND`| Message received from external number  
`OUTBOUND_API`| Message sent via API  
`OUTBOUND_CALL`| Message sent during a call  
`OUTBOUND_REPLY`| Message sent as webhook reply  
###  DateOperation 
Date filtering operations for message queries.
Value| Description  
---|---  
`ON_EXACTLY`| Messages on exactly this date  
`ON_AND_BEFORE`| Messages on or before this date  
`ON_AND_AFTER`| Messages on or after this date  
###  HttpMethod 
HTTP methods for webhook configuration.
Value| Description  
---|---  
`GET`| HTTP GET method  
`POST`| HTTP POST method  
##  Error Handling 
###  RequestFailed 
Exception raised when a Twilio API request fails (extends `RuntimeError`).
Attribute| Type| Description  
---|---|---  
`status_code`| `int`| HTTP status code  
`message`| `str`| Error message from Twilio  
**Example:**
    ```python
    try:
        message = client.send_sms_mms(sms)
    except RequestFailed as e:
        if e.status_code == 0:
            # Client-side validation error (e.g., phone lacks MMS capability)
            print(f"Validation error: {e.message}")
        else:
            # Twilio API error
            print(f"API error {e.status_code}: {e.message}")
    ```
##  Complete Webhook Example 
Here's a complete example of handling inbound SMS and sending replies:
    ```python
    from canvas_sdk.clients.twilio.structures import StatusInbound, TwiMlMessage
    def handle_webhook(raw_body: str) -> str:
        """
        Handle incoming SMS webhook from Twilio.
        Args:
            raw_body: URL-encoded form data from Twilio POST request
        Returns:
            TwiML XML response string
        """
        # Parse the inbound message
        inbound = StatusInbound.callback_inbound(raw_body)
        # Log the message
        print(f"From: {inbound.number_from}")
        print(f"To: {inbound.number_to}")
        print(f"Body: {inbound.body}")
        print(f"Media count: {inbound.count_media}")
        # Check for media attachments
        if inbound.count_media > 0:
            for i, url in enumerate(inbound.media_url):
                print(f"Media {i}: {inbound.media_content_type[i]} - {url}")
        # Generate appropriate response
        body_lower = inbound.body.lower()
        if "help" in body_lower:
            reply = TwiMlMessage.instance("Commands: HELP, STATUS, HELLO")
        elif "hello" in body_lower:
            reply = TwiMlMessage.instance_with_media(
                "Hello! Here's a welcome image!",
                "https://example.com/welcome.jpg"
            )
        elif "status" in body_lower:
            reply = TwiMlMessage.instance("System is operational.")
        else:
            reply = TwiMlMessage.instance("Unknown command. Text HELP for options.")
        return reply.to_xml()
    ```
##  Additional Resources 
  - [Twilio SMS API Documentation](https://www.twilio.com/docs/sms)
  - [Twilio Webhooks Guide](https://www.twilio.com/docs/messaging/guides/webhook-request)
  - [TwiML Reference](https://www.twilio.com/docs/messaging/twiml)
  - [Example Plugin](/sdk/example-twilio_sms_mms/) \- Documentation for the example plugin
  - [Source Code](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/twilio_sms_mms) \- View the source on GitHub

---

# Clients

Source: https://docs.canvasmedical.com/sdk/clients/

The clients module provides pre-built integrations with popular third-party services, letting your plugins send emails, SMS messages, interact with AI models, process documents, and manage cloud storage. Each client handles authentication, request formatting, and response parsing so you can focus on your plugin's logic.
All clients follow a consistent pattern: configure credentials via [plugin secrets](/sdk/secrets/), instantiate a client, and call methods. Error handling is standardized with a `RequestFailed` exception across most clients.
> **Warning:** When using third-party clients with your own API keys, you are responsible for all privacy, security, and regulatory compliance associated with those services. For certain providers such as OpenAI and Anthropic, you may contact Canvas to inquire about access through our compliant accounts.
[ AWS S3Upload, download, and manage files in Amazon S3. ](/sdk/clients-aws-s3/)[ Canvas FHIRInteract with the Canvas FHIR API for resources like Coverages and DocumentReferences. ](/sdk/clients-canvas-fhir/)[ Extend AIIntelligent document processing with extraction, classification, and splitting. ](/sdk/clients-extend-ai/)[ LLMsUnified interface for OpenAI, Anthropic, and Google AI models. ](/sdk/clients-llms/)[ SendGridSend emails, manage webhooks, and track delivery with SendGrid. ](/sdk/clients-sendgrid/)[ TwilioSend SMS/MMS messages and manage phone numbers with Twilio. ](/sdk/clients-twilio/)

---

# Command Metadata Create form

Source: https://docs.canvasmedical.com/sdk/command-metadata-create-form-effect/

The `CommandMetadataCreateFormEffect` allows developers to dynamically display additional fields with a command in a note. The values entered in these fields are stored as [command metadata](/sdk/data-command/#commandmetadata) against the target `command_uuid`.
Build a `CommandMetadataCreateFormEffect` with the form fields to show, then return its `apply()` from a `COMMAND__FORM__GET_ADDITIONAL_FIELDS` handler.
##  Methods 
###  apply() → Effect 
Displays the form fields with the command.
  - `command_uuid` and `form_fields` are required.
  - `options` may only be set on fields whose `type` is `InputType.SELECT`; providing `options` on a `TEXT` or `DATE` field raises a validation error.
  - Every `key` must be unique across `form_fields`. Duplicates raise a validation error per duplicated key.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`command_uuid`| `str`| The id of the [command](/sdk/data-command/) these fields should be rendered on.| Yes  
`form_fields`| `list[``FormField``]`| List of fields.| Yes  
##  FormField 
Attribute| Type| Description  
---|---|---  
`key`| `str`| Unique identifier of the field; the command metadata key.  
`label`| `str`| The label displayed on the field.  
`type`| `InputType`| The type of the input: `TEXT`, `SELECT`, or `DATE`. Defaults to `TEXT`.  
`required`| `bool`| Whether the input is required. Defaults to `False`.  
`editable`| `bool`| Whether the input can be edited. Defaults to `True`.  
`options`| `list[str]`| Possible options when the input type is `SELECT`. Only allowed on `SELECT` fields.  
`value`| `str`| Default value used only when no command metadata row exists for this key. If the user has previously saved a value (including a cleared or empty value), the stored row wins and this field is ignored.  
##  Example 
The following handler declares two extra fields on every plan command when the platform requests additional fields for it:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.command_metadata import (
        CommandMetadataCreateFormEffect,
        FormField,
        InputType,
    )
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class PlanCommandAdditionalFields(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.COMMAND__FORM__GET_ADDITIONAL_FIELDS)
        def compute(self) -> list[Effect]:
            # Only respond for plan commands.
            if self.event.context.get("schema_key") != "plan":
                return []
            form = CommandMetadataCreateFormEffect(
                command_uuid=self.event.target.id,
                form_fields=[
                    FormField(
                        key="priority",
                        label="Priority",
                        type=InputType.SELECT,
                        options=["low", "medium", "high"],
                    ),
                    FormField(
                        key="follow_up_date",
                        label="Follow-up date",
                        type=InputType.DATE,
                        editable=True,
                    ),
                ],
            )
            return [form.apply()]
    ```
Once the user fills out these fields, their values are persisted as command metadata and can be read back through the SDK [command metadata](/sdk/data-command/#commandmetadata) table.
##  Rendering on the printed note 
The same `COMMAND__FORM__GET_ADDITIONAL_FIELDS` event fires when a command is rendered for printing (single-command print URL or full note printout). The platform uses the response to label and order the fields shown beneath each command in the printed output.
Two things differ from the chart-form render path:
  - **Values come from stored command metadata, not from`FormField.value`.** The platform pairs each field declared in your effect with the matching `CommandMetadata` row by `key`. Whatever value is on `FormField` is ignored during print rendering. You do not need to populate `value` for print.
  - **Fields with no stored value or a blank value are skipped.** Only fields the user actually filled in will appear in the printout.
  - **Fields you do not declare are hidden.** A `CommandMetadata` row whose `key` is not in your response will not print, even if it exists in the database. This matches the chart UI: removing or renaming a key in your effect makes the prior data invisible.
###  Branching on `purpose`
The event context carries a `purpose` key indicating which call site triggered the request:
Value| When  
---|---  
`"form"`| Chart UI is rendering the command's edit form (default).  
`"print"`| Single-command printout or note printout is being generated.  
Read it from the handler context to vary your response — for example, to omit internal fields from print, or shorten labels for a denser layout.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.command_metadata import (
        CommandMetadataCreateFormEffect,
        FormField,
        InputType,
    )
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class PlanCommandAdditionalFields(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.COMMAND__FORM__GET_ADDITIONAL_FIELDS)
        def compute(self) -> list[Effect]:
            if self.event.context.get("schema_key") != "plan":
                return []
            is_print = self.event.context.get("purpose") == "print"
            fields = [
                FormField(
                    key="priority",
                    label="Priority",
                    type=InputType.SELECT,
                    options=["low", "medium", "high"],
                ),
                FormField(
                    key="follow_up_date",
                    label="Follow-up date",
                    type=InputType.DATE,
                ),
            ]
            if not is_print:
                # Internal-only: visible on the form, hidden from printouts.
                fields.append(
                    FormField(
                        key="reviewer_notes",
                        label="Reviewer notes",
                        type=InputType.TEXT,
                    )
                )
            return [
                CommandMetadataCreateFormEffect(
                    command_uuid=self.event.target.id,
                    form_fields=fields,
                ).apply()
            ]
    ```
###  Tips for the print path 
  - **Use clear, human-readable`label` values.** Whatever you put on `FormField.label` is what the printed output shows. The platform does not derive a label from the `key`.
  - **Use the same`key` you used when persisting metadata.** The print path joins on `key`; mismatches mean nothing renders for that field.
  - **`type`, `options`, and `required` are ignored at print time.** Only `key` and `label` shape the printout.
  - **Need to retire a field?** Removing it from the print response hides it for all future prints — including for committed notes. If you need the historical value to keep showing on signed records, keep the field declared (or declare it only when `purpose == "print"`).

---

# Custom Command

Source: https://docs.canvasmedical.com/sdk/commands-custom-command/

##  Introduction 
The `CustomCommand` class allows plugins to create custom commands with HTML-rendered content that can be inserted into patient charts. Custom commands are designed for displaying read-only content and do not support user input or interactive forms.
**Important** : Custom commands must be configured in the plugin's [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#commands) file under the `commands` array before they can be used.
##  Parameters 
Name| Type| Required| Description  
---|---|---|---  
`note_uuid`|  _string_| `true`| The externally exposable id of the note in which to insert the command.  
`command_uuid`|  _string_| `true`| The externally exposable id of the command which is being referenced.  
`schema_key`|  _string_| `true`| Identifier for data binding. Must match the `schema_key` in your manifest configuration and must be unique across every plugin installed on the instance.  
`content`|  _string_| `true`| HTML content for display in the chart.  
`print_content`|  _string_| `false`| HTML content for print version (recommended for optimal print output).  
##  Manifest Configuration 
Custom commands must be declared in your `CANVAS_MANIFEST.json`:
    ```json
    {
      "components": {
        "commands": [
          {
            "name": "RiskAssessment",
            "label": "Risk Assessment",
            "schema_key": "riskAssessment",
            "section": "assessment"
          }
        ]
      }
    }
    ```
###  Manifest Fields 
  - **name** : Unique name for the command
  - **label** : User-friendly label displayed in Canvas UI
  - **schema_key** : Identifier for the command. Must be unique across every plugin installed on the Canvas instance — if another installed plugin already declares the same `schema_key`, installation will be rejected. CustomCommand instances must use this value.
  - **section** : Chart section where command appears: `subjective`, `objective`, `assessment`, `plan`, `procedures`, `history`, or `internal`
**Note** : `schema_key` values must be unique across **all plugins installed on the instance** , not just within a single plugin. If you install a plugin whose manifest declares a `schema_key` already owned by another installed plugin, the installation fails with a clear validation error instead of silently overwriting the existing command. Choose a distinctive `schema_key` — for example, prefixing it with your plugin's name — to avoid collisions.
##  Basic Usage 
###  Step 1: Create HTML Templates 
Create a template file for your command content (e.g., `templates/risk_assessment.html`):
    ```html
    <!DOCTYPE html>
    <html>
    <head>
        <style>
            .risk-assessment {
                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
                padding: 16px;
            }
            .risk-header {
                font-size: 18px;
                font-weight: 600;
                margin-bottom: 16px;
            }
            .risk-item {
                padding: 8px;
                margin-bottom: 8px;
                background: #f7fafc;
                border-radius: 4px;
            }
            .risk-level {
                font-weight: 600;
                color: #c53030;
            }
        </style>
    </head>
    <body>
        <div class="risk-assessment">
            <div class="risk-header">Risk Assessment</div>
            <div class="risk-item">
                <span class="risk-level">Cardiovascular Risk: High</span>
                <p>Hypertension, family history of heart disease</p>
            </div>
            <div class="risk-item">
                <span class="risk-level">Falls Risk: Moderate</span>
                <p>Age over 65, history of dizziness</p>
            </div>
        </div>
    </body>
    </html>
    ```
Create a simpler print version (e.g., `templates/risk_assessment_print.html`):
    ```html
    <!DOCTYPE html>
    <html>
    <head>
        <style>
            .risk-assessment-print {
                font-family: Arial, sans-serif;
                font-size: 11px;
                .section {
                    margin-bottom: 8px;
                }
                .label {
                    font-weight: bold;
                }
            }
        </style>
    </head>
    <body class="risk-assessment-print">
        <h3>Risk Assessment</h3>
        <div class="section">
            <span class="label">Cardiovascular Risk:</span> High - Hypertension, family history
        </div>
        <div class="section">
            <span class="label">Falls Risk:</span> Moderate - Age over 65, history of dizziness
        </div>
    </body>
    </html>
    ```
###  Step 2: Use Templates in Your Command 
    ```python
    from canvas_sdk.commands.commands.custom_command import CustomCommand
    from canvas_sdk.templates import render_to_string
    import uuid
    command = CustomCommand(
        schema_key="riskAssessment",
        content=render_to_string("templates/risk_assessment.html"),
        print_content=render_to_string("templates/risk_assessment_print.html")
    )
    command.command_uuid = str(uuid.uuid4())
    command.note_uuid = "rk786p"
    effect = command.originate()
    ```
###  Extended CustomCommand Class (For Reusability) 
Create a subclass with a predefined `schema_key`:
    ```python
    from canvas_sdk.commands.commands.custom_command import CustomCommand
    from canvas_sdk.templates import render_to_string
    import uuid
    class RiskAssessmentCommand(CustomCommand):
        """Custom command for risk assessment."""
        class Meta:
            schema_key = "riskAssessment"
    # Usage
    command = RiskAssessmentCommand(
        content=render_to_string("templates/risk_assessment.html"),
        print_content=render_to_string("templates/risk_assessment_print.html")
    )
    command.command_uuid = str(uuid.uuid4())
    command.note_uuid = "rk786p"
    effect = command.originate()
    ```
##  Methods 
###  originate() 
Returns an Effect that originates a new command in the note body.
**Example:**
    ```python
    from canvas_sdk.commands.commands.custom_command import CustomCommand
    from canvas_sdk.templates import render_to_string
    import uuid
    command = CustomCommand(
        schema_key="riskAssessment",
        content=render_to_string("templates/risk_assessment.html"),
        print_content=render_to_string("templates/risk_assessment_print.html")
    )
    command.command_uuid = str(uuid.uuid4())
    command.note_uuid = "rk786p"
    effect = command.originate()
    ```
##  Content vs Print Content 
Custom commands support two versions of content:
###  Display Content (content) 
  - Rendered in the Canvas UI when viewing the chart
  - Can include rich styling and complex layouts
###  Print Content (print_content) 
  - Rendered when printing the chart or generating PDFs
  - Should be simpler and more compact
**Best Practice** : Always provide both versions for the best user experience.
##  Collapsible Content 
The `content` frame stops responding to clicks once the command is committed or the note is locked, so a toggle inside `content` can't be opened in a finished note. To show a long, read-only record without it taking up the note, attach it with [`set_custom_html`](/sdk/commands/#set_custom_html) inside a `<details>` element. Custom HTML renders under the command's title in its own frame. That frame keeps responding to clicks after the command is committed or the note is locked, and it grows when the provider opens the `<details>` element.
  - Set the custom HTML while the command is still staged: return `set_custom_html` in the same list as `originate()`, before any `commit()`.
  - `content` is still required. Keep it to a short summary; the custom HTML appears above it.
  - Custom HTML isn't printed, so put the full record in `print_content`.
    ```python
    from canvas_sdk.commands.commands.custom_command import CustomCommand
    from canvas_sdk.templates import render_to_string
    import uuid
    full_record = render_to_string("templates/intake_record.html")
    command = CustomCommand(
        schema_key="intakeRecord",
        content="<p>Intake submitted. 3 answers flagged for review.</p>",
        print_content=full_record
    )
    command.command_uuid = str(uuid.uuid4())
    command.note_uuid = "rk786p"
    effects = [
        command.originate(),
        command.set_custom_html(
            f"<details><summary>Show full intake</summary>{full_record}</details>"
        ),
    ]
    ```
##  Limitations 
  - Custom commands are read-only and cannot capture user input
  - Interactive elements (forms, buttons, input fields) are not supported, and the `content` frame stops responding to clicks once the command is committed or the note is locked. To let providers expand long content, see Collapsible Content.
  - Commands must be configured in the manifest before use
  - The `schema_key` must be unique across every plugin installed on the Canvas instance. Installing a plugin whose `schema_key` is already owned by another installed plugin will fail with a validation error.

---

# Commands

Source: https://docs.canvasmedical.com/sdk/commands/

The commands module lets you create and update commands within a specific note in Canvas. Commands are the building blocks of many end-user workflows in Canvas, including nearly all clinical workflows for documentation, like HPIs and questionnaires, as well as orders like prescriptions, labs, and referrals. Each Command class can be instantiated in your plugin and used to build a new command instance within a specific note or update an existing instance. The commands are then displayed in real time within the end user's workflow.
Common objectives that can be met by using Command classes include dynamic note templates, clinical decision support, order set composition, care gap closure, and care coordination automation.
Commands are written from an event handler by default. To let something outside Canvas write them — a patient-facing form, a device, an internal tool — expose them over HTTP with [`CommandAPI`](/sdk/handlers-simple-api-commands/), which reads a request body onto any command on this page, validates it, and emits the effects. The [Writing Commands Over HTTP](/guides/writing-commands-over-http/) guide walks through building one.
> **Info:** New to command fields? Fields that are autocompletes, dropdowns, or enums in the Canvas UI take a raw code, id, or enum value in the SDK — you have to look the value up first. See [Populating Command Fields](/guides/populating-command-fields/) for where each value comes from.
Note content such as HPI, Review of Systems, Physical Exam, Assessment, and Plan is populated programmatically through this commands module. A common pattern for external integrations is to expose a [SimpleAPI](/sdk/handlers-simple-api-http/) endpoint that uses the [Create Note](/sdk/effect-notes/#create-note) effect to create the note and then originates commands into it. See the [charting API examples](/sdk/example-charting_api_examples/) plugin for a worked example.
To write commands from an outside system over HTTP, use [`CommandAPI`](/sdk/handlers-simple-api-commands/), which turns a command into an endpoint and validates each request against the command.
To go beyond the built-in commands, by adding fields, showing your own content, or adding commands of your own, see [Customizing Commands Beyond the Built-ins](/guides/customizing-commands/).
"Commands" is an umbrella term for all the structured data within a patient's note. Questionnaire is one specific command type. When a questionnaire is built, its use case in charting can be set to Physical Exam, Structured Assessment, Review of Systems, or Questionnaire; these all share the same underlying database structure but appear in the note as their own distinct command. The `.originate()` method works on all command types.
You can use the SDK to auto-populate questionnaire commands (and other commands) in response to an event rather than building many separate per-situation automations. Listen for an appropriate [event](/sdk/events/) — such as a note state change, another command being committed, or metadata being added — and originate the commands you need. You can also insert commands when an [action button](/sdk/handlers-action-buttons/) is clicked if a manual trigger is preferred.
##  Common Attributes 
###  Parameters 
All commands share the following init kwarg parameters:
Name| Type| Required| Description  
---|---|---|---  
`note_uuid`|  _string_| `true` if creating a new command| The id of the [Note](/sdk/data-note/#note) in which to insert the command.  
`command_uuid`|  _string_| `true` if updating an existing command| The id of the [Command](/sdk/data-command/#command). On `originate` you can pass your own value to set it the first time; when updating, it references an existing command.  
All parameters can be set upon initialization, and also updated on the class instance.
Field values are read leniently, so a value does not have to arrive already in the field's own type: a number can be given as `"3"`, a date as `"2026-08-04"`, and an enum as its value (`"mild"`) rather than the member. This matters most when the values come from somewhere that only has strings, such as a JSON request body.
The **Required to** column (depending on the command's terminal action) in each command's parameter table below indicates whether a field must be set in order for the server to accept that terminal action. It does **not** mean the field is required to instantiate the class or to call `.originate()` or `.edit()`. You can create a command with every other field empty and the command appears in the note as fresh command, mirroring how a clinician picks a command from the menu in the UI and leaves it unfilled until they're ready to finalize it.
The only field required to **originate** any command is `note_uuid`. Skip `.commit()` and the command persists in the note in its empty/staged state until the user (or a later plugin call) fills it in and commits it:
    ```python
    from canvas_sdk.commands import PrescribeCommand
    # inside a handler's compute(), on an event whose context carries the note
    p = PrescribeCommand()
    p.note_uuid = self.event.context["note"]["uuid"]
    return [p.originate()]
    ```
The same pattern works with any command class — `PlanCommand(note_uuid=...)`, `AssessCommand(note_uuid=...)`, `MedicalHistoryCommand(note_uuid=...)`, etc.
###  Methods 
**Not every command supports every method.** `originate` is the only one they all have; `edit`, `delete`, `commit`, `enter_in_error`, `review`, `send`, `delegate` and `sign` each depend on the command. The [command type table](/sdk/effects/#commands) lists the actions each command accepts — check it before relying on one. `upsert_metadata` works on any command, and `set_custom_html` works on any staged command, including [custom commands](/sdk/commands-custom-command/#collapsible-content).
To call these over HTTP rather than from a handler, see [`CommandAPI`](/sdk/handlers-simple-api-commands/#methods).
####  originate 
Returns an Effect that originates a new command in the note body.
**Parameters:**
Name| Type| Required| Default| Description  
---|---|---|---|---  
`commit`| `bool`| No| `False`| When `True`, the command is automatically committed after origination. This is a simpler alternative to returning separate `originate()` and `commit()` effects. **Note:** This only applies to command types that support the COMMIT action. Commands that do not support committing (Reason For Visit, Prescribe, Refill, Adjust Prescription, Refer, and Order commands) will ignore this parameter. See the [command type table](/sdk/effects/#commands) for which commands support COMMIT.  
`line_number`| `int`| No| `-1`| The line number in the note where the command should be inserted. By default the command will insert at the bottom of the note.  
**See also:** For efficiently inserting multiple commands at once, see [Batch Originate Commands](/sdk/effect-batch-originate/).
**Examples** :
    ```python
    from canvas_sdk.commands import PlanCommand
    def compute():
        new_plan = PlanCommand(note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47', narrative='new')
        new_plan.narrative = 'newer'
        return [new_plan.originate()]
    ```
To originate and commit in a single effect:
    ```python
    from canvas_sdk.commands import AssessCommand
    def compute():
        assess_command = AssessCommand(
            note_uuid='550e8400-e29b-41d4-a716-446655440000',
            icd10_code='E11.9'
        )
        return [assess_command.originate(commit=True)]
    ```
####  edit 
Returns an Effect that edits an existing command with the values set on the command class instance.
**Behavior and Considerations:**
  - **Partial Edits:** If you update only some fields of the command, any fields not explicitly modified will retain their existing values.
  - **No Changes:** Calling `edit()` without making any changes will result in a no-op; the command remains unchanged.
  - **Invalid Values:** If you attempt to set an invalid value, you should receive a validation error.
**Example** :
    ```python
    from canvas_sdk.commands import PlanCommand
    def compute():
        existing_plan = PlanCommand(command_uuid='2b9d1f0a-4c3e-4b5a-9d8c-7e6f5a4b3c2d', narrative='something new')
        return [existing_plan.edit()]
    ```
####  delete 
Returns an Effect that deletes an existing, non-committed command from the note body.
**Example** :
    ```python
    from canvas_sdk.commands import PlanCommand
    def compute():
        existing_plan = PlanCommand(command_uuid='2b9d1f0a-4c3e-4b5a-9d8c-7e6f5a4b3c2d')
        return [existing_plan.delete()]
    ```
To delete the command that triggered your handler, instantiate the matching command class with `command_uuid=self.target` and return its `delete()` effect — for example, `PlanCommand(command_uuid=self.target).delete()` from a handler responding to `PLAN_COMMAND__POST_ORIGINATE`. If you instead want to mark a committed command as entered in error, use `enter_in_error`. Note that `delete()` only removes non-committed (staged) commands.
####  commit 
Returns an Effect that commits an existing, non-committed command to the note body.
To block a command from committing and surface a message to the user — for example, enforcing your own business rules before a command is entered — return a [Command Validation effect](/sdk/effect-command-validation/) from a handler on the command's validation event.
**Example** :
    ```python
    from canvas_sdk.commands import PlanCommand
    def compute():
        existing_plan = PlanCommand(command_uuid='2b9d1f0a-4c3e-4b5a-9d8c-7e6f5a4b3c2d')
        return [existing_plan.commit()]
    ```
####  review 
Returns an Effect that sets a command in review.
**Limited availability** The `review()` method can only be called on Prescribe commands objects. Other command types do not support this operation.
**Example** :
    ```python
    from canvas_sdk.commands import PrescribeCommand
    def compute():
        existing_prescribe = PrescribeCommand(command_uuid='e32b85d9-ccb7-4e4f-a0e5-8783ed2d9528')
        return [existing_prescribe.review()]
    ```
####  send 
Returns an Effect that sends a signed command.
**Limited availability** The `send()` method can only be called on LabOrder, Prescribe, Refill and AdjustPrescription command objects. Other command types do not support this operation. The three prescribing commands share one set of electronic prescribing validations.
**Parameters:**
Name| Type| Required| Default| Description  
---|---|---|---|---  
`practice_location_override`| `str \| UUID`| No| `None`| Prescribe only. The `id` of a [PracticeLocation](/sdk/data-practicelocation/#practicelocation) whose address is used as the prescriber address on the outgoing prescription, overriding the prescriber's primary location. See Prescribe for behavior and limitations.  
**Example** :
    ```python
    from canvas_sdk.commands import PrescribeCommand
    def compute():
        existing_prescribe = PrescribeCommand(command_uuid='e32b85d9-ccb7-4e4f-a0e5-8783ed2d9528')
        return [existing_prescribe.send()]
    ```
To send the prescription using a specific practice location's address (see Prescribe):
    ```python
    from canvas_sdk.commands import PrescribeCommand
    def compute():
        existing_prescribe = PrescribeCommand(command_uuid='e32b85d9-ccb7-4e4f-a0e5-8783ed2d9528')
        return [existing_prescribe.send(practice_location_override='a1b2c3d4-e5f6-7890-abcd-ef1234567890')]
    ```
####  enter_in_error 
Returns an effect that enter-in-errors an existing, committed command in the note body. The command referenced by `command_uuid` must already be committed; returning this effect transitions it to entered-in-error status.
**Example** :
    ```python
    from canvas_sdk.commands import PlanCommand
    def compute():
        existing_plan = PlanCommand(command_uuid='2b9d1f0a-4c3e-4b5a-9d8c-7e6f5a4b3c2d')
        return [existing_plan.enter_in_error()]
    ```
####  delegate 
Returns an Effect that delegates an existing, staged command by creating a task.
**Limited availability** The `delegate()` method can only be called on ImagingOrder and Refer command objects. Other command types do not support this operation.
**Example** :
    ```python
    from canvas_sdk.commands import ReferCommand
    def compute():
        existing_refer = ReferCommand(command_uuid='e32b85d9-ccb7-4e4f-a0e5-8783ed2d9528')
        return [existing_refer.delegate()]
    ```
####  sign 
Returns an Effect that signs an existing, staged command, transitioning it to a committed state.
**Limited availability** The `sign()` method can only be called on ImagingOrder, OrderDme, and Refer command objects. Other command types do not support this operation.
**Example** :
    ```python
    from canvas_sdk.commands import ImagingOrderCommand
    def compute():
        existing_imaging_order = ImagingOrderCommand(command_uuid='e32b85d9-ccb7-4e4f-a0e5-8783ed2d9528')
        return [existing_imaging_order.sign()]
    ```
####  upsert_metadata 
Returns a [CommandMetadata effect](/sdk/effect-command-metadata/) that creates or updates a metadata key-value pair on a command. If metadata with the given key already exists on the command, its value will be updated. Otherwise, a new metadata record will be created.
The `command_uuid` field must be set on the command object before calling `upsert_metadata`.
To make this metadata **visible and editable as fields on the command in the note** — rather than only stored behind the scenes — use the [Command Metadata Create Form effect](/sdk/command-metadata-create-form-effect/), which renders additional fields on the command whose values are saved as command metadata.
Parameter| Type| Description  
---|---|---  
`key`|  _string_|  The metadata key (max 256 characters).  
`value`|  _string_|  The metadata value.  
**Example** :
    ```python
    from canvas_sdk.commands import PlanCommand
    def compute():
        existing_plan = PlanCommand(command_uuid='2b9d1f0a-4c3e-4b5a-9d8c-7e6f5a4b3c2d')
        return [existing_plan.upsert_metadata(key="priority", value="high")]
    ```
####  set_custom_html 
Returns an effect that sets or clears custom HTML content on a command. The HTML is stored on the command and rendered alongside it in the note.
The `command_uuid` field must be set on the command object before calling `set_custom_html`. The command must be in a staged (not committed) state—calling this method on a committed command will raise a validation error.
Parameter| Type| Description  
---|---|---  
`custom_html`|  _string_ or _None_|  The HTML content to set on the command, or `None` to clear it.  
**Example** :
    ```python
    from canvas_sdk.commands import PlanCommand
    def compute():
        existing_plan = PlanCommand(command_uuid='2b9d1f0a-4c3e-4b5a-9d8c-7e6f5a4b3c2d')
        return [existing_plan.set_custom_html("<div class='highlight'>Important note</div>")]
    ```
To clear existing custom HTML from a command:
    ```python
    from canvas_sdk.commands import PlanCommand
    def compute():
        existing_plan = PlanCommand(command_uuid='2b9d1f0a-4c3e-4b5a-9d8c-7e6f5a4b3c2d')
        return [existing_plan.set_custom_html(None)]
    ```
##  Originating and Committing Together 
The simplest way to originate and commit a command in a single plugin action is to pass `commit=True` to the `originate()` method:
    ```python
    from canvas_sdk.commands import AssessCommand
    def compute():
        assess_command = AssessCommand(
            note_uuid='550e8400-e29b-41d4-a716-446655440000',
            icd10_code='E11.9'
        )
        return [assess_command.originate(commit=True)]
    ```
This handles the origination and commit in a single effect, without needing to manage a `command_uuid` yourself.
###  Chaining Methods with a User-set UUID 
If you need more control over the process — for example, to edit a command between origination and commit — you can chain separate effects by setting the `command_uuid` manually. This chaining is necessary because a handler returns all of its effects at once, so it cannot read back an id that Canvas assigns during origination.
    ```python
    from uuid import uuid4
    from canvas_sdk.commands import AssessCommand
    def compute():
        note_uuid = '550e8400-e29b-41d4-a716-446655440000'
        assess_command = AssessCommand(
            note_uuid=note_uuid,
            icd10_code='E11.9'
        )
        # To chain command effects, you must know what the command's id
        # is. To accomplish that, we set the id ourselves rather than
        # allow the database to assign one.
        assess_command.command_uuid = str(uuid4())
        # Now we can both originate and commit in a single operation
        return [assess_command.originate(), assess_command.commit()]
    ```
This pattern ensures that both the originate and commit operations use the same `command_uuid`, allowing them to be chained together reliably in a single plugin execution.
Command-specific details for each command class can be found below.
##  Command Actions 
All commands support user-triggered actions through the Canvas UI. These actions appear as buttons or menu items that users can click to perform operations on a command.
Commands have two types of actions:
  - **Generic actions** — available on all commands (listed below).
  - **Command-specific actions** — vary by command type and are documented in each command's section below.
Action| Description  
---|---  
`print`| Generates a printable version of the command for documentation or external sharing.  
`audit_history`| Displays the complete audit trail for the command, showing all modifications, state changes, and user interactions over time.  
`carry_forward`| Populates the command with the last known data for this command type and patient, letting users quickly recreate a similar command from a previous entry.  
How a printed note orders its commands depends on the note's format. A note in the older format, or any note on an instance outside the [revamped note beta program](/product-updates/note-revamp/), groups its commands by section in SOAP order, and this sorting can't be turned off. Within each section, commands print in a fixed order by command type, not in the order they were entered.
A note in the revamped format prints the sections it shows on screen, History, Exam, and Assessment & Plan, in the note's SOAP or APSO order. Within each section, commands print in the order the provider arranged them in the note. Each Assess command prints with the commands [linked to it](/sdk/data-assessment/#commands-linked-to-an-assessment) indented below it. The Internal section isn't printed, and free text prints under a Notes heading after the sections. Faxed notes and the patient's entire-record print use the same layout.
To control the print layout yourself, build a plugin that adds an [action button](/sdk/handlers-action-buttons/) with a custom print template. The [patient-visit-summary](https://github.com/medical-software-foundation/canvas/tree/main/extensions/patient-visit-summary) extension does this: staff choose and reorder the sections of a note, preview the result, and print it or save it as a PDF.
> **Info:** The send action is the only command action available through the SDK, and only LabOrder, Prescribe, Refill and Adjust Prescription commands support it.
###  Customizing Action Availability 
You can programmatically control which actions appear on a command — and in what order — by responding to that command's `AVAILABLE_ACTIONS` event. Common uses:
  - **Hide actions** based on user permissions, role, or command state.
  - **Reorder actions** to prioritize commonly used operations.
  - **Conditionally show actions** depending on workflow or business logic.
**How it works:**
  1. When Canvas renders a command, it fires that command's `<COMMAND>_COMMAND__AVAILABLE_ACTIONS` event (e.g. `PLAN_COMMAND__AVAILABLE_ACTIONS`).
  2. Your handler receives the default action list in `self.context["actions"]` and the acting user in `self.context["user"]`.
  3. Return a single `COMMAND_AVAILABLE_ACTIONS_RESULTS` effect whose payload is the action list you want rendered. The returned list **replaces** the default set, so include every action the user should see — returning the original list unchanged is a no-op.
**Example** — hide the `print` action for a specific user:
    ```python
    import json
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.v1.data import Staff
    class Handler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PLAN_COMMAND__AVAILABLE_ACTIONS)
        def compute(self) -> list[Effect]:
            actions = self.context["actions"]
            user_id = self.context["user"]["staff"]
            try:
                staff = Staff.objects.get(id=user_id)
                # Hide the print action for this user; everyone else keeps the full set
                if staff.first_name == "Larry":
                    filtered_actions = [a for a in actions if a["name"] != "print"]
                else:
                    filtered_actions = actions
            except Staff.DoesNotExist:
                filtered_actions = actions
            return [
                Effect(
                    type=EffectType.COMMAND_AVAILABLE_ACTIONS_RESULTS,
                    payload=json.dumps(filtered_actions),
                )
            ]
    ```
##  Command Validation 
Beyond the built-in validation each command performs on its own fields, you can add your **own** validation rules to a command and surface error messages to the user directly in the Canvas UI. A handler responds to a command's validation event (for example, `PLAN_COMMAND__POST_VALIDATION`) and returns a [Command Validation effect](/sdk/effect-command-validation/) containing one or more error messages. This is useful for enforcing organization-specific business rules — such as requiring a field, restricting certain combinations, or blocking a command until an external condition is met — before the command can be committed.
See the [Command Validation effect](/sdk/effect-command-validation/) documentation for the full API and examples.
##  Choosing Between Similar Commands 
Some commands write to the same part of the chart and differ only in intent. The tables below cover the cases where more than one command could plausibly apply.
###  Recording a condition 
Which command fits depends on whether the condition is active now, whether you are assessing it, and whether it is surgical.
Command| Use it when  
---|---  
Assess with `icd10_code`| The condition is active and you are assessing it, whether it is new or already on the chart. It reuses the patient's charted condition with that code, and records a new one only when the patient has none, so it never adds a duplicate. Use this for new work. Set `show_in_problem_list=False` for a diagnosis that belongs only to this visit.  
MedicalHistory| You are backfilling a condition the patient had in the past that is not active now.  
AddCondition| The condition was diagnosed previously and is still active, and you are not assessing it.  
SurgicalHistory| You are recording a past surgical procedure.  
Diagnose| Still available for a new active condition you are assessing for the first time, but planned for retirement in a future release. Use Assess with `icd10_code` instead.  
Each of these writes a [Condition](/sdk/data-condition/#condition) when it records a new one. They differ in what they set on it, which is what decides where it shows up and which commands can act on it later:
Command| `clinical_status`| `surgical`| Opens an assessment  
---|---|---|---  
Assess with `icd10_code`| `active`| `false`| Yes  
MedicalHistory| `resolved`| `false`| No  
AddCondition| `active`| `false`| No  
SurgicalHistory| `resolved`| `true`| No  
Diagnose| `active`| `false`| Yes  
Surgical history is coded in SNOMED rather than ICD-10, and the `surgical` flag is what separates it from past medical history: Remove Past Medical History rejects a surgical entry, and AddCondition ignores one when checking whether a condition is already on the list.
###  Updating or removing a condition 
Four more commands act on a condition that is already on the chart.
Command| Use it when  
---|---  
Assess| You are recording an assessment against a condition on the chart, named by `condition_id` or `icd10_code`. Assessing a resolved condition makes it active again.  
UpdateDiagnosis| The diagnosis was wrong or has been refined, and you want the new code to carry the original's history.  
Resolve Condition| An active condition is no longer relevant to track. It must be committed, not entered in error, and not already resolved.  
Remove Past Medical History| A past medical history entry does not belong on the chart at all. It must have no committed assessment against it. Resolve Condition will not take it, because the entry is already resolved.  
The last two are easy to confuse. Resolve Condition closes a condition that was genuinely present and leaves it on the record as resolved. Remove Past Medical History withdraws an entry that should not have been recorded, taking it off the conditions list entirely.
###  Recording a medication 
Six commands touch a patient's medication list. Three of them produce a prescription that can be sent to a pharmacy with `send()`, and three only change what the chart says.
Command| Use it when| Produces a prescription  
---|---|---  
Prescribe| You are prescribing a medication the patient is not already on.| Yes  
Refill| You are renewing a medication the patient is already on. The `fdb_code` must match one of that patient's active medications.| Yes  
AdjustPrescription| You are replacing a prescribed medication with a different one, given as `new_fdb_code`. A different strength or formulation is a different FDB code, so it goes here too.| Yes  
ChangeMedication| You are changing the `sig` on an active medication without issuing a new prescription.| No  
StopMedication| The patient is stopping a medication, and you want the reason on the chart.| No  
MedicationStatement| You are recording a medication the patient reports taking, without prescribing it.| No  
Canceling a prescription that has already gone to a pharmacy is a Cancel Prescription command in the note. There is no SDK command class for it, so a plugin cannot originate one, though the resulting records are readable through the [CancelPrescription](/sdk/data-cancel-prescription/) data module.
##  Commands 
The sections below document each command class. See Common Attributes for the parameters and methods shared by all commands.
###  AddCondition 
Records a coded (ICD-10) condition on the patient's Conditions list with clinical status active, in the note's History section, without opening an assessment for it. Reach for it when the condition was diagnosed previously and is still active. See Recording a condition for how it compares to Assess and MedicalHistory.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`icd10_code`|  _string_| `true`| ICD-10 code of the condition to record. Search with the [ICD-10 condition endpoint](/sdk/utils/#get-icdcondition--icd-10-conditions).  
`background`|  _string_| `false`| Background information about the condition.  
`approximate_date_of_onset`|  _date_| `false`| The approximate date the condition began.  
`comments`|  _string_| `false`| Additional comments (max length: 1000 characters).  
**Example** :
    ```python
    from canvas_sdk.commands import AddConditionCommand
    from datetime import date
    add_condition = AddConditionCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        icd10_code='N183',
        background='Diagnosed at outside nephrology practice.',
        approximate_date_of_onset=date(2023, 4, 1),
        comments='Stable on last three panels.'
    )
    ```
> **Info:** Once the condition this command recorded carries an assessment, the command can no longer be entered in error, because reverting it would take the condition out from under that assessment. This holds for plugins as well as for the note: an `ENTER_IN_ERROR` effect against such a command is rejected with _Command could not be entered in error due to command-specific business logic_. Resolve the condition instead.
* * *
###  AdjustPrescription 
Replaces a prescribed medication with a different one, and can send the new prescription to a pharmacy. See Recording a medication for how it compares to the other medication commands.
**Command-specific parameters** :
Name| Type| Required to review / send| Description  
---|---|---|---  
`new_fdb_code`|  _string_| `true`| The [FDB code](/sdk/utils/#fdb_code) of the new medication.  
Check the Prescribe command for the other parameters used in the Adjust Prescription command. Adjust Prescription supports `send()` under the same electronic prescribing validations.
    ```python
    from canvas_sdk.commands import AdjustPrescriptionCommand, PrescribeCommand
    from canvas_sdk.commands.constants import ClinicalQuantity
    AdjustPrescriptionCommand(
        fdb_code="172480",
        new_fdb_code="216092",
        icd10_codes=["R51"],
        sig="Take one tablet daily after meals",
        days_supply=30,
        quantity_to_dispense=30,
        type_to_dispense=ClinicalQuantity(
            representative_ndc="12843016128",
            ncpdp_quantity_qualifier_code="C48542"
        ),
        refills=3,
        substitutions=PrescribeCommand.Substitutions.ALLOWED,
        pharmacy="pharmacy_ncpdp_id",
        prescriber_id="a7c2e9d1-3b4f-4a6c-8e0d-5f1a2b3c4d5e",
        supervising_provider_id="c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
        note_to_pharmacist="Please verify patient's insurance before processing."
    )
    ```
* * *
###  Allergy 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`allergy`|  _Allergen_| `false`| Represents the allergen. See details in the Allergen type below. Search allergens with the [ontologies allergen search](/sdk/utils/#get-fdballergy--full-text-search).  
`severity`|  _Severity enum_| `false`| The severity of the allergic reaction. Must be one of `AllergyCommand.Severity`.  
`narrative`|  _string_| `false`| A narrative or free-text description of the allergy (max length: 512 characters).  
`approximate_date`|  _datetime_| `false`| The approximate date the allergy was identified.  
**Enums and Types** :
**`Allergen`**
Attribute| Type| Description  
---|---|---  
`concept_id`|  _integer_|  The identifier for the allergen concept.  
`concept_type`|  _AllergenType enum_| The type of allergen. See `AllergenType` values below.  
AllergenType| Value| Description  
---|---|---  
`ALLERGEN_GROUP`| `1`| Represents a group of allergens.  
`MEDICATION`| `2`| Represents a medication allergen.  
`INGREDIENT`| `6`| Represents an ingredient allergen.  
Severity| Value| Description  
---|---|---  
`MILD`| `"mild"`| Indicates a mild reaction.  
`MODERATE`| `"moderate"`| Indicates a moderate reaction.  
`SEVERE`| `"severe"`| Indicates a severe reaction.  
**Example** :
    ```python
    from canvas_sdk.commands.commands.allergy import AllergyCommand, AllergenType, Allergen
    from datetime import date
    allergy = AllergyCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        allergy=Allergen(concept_id=12345, concept_type=AllergenType.MEDICATION),
        severity=AllergyCommand.Severity.SEVERE,
        narrative="Severe rash and difficulty breathing after penicillin.",
        approximate_date=date(2023, 6, 15)
    )
    ```
* * *
###  Assess 
Records an assessment of a patient's condition. Name the condition in one of two ways:
  - `icd10_code` (recommended) assesses a condition by its ICD-10 code, whether or not it's already on the chart, so there's no need to look up a condition id first. If the patient already has a charted condition with that code, the assessment uses it, preferring an active condition over a resolved one. Committing the command makes a resolved condition active again. Codes match regardless of dots and case, so `M54.50` and `M5450` name the same condition. If the patient has no charted condition with that code, committing the command records a new one, on the problem list unless `show_in_problem_list` is `False`.
  - `condition_id` assesses a specific condition already on the patient's chart.
Set one or the other, not both. You can originate an Assess with neither, for example to leave an empty command for the user to complete, but committing it needs a condition. See Recording a condition and Updating or removing a condition for how it compares to the other condition commands.
> **Info:** If your plugin relies on [`ASSESS_COMMAND__CONDITION_SELECTED`](/sdk/events/#assess_command__condition_selected) or [`ASSESS_COMMAND__ICD10_CODE_SELECTED`](/sdk/events/#assess_command__icd10_code_selected), set the condition with `edit()`. These events fire when an existing Assess command's condition changes, so originating an Assess with `condition_id` or `icd10_code` already set sends neither. To trigger them, originate the command without a condition, then `edit()` it to set one. An `edit()` with `icd10_code` sends `ASSESS_COMMAND__ICD10_CODE_SELECTED` even when the patient already has that condition charted.
Entering a committed Assess in error also enters in error the condition its commit recorded, so withdrawing the assessment doesn't leave a diagnosis on the chart that no one made. The condition stays on the chart while another committed assessment that isn't entered in error still uses it. Conditions the Assess didn't record, such as one already on the chart or one recorded by a Diagnose or AddCondition command, are never changed. You can always enter an Assess in error, even when other assessments use the condition it recorded.
Set `show_in_problem_list` to choose whether the condition belongs on the patient's problem list or only to this visit. Committing with `False` records the condition as an encounter diagnosis, such as a sore throat that doesn't need tracking. Committing with `True` moves an encounter diagnosis back onto the problem list. The choice is saved as the condition's category, which the [FHIR Condition](/api/condition/) resource returns as `encounter-diagnosis` or `problem-list-item`. An encounter diagnosis is still one assessed condition, not a copy, so Plan commands and billing in the note can use it. The chart's Conditions list shows encounter diagnoses alongside problem list items. Clinicians can pick one in Update Diagnosis or Resolve Condition, or as a Prescribe indication, and an UpdateDiagnosis command can name it by code. A commit that changes the status sends [`CONDITION_UPDATED`](/sdk/events/#condition_updated).
Entering in error an Assess that changed the status resets the condition's status. The condition takes the status set by the most recently committed Assess that changed it and isn't entered in error. If none remains, it goes back to the status it had before any Assess changed it.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`condition_id`|  _string_| `true`, unless `icd10_code` is set| The id of the [Condition](/sdk/data-condition/#condition) being assessed. Must be a condition already recorded on that patient's chart. Can't be combined with `icd10_code`.  
`icd10_code`|  _string_| `true`, unless `condition_id` is set| ICD-10 code of the condition being assessed. Search with the [ICD-10 condition endpoint](/sdk/utils/#get-icdcondition--icd-10-conditions). Can't be combined with `condition_id`.  
`approximate_date_of_onset`|  _date_| `false`| The approximate date the condition began. Committing the command saves it as the condition's onset date, replacing any date already recorded. If you leave it unset, the condition's onset date doesn't change.  
`show_in_problem_list`|  _boolean_| `false`| Whether committing the command puts the condition on the problem list (`True`) or records it as an encounter diagnosis for this visit only (`False`). If you leave it unset or pass `None`, the condition keeps its current status, and a new condition goes on the problem list.  
`background`|  _string_| `false`| Background information about the diagnosis.  
`status`|  _Status enum_| `false`| The current status of the diagnosis. Must be one of `AssessCommand.Status`.  
`narrative`|  _string_| `false`| The narrative for the current assessment (max 2048 characters; values exceeding the limit raise a validation error instead of being truncated).  
`Status`| Value| Description  
---|---|---  
`IMPROVED`| `"improved"`| The condition has improved.  
`STABLE`| `"stable"`| The condition is stable.  
`DETERIORATED`| `"deteriorated"`| The condition has deteriorated.  
**Examples** :
Assess a condition by ICD-10 code, whether or not the patient has it charted:
    ```python
    from datetime import date
    from canvas_sdk.commands import AssessCommand
    assess = AssessCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        icd10_code='M54.50',
        approximate_date_of_onset=date(2012, 1, 1),
        background='lifted heavy box',
        narrative='unable to sleep lately'
    )
    ```
Record a visit-only diagnosis as an encounter diagnosis:
    ```python
    from canvas_sdk.commands import AssessCommand
    assess = AssessCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        icd10_code='J02.9',
        show_in_problem_list=False,
        narrative='sore throat for two days'
    )
    ```
Assess a specific condition already on the chart by its id:
    ```python
    from canvas_sdk.commands import AssessCommand
    assess = AssessCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        condition_id='a1c2e3d4-5b6f-4a7c-8e9d-0f1a2b3c4d5e',
        background='started in 2012',
        status=AssessCommand.Status.STABLE,
        narrative='experiencing more pain lately'
    )
    ```
**Validation** :
Passing both `condition_id` and `icd10_code` fails validation when you `originate` or `edit` the command, with the error `Name the condition with either condition_id or icd10_code, not both`. This applies even when one of them is `None`, because the empty value would clear the other. Leave out the argument you aren't using.
Canvas checks `icd10_code` against the ICD-10 terminology when it applies the effect. A code that matches no ICD-10 condition fails with the error `ICD-10 code <code> not found`, and the command is neither created nor updated.
`condition_id` must belong to the same patient as the note or command it is written to: the patient comes from `note_uuid` when you `originate` the command, and from the existing command when you `edit` one. A condition on another patient's chart — or an id that matches no condition at all — fails validation, and the command is neither created nor updated. This check is deferred when the target note (on `originate`) or command (on `edit`) is not yet persisted — for example, when a plugin creates the note and originates `AssessCommand`s against that same `note_uuid` in a single handler response. In that case the note's or command's patient cannot be resolved yet, so `condition_id` passes this validation. The patient-ownership check then runs later, once the command is applied and the note exists.
Committing the command checks `condition_id` again. If the condition was entered in error after it was picked, or isn't on the patient's chart, the commit fails with the error `The condition picked in this Assess was entered in error or is not on this patient's chart. Pick the condition again.`
* * *
###  ChangeMedication 
Changes the sig on an active medication without issuing a new prescription. See Recording a medication for how it compares to the other medication commands.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`medication_id`|  _string_| `true`| The id of the [Medication](/sdk/data-medication/#medication) being changed. Must be an active medication on that patient's chart.  
`sig`|  _string_| `false`| Administration details of the medication.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
**Example** :
    ```python
    from canvas_sdk.commands.commands.change_medication import ChangeMedicationCommand
    change_medication = ChangeMedicationCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        medication_id='f0a1b2c3-d4e5-4f6a-8b9c-0d1e2f3a4b5c',
        sig='two pills taken orally'
    )
    ```
**Validation** :
`medication_id` must belong to the same patient as the note or command it is written to: the patient comes from `note_uuid` when you `originate` the command, and from the existing command when you `edit` one. The medication must also be active. A medication on another patient's chart, an id that matches no medication, or an inactive medication fails validation, and the command is neither created nor updated. This check is deferred when the target note (on `originate`) or command (on `edit`) is not yet persisted — for example, when a plugin creates the note and originates the command in the same batch of handler effects. In that case the command's patient cannot be resolved yet, so `medication_id` passes this validation; the check then runs once the command is applied.
A malformed `medication_id` fails at command construction, before any patient lookup, while a well-formed UUID passed as a string is accepted.
* * *
###  ChartSectionReview 
Records that a section of the patient's chart was reviewed during a visit. Originating the command snapshots the patient's active records in that section onto the note, along with the rendered text of those records as they read at the time of review — the same thing that happens when a user clicks **Review** on a chart section in the Canvas UI. Use it to attest to a review your plugin has already performed, such as reconciling medications from an external source.
The command is always committed on origination, so there is no staged state to fill in and no need to pass `commit=True`.
Read the resulting snapshot back with the [ChartSectionReview](/sdk/data-chart-section-review/#chartsectionreview) data model.
> **Info:** This command supports `originate()` only since it is a read only command.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`section`|  _ChartSectionReviewCommand.Sections enum_| `true`| The chart section being reviewed. Required when instantiating the command. Must be one of `ChartSectionReviewCommand.Sections`.  
**Example** :
    ```python
    from canvas_sdk.commands import ChartSectionReviewCommand
    def compute():
        medication_review = ChartSectionReviewCommand(
            note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
            section=ChartSectionReviewCommand.Sections.MEDICATIONS,
        )
        return [medication_review.originate()]
    ```
####  ChartSectionReviewCommand.Sections 
Member| Value| Chart section  
---|---|---  
`CONDITIONS`| `conditions`| Conditions  
`SURGICAL_HISTORY`| `surgical_history`| Surgical History  
`MEDICATIONS`| `medications`| Medications  
`FAMILY_HISTORY`| `family_histories`| Family Histories  
`ALLERGIES`| `allergies`| Allergies  
`IMMUNIZATIONS`| `immunizations`| Immunizations  
> **Warning:** The member name for family history differs between the command and the data model: the command uses `ChartSectionReviewCommand.Sections.FAMILY_HISTORY`, while the data model uses `ChartSectionReviewSection.FAMILY_HISTORIES`. Both carry the same value, `family_histories`.
* * *
###  CloseGoal 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`goal_id`|  _int_| `true`| The `dbid` of the [Goal](/sdk/data-goal/#goal) being closed. Must be a goal on that patient's chart.  
`achievement_status`|  _AchievementStatus enum_| `false`| The final achievement status of the goal. Must be one of `GoalCommand.AchievementStatus`.  
`progress`|  _string_| `false`| A narrative about the patient's progress toward the goal.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
**Example** :
    ```python
    from canvas_sdk.commands import CloseGoalCommand, GoalCommand
    close_goal = CloseGoalCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        goal_id=12345,
        achievement_status=GoalCommand.AchievementStatus.ACHIEVED,
        progress="Patient has achieved the target weight goal of 150 lbs."
    )
    ```
###  Diagnose 
Records an active condition and assesses it for the first time. See Recording a condition for how it compares to Assess, MedicalHistory and AddCondition.
> **Warning:** Diagnose is planned for retirement in a future release, and `DiagnoseCommand` will be deprecated then. Use AssessCommand with `icd10_code` for new work: it records a new condition the same way, and reuses the patient's charted condition instead of adding a duplicate. Existing plugins that use `DiagnoseCommand` keep working for now.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`icd10_code`|  _string_| `true`| ICD-10 code of the condition being diagnosed. Search with the [ICD-10 condition endpoint](/sdk/utils/#get-icdcondition--icd-10-conditions).  
`background`|  _string_| `false`| Background information about the diagnosis.  
`approximate_date_of_onset`|  _datetime_| `false`| The approximate date the condition began.  
`today_assessment`|  _string_| `false`| The narrative for the initial assessment of the condition (max length: 2048 characters).  
**Example** :
    ```python
    from canvas_sdk.commands import DiagnoseCommand
    from datetime import datetime
    diagnose = DiagnoseCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        icd10_code='M54.50',
        background='lifted heavy box',
        approximate_date_of_onset=datetime(2012, 1, 1),
        today_assessment='unable to sleep lately'
    )
    ```
* * *
###  FamilyHistory 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`family_history`|  _string_ or _Coding_| `true`| A description of the family history being documented. Search with the [family-history endpoint](/sdk/utils/#get-snomedfamily-history--family-history-conditions).  
`relative`|  _string_| `false`| A description of the relative (e.g., mother, uncle). Search with the [family-relation endpoint](/sdk/utils/#get-snomedfamily-relation--family-relationships).  
`note`|  _string_| `false`| Additional notes or context about the family history (max length: 512 characters).  
**Coding Support** :
The `family_history` parameter accepts either:
  - **String** : Searches for matching family history conditions and selects the first result.
  - **Coding object** : Allows structured or unstructured coding
    - Supported systems: `SNOMED`, `UNSTRUCTURED`
    - Required fields: `system`, `code`
    - Optional field: `display`
The `relative` parameter also searches and selects the first result when a string is provided. Use specific terms (e.g., `"Paternal Grandfather"`, `"Maternal Grandfather"`) to avoid ambiguous matches.
**Example** :
    ```python
    from canvas_sdk.commands import FamilyHistoryCommand
    from canvas_sdk.commands.constants import CodeSystems, Coding
    # Using a string (searches and takes the first result — may be ambiguous)
    family_history = FamilyHistoryCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        family_history="Diabetes Type 2",
        relative="Mother",
        note="Diagnosed at age 45"
    )
    # Using a SNOMED code
    family_history_snomed = FamilyHistoryCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        family_history=Coding(
            system=CodeSystems.SNOMED,
            code="44054006",
            display="Diabetes Type 2"
        ),
        relative="Mother",
        note="Diagnosed at age 45"
    )
    # Using unstructured (free text)
    family_history_unstructured = FamilyHistoryCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        family_history=Coding(
            system=CodeSystems.UNSTRUCTURED,
            code="Family history of heart disease"
        ),
        relative="Father"
    )
    ```
* * *
###  FollowUp 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`structured`|  _boolean_| `false`| Whether the RFV is structured or not. Defaults to False.  
`requested_date`|  _date_| `false`| The desired follow up date.  
`note_type_id`|  _UUID (str)_| `false`| The desired type of appointment. See [NoteType](/sdk/data-note/#notetype).  
`coding`|  _Coding_ or _UUID (str)_| `true` if structured=True| The coding for the structured RFV. Either a full Coding object (with `code`, `system`, `display`) or a UUID string referencing a verified coding record. If a Coding is provided, it is validated against existing [ReasonForVisitSettingCoding](/sdk/data-reason-for-visit/#reasonforvisitsettingcoding) records  
`comment`|  _string_| `false`| Additional commentary on the RFV.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
**Example** :
    ```python
    from canvas_sdk.commands import FollowUpCommand
    from datetime import date
    structured = FollowUpCommand(
      note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
      structured=True,
      requested_date=date(2025, 3, 2),
      note_type_id="d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
      coding={'code': '49727002', 'system': 'http://snomed.info/sct', 'display': 'Cough'},
      comment='also wants to discuss treatment options'
    )
    # Example with a UUID string referencing a Coding record
    structured2 = FollowUpCommand(
      note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
      structured=True,
      requested_date=date(2025, 3, 2),
      note_type_id="d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
      coding="e2b1e1e3-3f52-4a0a-bb3a-123456789abc",  # Must correspond to an existing coding record
      comment="Discuss treatment options"
    )
    unstructured = FollowUpCommand(
      note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
      requested_date=date(2025, 3, 2),
      note_type_id="d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
      comment='also wants to discuss treatment options'
    )
    ```
* * *
###  Goal 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`goal_statement`|  _string_| `true`| Description of the goal.  
`start_date`|  _datetime_| `false`| The date the goal begins.  
`due_date`|  _datetime_| `false`| The date the goal is due.  
`achievement_status`|  _AchievementStatus enum_| `false`| The current achievement status of the goal.  
`priority`|  _Priority enum_| `false`| The priority of the goal.  
`progress`|  _string_| `false`| A narrative about the patient's progress toward the goal.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
`AchievementStatus`| Value| Description  
---|---|---  
`IN_PROGRESS`| `"in-progress"`| The goal is being pursued.  
`IMPROVING`| `"improving"`| Progress toward the goal is improving.  
`WORSENING`| `"worsening"`| Progress toward the goal is worsening.  
`NO_CHANGE`| `"no-change"`| No change in progress toward the goal.  
`ACHIEVED`| `"achieved"`| The goal has been achieved.  
`SUSTAINING`| `"sustaining"`| The achieved goal is being sustained.  
`NOT_ACHIEVED`| `"not-achieved"`| The goal was not achieved.  
`NO_PROGRESS`| `"no-progress"`| No progress has been made toward the goal.  
`NOT_ATTAINABLE`| `"not-attainable"`| The goal is not attainable.  
`Priority`| Value| Description  
---|---|---  
`HIGH`| `"high-priority"`| High priority.  
`MEDIUM`| `"medium-priority"`| Medium priority.  
`LOW`| `"low-priority"`| Low priority.  
**Example** :
    ```python
    from canvas_sdk.commands import GoalCommand
    from datetime import datetime
    goal = GoalCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        goal_statement='Eat more healthy vegetables.',
        start_date=datetime(2024, 1, 1),
        due_date=datetime(2024, 12, 31),
        achievement_status=GoalCommand.AchievementStatus.IN_PROGRESS,
        priority=GoalCommand.Priority.HIGH,
        progress='patient is frequenting local farmers market to find healthy options'
    )
    ```
* * *
###  HistoryOfPresentIllness 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`narrative`|  _string_| `true`| The narrative of the patient's history of present illness.  
**Example** :
    ```python
    from canvas_sdk.commands import HistoryOfPresentIllnessCommand
    hpi = HistoryOfPresentIllnessCommand(
            note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
            narrative='presents with chronic back pain and headaches'
        )
    ```
* * *
###  ImagingOrder 
**Command-specific parameters** :
Name| Type| Required to delegate / sign| Description  
---|---|---|---  
`image_code`|  _string_| `true`| Code identifier of the imaging order. Search with the [imaging-codes endpoint](/sdk/utils/#searching-for-imaging-codes).  
`diagnosis_codes`|  _list[string]_| `true`| ICD-10 Diagnosis codes justifying the imaging order. Search with the [ICD-10 condition endpoint](/sdk/utils/#get-icdcondition--icd-10-conditions).  
`priority`|  _Priority enum_| `false`| Priority of the imaging order. Must be one of `ImagingOrderCommand.Priority`.  
`additional_details`|  _string_| `false`| Additional details or instructions related to the imaging order (max length: 1024 characters).  
`service_provider`|  _ServiceProvider_| `true`| Service provider of the imaging order. Search with the [contacts endpoint](/sdk/utils/#searching-for-contacts-and-service-providers).  
`comment`|  _string_| `false`| Additional comments (max length: 1024 characters).  
`ordering_provider_key`|  _string_| `true`| The [Staff](/sdk/data-staff/#staff) `id` of the provider ordering the imaging.  
`linked_items_urns`|  _list[string]_| `false`| List of URNs for items linked to the imaging order command.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment). Linking also adds the assessed condition's ICD-10 codes to `diagnosis_codes` unless they're already listed.  
**Command-specific actions** :
Action Name| Available When| Description  
---|---|---  
`delegate_action`| command is staged| Delegates the order by creating a task.  
`sign_action`| command is staged| Signs the order, transitioning it from staged to committed state.  
`print_specialist`| command is committed| Prints the order using a specialist-focused template.  
`print_patient`| command is committed| Prints the order using a patient-friendly template.  
`fax`| command is committed| Transmits the order electronically via fax.  
**Enums and Types** :
**`Priority`**
Priority| Value| Description  
---|---|---  
`ROUTINE`| `"Routine"`| A routine order.  
`URGENT`| `"Urgent"`| An urgent order.  
`STAT`| `"STAT"`| A STAT (immediate) order.  
**Example** :
    ```python
    from canvas_sdk.commands import ImagingOrderCommand
    from canvas_sdk.commands.constants import ServiceProvider
    imaging_order = ImagingOrderCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        image_code="G0204",
        diagnosis_codes=["E119"],
        priority=ImagingOrderCommand.Priority.ROUTINE,
        comment="this is a comment",
        additional_details="more details",
        ordering_provider_key="b8a7c6d5-4e3f-4a2b-9c1d-0e8f7a6b5c4d",
        service_provider=ServiceProvider(
          first_name="Clinic",
          last_name="Imaging",
          practice_name="Clinic Imaging",
          specialty="radiology",
          business_address="Street Address",
          business_phone="1234569874",
          business_fax="1234569874"
     ),
    )
    ```
* * *
###  ImagingReview 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`report_ids`|  _list[string]_| `true`| List of [ImagingReport](/sdk/data-imaging/#imagingreport) IDs to review. Must be reports on that patient's chart.  
`message_to_patient`|  _string_| `false`| Message to communicate findings to the patient.  
`communication_method`|  _ReportReviewCommunicationMethod enum_| `false`| Method for patient communication. Must be one of `ReportReviewCommunicationMethod`.  
`linked_items_urns`|  _list[string]_| `false`| List of URNs for items linked to the review.  
`comment`|  _string_| `false`| Internal comment about the review.  
**Example** :
    ```python
    from canvas_sdk.commands import ImagingReviewCommand
    from canvas_sdk.commands.commands.review import ReportReviewCommunicationMethod
    from canvas_sdk.v1.data import ImagingReport, Patient
    patient = Patient.objects.get(id="patient-id")
    # Get imaging reports to review
    imaging_reports = ImagingReport.objects.filter(patient=patient, review__isnull=True, review_mode='RR')
    report_ids = [str(report.id) for report in imaging_reports]
    imaging_review = ImagingReviewCommand(
        note_uuid="a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        report_ids=report_ids,
        message_to_patient="Your imaging results show no abnormalities.",
        communication_method=ReportReviewCommunicationMethod.DELEGATED_CALL_CAN_LEAVE_MESSAGE,
        comment="All clear, no follow-up needed."
    )
    ```
* * *
###  ImmunizationStatement 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`cpt_code`|  _string_ or _Coding_| `false`*| The CPT code for the immunization procedure. Used with CVX code to search against ontologies server for validation. Search with the [immunization endpoint](/sdk/utils/#get-cptimmunization--search-immunizations).  
`cvx_code`|  _string_ or _Coding_| `false`*| The CVX code for the vaccine administered. Used with CPT code to search against ontologies server for validation. Search with the [immunization endpoint](/sdk/utils/#get-cptimmunization--search-immunizations).  
`unstructured`|  _Coding_| `false`*| Free-text immunization description.  
`approximate_date`|  _date_| `false`| The approximate date when the immunization was administered.  
`comments`|  _string_| `false`| Additional comments about the immunization (max 255 characters).  
*Must provide either both `cpt_code` and `cvx_code` together, or `unstructured` alone (cannot mix structured and unstructured).
**Coding Support** :
The `cpt_code` and `cvx_code` parameters accept either:
  - **String** : Looks up the code in the respective system (CPT or CVX)
  - **Coding object** : Allows structured coding
    - `cpt_code` must use system: `CPT`
    - `cvx_code` must use system: `CVX`
    - Required fields: `system`, `code`
    - Optional field: `display`
The `unstructured` parameter:
  - **Coding object** : For free-text immunizations
    - Required system: `UNSTRUCTURED`
    - Required fields: `system`, `code`
    - Optional field: `display`
**Examples** :
    ```python
    from canvas_sdk.commands.commands.immunization_statement import ImmunizationStatementCommand
    from canvas_sdk.commands.constants import CodeSystems, Coding
    from datetime import date
    immunization_statement = ImmunizationStatementCommand(
        cpt_code="90724",
        cvx_code="88",
        approximate_date=date(2024, 1, 15),
        comments="Patient received influenza vaccine"
    )
    # Using Coding objects for structured codes
    immunization_statement_coded = ImmunizationStatementCommand(
        cpt_code=Coding(
            system=CodeSystems.CPT,
            code="90724"
        ),
        cvx_code=Coding(
            system=CodeSystems.CVX,
            code="88"
        ),
        approximate_date=date(2024, 1, 15),
        comments="Patient received influenza vaccine"
    )
    # Using unstructured (free text immunization)
    immunization_statement_unstructured = ImmunizationStatementCommand(
        unstructured=Coding(
            system=CodeSystems.UNSTRUCTURED,
            code="COVID-19 booster at pharmacy"
        ),
        approximate_date=date(2024, 1, 15)
    )
    ```
* * *
###  Immunize 
Records a vaccine **administered** during the visit, including the lot it came from.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`vaccine_id`|  _UUID_| `true`| The `id` of a [Vaccine](/sdk/data-vaccine/#vaccine) in this instance's catalog. Must be active.  
`lot_id`|  _UUID_| `false`*| The `id` of a [VaccineLot](/sdk/data-vaccine/#vaccinelot) with doses on hand.  
`lot_number`|  _string_| `false`*| A lot number this instance does not stock, recorded as free text (max 20 characters).  
`manufacturer`|  _string_| `false`| The vaccine's manufacturer (max 100 characters).  
`expiration_date`|  _date_| `false`| The lot's expiration date.  
`sig`|  _string_| `false`| Directions, as free text - for example `"0.5 mL IM, left deltoid"` (max 75 characters).  
`consent_given`|  _boolean_| `true`| Whether the patient consented after reviewing the Vaccine Information Statement. Must be `true` to commit.  
`given_by_id`|  _string_| `true`| The `id` of the [Staff](/sdk/data-staff/#staff) member who administered the vaccine. Must be active.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
*`lot_id` and `lot_number` are mutually exclusive; supplying both raises an error. Either may be omitted.
**Choosing a vaccine and lot** :
Both are instance-specific data, so look them up rather than hard-coding identifiers. A vaccine is only selectable on a note if it is active and carries an active CPT charge. See [Vaccine](/sdk/data-vaccine/) for the query.
**Manufacturer and expiration** :
When you supply a `lot_id` and leave `manufacturer` or `expiration_date` unset, the command fills them in from the lot. Anything you set explicitly is used as-is - including an explicit `None`, which is treated as a deliberate choice to leave the field empty rather than as an omission.
A `lot_number` is free text with no inventory record behind it, so nothing is derived from it; set `manufacturer` and `expiration_date` yourself if you want them recorded.
**Example** :
    ```python
    from datetime import date
    from canvas_sdk.commands.commands.immunize import ImmunizeCommand
    from canvas_sdk.v1.data import Vaccine, VaccineLot
    vaccine = Vaccine.objects.filter(active=True, cvx_code="135").first()
    lot = VaccineLot.objects.filter(vaccine__id=vaccine.id, on_hand_inventory__gt=0).first()
    # manufacturer and expiration_date are taken from the lot
    immunize = ImmunizeCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        vaccine_id=vaccine.id,
        lot_id=lot.id,
        sig="0.5 mL IM, left deltoid",
        consent_given=True,
        given_by_id="b8a7c6d5-4e3f-4a2b-9c1d-0e8f7a6b5c4d",
    )
    # A lot the instance does not stock: supply the details yourself
    immunize_unstocked = ImmunizeCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        vaccine_id=vaccine.id,
        lot_number="ABC-12345",
        manufacturer="Acme Vaccines",
        expiration_date=date(2028, 1, 31),
        sig="0.5 mL IM, left deltoid",
        consent_given=True,
        given_by_id="b8a7c6d5-4e3f-4a2b-9c1d-0e8f7a6b5c4d",
    )
    ```
* * *
###  Instruct 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`coding`| **Coding**| `true`| The SNOMED code or UNSTRUCTURED code that represents the instruction. Search SNOMED with the [instruction endpoint](/sdk/utils/#get-snomedinstruction--instructions).  
`comment`|  _string_| `false`| Additional comments related to the instruction.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
The Educational Material command only supports a fixed set of selectable values and is not available in this commands module. For free-text patient education, use `InstructCommand` instead — its `UNSTRUCTURED` coding accepts arbitrary instruction text.
**Example** :
    ```python
    from canvas_sdk.commands import InstructCommand
    from canvas_sdk.commands.constants import CodeSystems, Coding
    # SNOMED code
    InstructCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        coding=Coding(system=CodeSystems.SNOMED, code="65921008"),
        comment="To address mild dehydration symptoms"
    )
    # UNSTRUCTURED code
    InstructCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        coding=Coding(system=CodeSystems.UNSTRUCTURED, code="Physical medicine neuromuscular training"),
    )
    ```
* * *
###  LabOrder 
The `LabOrderCommand` is used to initiate a lab order through the Canvas system. This command requires detailed information about the lab partner, the tests being ordered, and the provider placing the order.
There is no dedicated endpoint for ordering labs or medications. Labs and prescriptions are ordered by creating `LabOrderCommand` and Prescribe commands in a note via the SDK, typically in response to an [event](/sdk/events/). Built-in validations ensure that:
  - The specified lab partner exists (whether provided by name or ID).
  - The ordered tests are available for the chosen lab partner.
**Electronic ordering:** LabOrder commands support the `send()` method for electronic ordering of signed orders directly to lab partners. However, electronic ordering has additional requirements:
  - Only lab partners with electronic ordering enabled support the `send()` method.
  - The command must be committed/signed before it can be sent electronically.
  - The patient must have an address and phone number on file.
  - The ordering provider must have an NPI.
**Command-specific parameters** :
Name| Type| Required to send| Description  
---|---|---|---  
`lab_partner`|  _string_| `true`| The [lab partner](/sdk/data-lab-partner-and-test/#labpartner) processing the order. Accepts either the lab partner's name or its unique identifier (ID).  
`tests_order_codes`|  _list[string]_| `true`| A list of codes or IDs for the [tests](/sdk/data-lab-partner-and-test/#labpartnertest-attributes) being ordered. The system verifies that each provided value corresponds to an available test for the specified lab partner.  
`ordering_provider_key`|  _string_| `false`| The [Staff](/sdk/data-staff/#staff) `id` of the provider ordering the tests.  
`diagnosis_codes`|  _list[string]_| `false`| ICD-10 Diagnosis codes justifying the lab order. Search with the [ICD-10 condition endpoint](/sdk/utils/#get-icdcondition--icd-10-conditions).  
`fasting_required`|  _boolean_| `false`| Indicates if fasting is required for the tests.  
`comment`|  _string_| `false`| Additional comments related to the lab order (max length: 128 characters).  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment). Linking also adds the assessed condition's ICD-10 codes to `diagnosis_codes` unless they're already listed.  
**Command-specific actions** :
Action Name| Available When| Description  
---|---|---  
`sign_send_action`| command is staged| Signs and immediately sends the order electronically to the lab partner.  
`send_action`| command is staged| Sends the order electronically to the chosen lab partner.  
`sign_action`| command is staged| Signs the order, transitioning it from staged to committed state.  
`print_requisition_form`| command is committed| Prints the order using a requisition-focused template for lab submission.  
`print_specimen_label`| command is committed| Prints the template using a specimen-focused template.  
`fax_requisition_form`| command is committed| Transmits the order electronically via fax.  
**ABN Workflow Actions**
When the ABN (Advance Beneficiary Notice) workflow is enabled, additional actions become available:
Action Name| Available When| Description  
---|---|---  
`send_abn_signed`| command is staged| Sends the order electronically after ABN requirements are met.  
`make_changes`| command is staged| Allows modifications to complete ABN requirements before sending.  
####  Validations 
  - **Lab Partner Validation:** The system checks that the provided `lab_partner` (by name or ID) exists in the system. If no matching lab partner is found, a validation error is raised.
  - **Tests Order Codes Validation:** Each test code or ID in `tests_order_codes` is verified against the tests available for the specified lab partner. If one or more tests cannot be found, the error will indicate which codes or IDs are missing.
**Example** :
    ```python
    from canvas_sdk.commands import LabOrderCommand
    from canvas_sdk.v1.data.lab import LabPartner, LabPartnerTest
    partner = LabPartner.objects.first()
    tests = [test.order_code for test in LabPartnerTest.objects.filter(lab_partner=partner)]
    LabOrderCommand(
      lab_partner=str(partner.id),
      tests_order_codes=tests,
      ordering_provider_key="b8a7c6d5-4e3f-4a2b-9c1d-0e8f7a6b5c4d",
      diagnosis_codes=["E119"],
      fasting_required=True,
      comment="Patient should fast for 8 hours before the test."
    )
    ```
* * *
###  LabReview 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`report_ids`|  _list[string]_| `true`| List of [LabReport](/sdk/data-labs/#labreport) IDs to review. Must be reports on that patient's chart.  
`message_to_patient`|  _string_| `false`| Message to communicate findings to the patient.  
`communication_method`|  _ReportReviewCommunicationMethod enum_| `false`| Method for patient communication. Must be one of `ReportReviewCommunicationMethod`.  
`linked_items_urns`|  _list[string]_| `false`| List of URNs for items linked to the review.  
`comment`|  _string_| `false`| Internal comment about the review.  
**Example** :
    ```python
    from canvas_sdk.commands import LabReviewCommand
    from canvas_sdk.commands.commands.review import ReportReviewCommunicationMethod
    from canvas_sdk.v1.data import LabReport, Patient
    patient = Patient.objects.get(id="patient-id")
    # Get lab reports to review
    lab_reports = LabReport.objects.filter(patient=patient, review__isnull=True, review_mode='RR')
    report_ids = [str(report.id) for report in lab_reports]
    lab_review = LabReviewCommand(
        note_uuid="a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        report_ids=report_ids,
        message_to_patient="Your lab results are within normal range.",
        communication_method=ReportReviewCommunicationMethod.DELEGATED_CALL_CAN_LEAVE_MESSAGE,
        comment="All values normal, no follow-up needed."
    )
    ```
* * *
###  MedicalHistory 
Backfills a condition the patient had in the past that is not active now. See Recording a condition for how it compares to Assess and AddCondition.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`past_medical_history`|  _string_| `true`| An ICD-10 code or description of the past medical condition. ICD-10 codes are strongly preferred (see note below). Search with the [ICD-10 condition endpoint](/sdk/utils/#get-icdcondition--icd-10-conditions).  
`approximate_start_date`|  _date_| `false`| Approximate start date of the condition.  
`approximate_end_date`|  _date_| `false`| Approximate end date of the condition.  
`show_on_condition_list`|  _boolean_| `false`| Whether the condition should appear on the condition list.  
`comments`|  _string_| `false`| Additional comments (max length: 1000 characters).  
**Important: Use ICD-10 codes for accurate matching.** The `past_medical_history` field searches for matching conditions and selects the first result. When a text description is provided, similar conditions may match first. To guarantee the correct condition, pass the ICD-10 code directly (e.g., `"I1010"`).
**Example** :
    ```python
    from canvas_sdk.commands import MedicalHistoryCommand
    from datetime import date
    # Preferred: use the ICD-10 code for exact matching
    MedicalHistoryCommand(
        past_medical_history="I1010",  # Resistant Hypertension
        approximate_start_date=date(2015, 1, 1),
        show_on_condition_list=True,
        comments="Controlled with medication."
    )
    # Also works but may match a different condition if the description is ambiguous
    MedicalHistoryCommand(
        past_medical_history="Resistant Hypertension",
        approximate_start_date=date(2015, 1, 1),
        show_on_condition_list=True,
        comments="Controlled with medication."
    )
    ```
* * *
###  MedicationStatement 
Records a medication the patient reports taking, without prescribing it. See Recording a medication for how it compares to the other medication commands.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`fdb_code`|  _string_ or _Coding_| `true`| The [FDB code](/sdk/utils/#fdb_code) of the medication  
`sig`|  _string_| `false`| Administration details of the medication (max length: 1000 characters).  
**Coding Support** :
The `fdb_code` parameter accepts either:
  - **String (FDB code)** : Looks up the medication in the FDB system
  - **Coding object** : Allows structured or unstructured coding
    - Supported systems: `FDB`, `UNSTRUCTURED`
    - Required fields: `system`, `code`
    - Optional field: `display`
**Converting an RxNorm code to an FDB code:** MedicationStatement requires an FDB code; it cannot be originated directly from an RxNorm RXCUI. If you have an RxNorm code, use the [ontologies service](/sdk/utils/#searching-for-medications) grouped-medication lookup, which returns a `med_medication_id` — that value is the FDB code:
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    # search for a specific RxNorm RXCUI
    response_json = ontologies_http.get_json(f"/fdb/grouped-medication/?{urlencode({'rxnorm_rxcui': 313782})}").json()
    ```
**Example** :
    ```python
    from canvas_sdk.commands import MedicationStatementCommand
    from canvas_sdk.commands.constants import CodeSystems, Coding
    # Using an FDB code string (recommended for FDB medications)
    medication_statement = MedicationStatementCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        fdb_code='198698',
        sig='two pills taken orally'
    )
    # Using an FDB Coding object
    medication_statement_fdb = MedicationStatementCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        fdb_code=Coding(
            system=CodeSystems.FDB,
            code='198698',
            display='aspirin 81 mg oral tablet'
        ),
        sig='two pills taken orally'
    )
    # Using unstructured (free text medication)
    medication_statement_unstructured = MedicationStatementCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        fdb_code=Coding(
            system=CodeSystems.UNSTRUCTURED,
            code='Herbal supplement for joint health'
        )
    )
    ```
* * *
###  OrderDme 
Orders durable medical equipment (DME), such as a wheelchair, catheter, or shower chair, from a note and sends the order to a supplier. Order a product from your DME formulary with `dme_product_id`, or describe an off-formulary item with `free_text_item`.
Admins manage the formulary in the Django Admin UI under **DME Products**. In a plugin, look up a product and its ID with the [DmeProduct](/sdk/data-dme/#dmeproduct) data model, as the example below does.
**Command-specific parameters** :
Name| Type| Required to sign| Description  
---|---|---|---  
`dme_product_id`|  _string_| `true`, unless `free_text_item` is set| The `id` of an active [DmeProduct](/sdk/data-dme/#dmeproduct) in your DME formulary. Can't be combined with `free_text_item`.  
`free_text_item`|  _string_| `true`, unless `dme_product_id` is set| Description of an off-formulary item (max length: 255 characters). Can't be combined with `dme_product_id`.  
`diagnosis_codes`|  _list[string]_| `true`| ICD-10 Diagnosis codes justifying the order. Search with the [ICD-10 condition endpoint](/sdk/utils/#get-icdcondition--icd-10-conditions).  
`quantity`|  _integer_| `true`| Number of units ordered. Must be at least 1.  
`length_of_need`|  _string_| `false`| How long the patient needs the equipment, such as `"6 months"` or `"Lifetime"` (max length: 255 characters). Canvas prints this text on the order as written.  
`service_provider`|  _ServiceProvider_| `false`| The supplier the order is sent to. Search with the [contacts endpoint](/sdk/utils/#searching-for-contacts-and-service-providers).  
`ordering_provider_key`|  _string_| `true`| The [Staff](/sdk/data-staff/#staff) `id` of the provider ordering the equipment. The staff member must be active and able to prescribe.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment). Linking also adds the assessed condition's ICD-10 codes to `diagnosis_codes` unless they're already listed.  
Setting both `dme_product_id` and `free_text_item`, a `quantity` below 1, or a `length_of_need` longer than 255 characters raises a validation error when you create the command object.
Canvas leaves a field empty when its value doesn't resolve. A `dme_product_id` resolves only to an active formulary product, and an `ordering_provider_key` only to an active staff member. Diagnosis codes that don't match an ICD-10 condition are dropped. The command can't be signed until every required field has a value. Signing also fails when the ordering provider isn't an active prescriber, because the printed order names them as the signer.
Signing saves the item's formulary name and code and the indications with the order, along with the patient's latest height and weight. Later changes to the formulary or the patient's vitals don't change the printed order.
**Command-specific actions** :
Action Name| Available When| Description  
---|---|---  
`sign_action`| command is staged| Signs the order, transitioning it from staged to committed state.  
`print_order`| command is committed| Prints the order as a requisition. Requires printing access.  
`fax`| command is committed| Faxes the order, prefilling the supplier's fax number when one is on file. Requires printing access.  
To filter or annotate the products, indications, suppliers, and ordering providers a user sees while filling in the command, handle the `PRE_SEARCH` and `POST_SEARCH` [events](/sdk/events/#order-dme-command) for the `ITEM`, `INDICATIONS`, `SEND_TO`, and `ORDERING_PROVIDER` fields, such as `ORDER_DME__ITEM__POST_SEARCH`.
Suppliers you create with the [ServiceProvider effect](/sdk/effect-service-provider/) aren't searched in **Send to** automatically. To offer them there, see [Offering your own providers alongside the directory](/guides/customize-search-results/#offering-your-own-providers-alongside-the-directory).
**Example** :
    ```python
    from canvas_sdk.commands import OrderDmeCommand
    from canvas_sdk.commands.constants import ServiceProvider
    from canvas_sdk.v1.data import DmeProduct
    supplier = ServiceProvider(
        first_name="Acme",
        last_name="Medical Supply",
        practice_name="Acme Medical Supply",
        specialty="Durable Medical Equipment",
        business_fax="5555550100",
    )
    # A product from the DME formulary, looked up by its HCPCS code.
    # get() raises an error unless exactly one active product has this code.
    wheelchair = DmeProduct.objects.get(code="K0001", active=True)
    formulary_order = OrderDmeCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        dme_product_id=str(wheelchair.id),
        diagnosis_codes=["N186"],
        quantity=1,
        length_of_need="Lifetime",
        service_provider=supplier,
        ordering_provider_key="b8a7c6d5-4e3f-4a2b-9c1d-0e8f7a6b5c4d",
    )
    # An off-formulary item
    free_text_order = OrderDmeCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        free_text_item="Bariatric shower chair",
        diagnosis_codes=["E6601"],
        quantity=1,
        length_of_need="12 months",
        service_provider=supplier,
        ordering_provider_key="b8a7c6d5-4e3f-4a2b-9c1d-0e8f7a6b5c4d",
    )
    ```
* * *
###  SurgicalHistory 
Records a past surgical procedure, coded in SNOMED. See Recording a condition for how it compares to the other condition commands.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`past_surgical_history`|  _string_ or _Coding_| `true`| A description of the past surgical procedure. Search with the [procedures endpoint](/sdk/utils/#get-snomedprocedures--surgical-history-procedures).  
`approximate_date`|  _date_| `false`| Approximate date of the surgery.  
`comment`|  _string_| `false`| Additional comments (max length: 1000 characters).  
**Coding Support** :
The `past_surgical_history` parameter accepts either:
  - **String** : Searches for matching surgical procedures and selects the first result.
  - **Coding object** : Allows structured or unstructured coding
    - Supported systems: `SNOMED`, `UNSTRUCTURED`
    - Required fields: `system`, `code`
    - Optional field: `display`
**Example** :
    ```python
    from canvas_sdk.commands import PastSurgicalHistoryCommand
    from canvas_sdk.commands.constants import CodeSystems, Coding
    from datetime import date
    # Using a string (searches and takes the first result)
    PastSurgicalHistoryCommand(
        past_surgical_history="Appendectomy",
        approximate_date=date(2008, 6, 15),
        comment="No complications reported."
    )
    # Using a SNOMED code
    surgical_history_snomed = PastSurgicalHistoryCommand(
        past_surgical_history=Coding(
            system=CodeSystems.SNOMED,
            code="80146002",
            display="Appendectomy"
        ),
        approximate_date=date(2008, 6, 15),
        comment="No complications reported."
    )
    # Using unstructured (free text)
    surgical_history_unstructured = PastSurgicalHistoryCommand(
        past_surgical_history=Coding(
            system=CodeSystems.UNSTRUCTURED,
            code="Minor outpatient procedure on left knee"
        ),
        approximate_date=date(2020, 3, 10)
    )
    ```
* * *
###  Perform 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`cpt_code`|  _string_ or _Coding_| `true`| The CPT code of the procedure or action performed. Look it up in the [Charge Description Master](/sdk/data-charge-description-master/#chargedescriptionmaster).  
`notes`|  _string_| `false`| Additional notes related to the performed procedure.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
**Coding Support** :
The `cpt_code` parameter accepts either:
  - **String** : Searches for matching procedures
  - **Coding object** : Allows structured or unstructured coding
    - Supported systems: `CPT`, `UNSTRUCTURED`
    - Required fields: `system`, `code`
    - Optional field: `display`
**Example** :
    ```python
    from canvas_sdk.commands import PerformCommand
    from canvas_sdk.commands.constants import CodeSystems, Coding
    # Using a string (searches for matching procedures)
    PerformCommand(
        cpt_code="99213",
        notes="Patient presented with a common cold."
    )
    # Using a CPT code
    perform_cpt = PerformCommand(
        cpt_code=Coding(
            system=CodeSystems.CPT,
            code="99213",
            display="Office visit, established patient"
        ),
        notes="Annual wellness visit"
    )
    # Using unstructured (free text)
    perform_unstructured = PerformCommand(
        cpt_code=Coding(
            system=CodeSystems.UNSTRUCTURED,
            code="Custom procedure performed"
        ),
        notes="Non-standard procedure documentation"
    )
    ```
* * *
###  Plan 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`narrative`|  _string_| `true`| The narrative of the patient's plan.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
**Example** :
    ```python
    from canvas_sdk.commands import PlanCommand
    plan = PlanCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        narrative='will return in 2 weeks to check on pain management'
    )
    ```
* * *
###  POCLabTest 
The `POCLabTestCommand` is used to document the results of a Point-of-Care (POC) lab test performed in the clinic — distinct from `LabOrder` (which sends tests to an external lab partner) and `LabReview` (which reviews returned results). The command captures the template used, the indications, individual measured values, and a free-text remarks field.
Built-in validations ensure that:
  - The provided `template` UUID resolves to an active POC [`LabReportTemplate`](/sdk/data-lab-report-template/#labreporttemplate).
  - Each `test_values` entry's `label` matches one of the template's [field labels](/sdk/data-lab-report-template/#labreporttemplatefield) (case-insensitive).
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`template`|  _UUID | string_| `true`| The UUID of the active POC [`LabReportTemplate`](/sdk/data-lab-report-template/#labreporttemplate). Accepts UUID instances or UUID-formatted strings.  
`indications`|  _list[string]_| `false`| ICD-10 diagnosis codes justifying the test. Search with the [ICD-10 condition endpoint](/sdk/utils/#get-icdcondition--icd-10-conditions).  
`test_values`|  _list[TestValue]_| `false`| The measured values, each tagged with its template-field label. See `TestValue` below.  
`remarks`|  _string (≤512)_| `false`| Free-text comments from the clinician.  
**Enums and Types** :
**`TestValue`**
A dataclass representing a single measured value within a POC lab test result.
Attribute| Type| Description  
---|---|---  
`label`|  _string_|  The template field's label (must match a field on the template).  
`value`|  _string_|  The measured value (as a string).  
`TestValue.to_dict()` returns the `{"label": ..., "value": ...}` dict shape consumed by the runtime.
**Helper methods** :
  - `set_test_value(label, value)` — Adds or replaces a test value by label. If a `TestValue` with the same `label` already exists on the command, it is replaced (so calling `set_test_value` twice with the same label leaves a single entry).
####  Validations 
  - **Template Validation:** The `template` UUID must resolve to a [`LabReportTemplate`](/sdk/data-lab-report-template/#labreporttemplate) that is `active=True` and `poc=True`. Templates from external lab partners or inactive templates are rejected.
  - **Test Values Validation:** Each `TestValue.label` must match (case-insensitive) the `label` of one of the resolved template's [fields](/sdk/data-lab-report-template/#labreporttemplatefield). Unknown labels cause a validation error.
The valid labels are the `label` of each [`LabReportTemplateField`](/sdk/data-lab-report-template/#labreporttemplatefield) on the template's [`fields`](/sdk/data-lab-report-template/#labreporttemplate) relation:
    ```python
    from canvas_sdk.v1.data import LabReportTemplate
    template = LabReportTemplate.objects.active().point_of_care().first()
    valid_labels = [field.label for field in template.fields.all()]
    ```
**Example** :
    ```python
    from canvas_sdk.commands import POCLabTestCommand
    from canvas_sdk.commands.commands.poc_lab_test import TestValue
    from canvas_sdk.v1.data import LabReportTemplate
    template = LabReportTemplate.objects.active().point_of_care().first()
    command = POCLabTestCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        template=template.id,
        indications=["E11.9"],
        test_values=[
            TestValue(label="pH", value="6.5"),
            TestValue(label="Glucose", value="120"),
        ],
        remarks="Sample collected mid-stream",
    )
    # Or via the helper (overwrites by label):
    command.set_test_value("pH", "6.8")
    ```
* * *
###  Prescribe 
Writes a new prescription for a medication the patient is not already on, and can send it to a pharmacy. See Recording a medication for how it compares to the other medication commands.
**Electronic prescribing:** Prescribe commands support the `send()` method for electronic transmission of signed prescriptions. However, electronic prescribing has additional validations:
  - A pharmacy must be specified on the command before it can be sent.
  - The command must be committed/signed before it can be sent electronically.
  - The prescriber must have an SPI (Surescripts Prescriber Identifier) number on file, or the send is restricted with `eRx unavailable, prescriber missing SPI number`. SPI is a send requirement only: a prescriber without one can still review and sign the prescription.
  - For a controlled substance, the prescriber must be enrolled in EPCS, or the send is restricted with `eRx unavailable, prescriber not enrolled in EPCS`.
  - For a controlled substance (a medication with a DEA schedule), the patient's [sex at birth](/sdk/data-patient/#sexatbirth) must be male or female, or the send is restricted with `eRx unavailable, patient sex at birth must be male or female`.
These validations apply to Refill and AdjustPrescription as well, and in the Canvas UI as well as through the SDK — in the UI a restricted prescription offers no send action at all.
**Overriding the prescriber address:** By default, the prescriber address transmitted on the prescription is derived from the prescriber's primary practice location. For workflows where a provider works across multiple offices — for example white bagging, where the medication ships to the office where the patient is being seen — pass a `practice_location_override` to `send()` to use a specific practice location's address instead:
    ```python
    from canvas_sdk.commands import PrescribeCommand
    def compute():
        existing_prescribe = PrescribeCommand(command_uuid='e32b85d9-ccb7-4e4f-a0e5-8783ed2d9528')
        return [existing_prescribe.send(practice_location_override='a1b2c3d4-e5f6-7890-abcd-ef1234567890')]
    ```
  - `practice_location_override` is the `id` of a [PracticeLocation](/sdk/data-practicelocation/#practicelocation). When set, that location's business name, phone, fax, and street address replace the prescriber's default on the outgoing prescription.
  - If the id does not correspond to an existing practice location, the send raises an error rather than falling back to the default address.
  - The override applies only to `send()`-initiated (plugin-driven) prescriptions. It does not affect prescriptions a clinician sends from the charting UI.
**Signing is not supported programmatically.** A Prescribe command cannot be committed (signed) via the SDK. Surescripts requires certain elements to be present in the UI when prescribing in order to remain certified, so the prescriber must physically sign the prescription in the UI. The sign and send actions were separated into distinct steps so that the **send** step can be performed programmatically, but only after the prescription has been manually signed in the UI. The [send all prescriptions](/sdk/example-send_all_prescriptions/) example plugin demonstrates the supported programmatic-send flow.
**Command-specific parameters** :
Name| Type| Required to review / send| Description  
---|---|---|---  
`fdb_code`|  _string_| `false`*| The [FDB code](/sdk/utils/#fdb_code) of the medication.  
`compound_medication_id`|  _string_| `false`*| The id of an existing [CompoundMedication](/sdk/data-compound-medication/#compoundmedication) to prescribe.  
`compound_medication_data`| `CompoundMedicationData`| `false`*| Data for creating a new compound medication inline.  
`icd10_codes`|  _list[string]_| `false`| List of ICD-10 codes (maximum 2) associated with the prescription. Must be active [Conditions](/sdk/data-condition/#condition) on the patient's chart, including encounter diagnoses kept off the problem list.  
`sig`|  _string_| `true`| Administration instructions/details of the medication. Up to 1000 characters — see Limits.  
`days_supply`|  _integer_| `false`| Number of days the prescription is intended to cover.  
`quantity_to_dispense`|  _Decimal | float | integer_| `true`| The amount of medication to dispense. Must be greater than zero — see Limits.  
`type_to_dispense`|  _ClinicalQuantity_| `true`**| Information about the form or unit of the medication to dispense. Get the available quantities from the [medication search](/sdk/utils/#searching-for-medications)'s `clinical_quantities`.  
`refills`|  _integer_| `true`| Number of refills allowed for the prescription. From 0 to 99 — see Limits.  
`substitutions`|  _Substitutions enum_| `true`| Specifies whether substitutions (e.g., generic drugs) are allowed.  
`pharmacy`|  _string_| `false`| The NCPDP ID of the pharmacy where the prescription should be sent. [Look it up via the pharmacy search](/sdk/utils/#searching-for-pharmacies).  
`prescriber_id`|  _string_| `true`| The [Staff](/sdk/data-staff/#staff) id of the prescriber.  
`supervising_provider_id`|  _string_| `false`| The [Staff](/sdk/data-staff/#staff) id of the supervising provider of the prescriber.  
`note_to_pharmacist`|  _string_| `false`| Additional notes or instructions for the pharmacist. Up to 210 characters — see Limits.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment). Linking also adds the assessed condition to `icd10_codes` unless it's already listed. A prescription holds at most two codes, so a link that would add a third is rejected.  
*Must provide exactly one of: fdb_code, compound_medication_id, or compound_medication_data
**ClinicalQuantity is only required when `fdb_code` is provided. It is optional for compound medications.
**Compound medications:** Compound medications have no FDB code, so they are referenced with `compound_medication_id` or `compound_medication_data` rather than `fdb_code`. Because a compound medication has no FDB code, the quantity-to-dispense format is not preselected — the same as the UI behavior — and must be chosen manually in the UI after the command is inserted. Do not supply `type_to_dispense` for compound medications.
**Command-specific actions** :
Action Name| Available When| Description  
---|---|---  
`sign_send_action`| command is in review| Signs and immediately sends the prescription electronically.  
`sign_action`| command is in review| Signs the prescription, transitioning it from staged to committed state.  
`print_action`| command is in review| Prints and commits the command.  
`make_changes`| command is in review| Allow users to revert the command to staged state and make changes.  
`send_action`| command is committed| Sends the prescription electronically.  
**Enums and Types**
Substitutions| Value| Description  
---|---|---  
`ALLOWED`| `"allowed"`| Generic or substitute medications are permitted.  
`NOT_ALLOWED`| `"not_allowed"`| Only the prescribed brand is allowed.  
**CompoundMedicationData** : Data for creating a compound medication inline within a prescription.
Field Name| Type| Description| Required  
---|---|---|---  
`formulation`|  _string_|  The compound medication formulation (max 105 characters)| `true`  
`potency_unit_code`|  _[PotencyUnit](/sdk/data-compound-medication/#potencyunit) value_| The unit of measurement for the medication.| `true`  
`controlled_substance`|  _[ControlledSubstanceSchedule](/sdk/data-compound-medication/#controlledsubstanceschedule) value_| The controlled substance schedule (`N` for none).| `true`  
`controlled_substance_ndc`|  _string_|  NDC for controlled substances (dashes removed)| `false`*  
`active`|  _bool_|  Whether the compound medication is active (default: true)| `false`  
*Required when controlled_substance is not "N" (None)
**Examples**
** _Option 1: Standard Prescription (FDB Code)_**
    ```python
    from canvas_sdk.commands.constants import ClinicalQuantity
    from canvas_sdk.commands import PrescribeCommand
    prescription = PrescribeCommand(
        fdb_code="216092",
        icd10_codes=["R51"],
        sig="Take one tablet daily after meals",
        days_supply=30,
        quantity_to_dispense=30,
        type_to_dispense=ClinicalQuantity(
            representative_ndc="12843016128",
            ncpdp_quantity_qualifier_code="C48542"
        ),
        refills=3,
        substitutions=PrescribeCommand.Substitutions.ALLOWED,
        pharmacy="pharmacy_ncpdp_id",
        prescriber_id="a7c2e9d1-3b4f-4a6c-8e0d-5f1a2b3c4d5e",
        supervising_provider_id='c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f',
        note_to_pharmacist="Please verify patient's insurance before processing."
    )
    ```
**_Option 2: Existing Compound Medication (by ID)_**
Note: `type_to_dispense` should not be provided for compound medications as this field will auto-populate in the command when it is inserted in the note
    ```python
    from canvas_sdk.commands.constants import ClinicalQuantity
    from canvas_sdk.commands import PrescribeCommand
    from canvas_sdk.v1.data.compound_medication import CompoundMedication as CompoundMedicationModel
    # Get an existing compound medication (let's assume it exists in the database)
    compound_med = CompoundMedicationModel.objects.filter(
        active=True,
        formulation="Testosterone 200mg/mL in Grapeseed Oil"
    ).first()
    prescription = PrescribeCommand(
        compound_medication_id=str(compound_med.id),
        icd10_codes=["R51"],
        sig="Take one tablet daily after meals",
        days_supply=30,
        quantity_to_dispense=30,
        refills=3,
        substitutions=PrescribeCommand.Substitutions.ALLOWED,
        pharmacy="pharmacy_ncpdp_id",
        prescriber_id="a7c2e9d1-3b4f-4a6c-8e0d-5f1a2b3c4d5e",
        supervising_provider_id='c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f',
        note_to_pharmacist="Please verify patient's insurance before processing."
    )
    ```
**_Option 3: Create New Compound Medication Inline_**
    ```python
    from canvas_sdk.commands.constants import ClinicalQuantity
    from canvas_sdk.commands.commands.prescribe import PrescribeCommand, CompoundMedicationData
    from canvas_sdk.v1.data.compound_medication import CompoundMedication
    compound_medication_data = CompoundMedicationData(
        formulation="Testosterone 200mg/mL in Grapeseed Oil",
        potency_unit_code=CompoundMedication.PotencyUnits.GRAM,
        controlled_substance=CompoundMedication.ControlledSubstanceOptions.SCHEDULE_III,
        controlled_substance_ndc="12345678901",
        active=True,
    )
    prescription = PrescribeCommand(
        compound_medication_data=compound_medication_data,
        icd10_codes=["M79.3"],
        sig="Apply thin layer to affected area twice daily",
        days_supply=30,
        quantity_to_dispense=30,
        refills=3,
        substitutions=PrescribeCommand.Substitutions.ALLOWED,
        pharmacy="pharmacy_ncpdp_id",
        prescriber_id="a7c2e9d1-3b4f-4a6c-8e0d-5f1a2b3c4d5e",
        supervising_provider_id='c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f',
        note_to_pharmacist="Please verify patient's insurance before processing."
    )
    ```
**Validation Notes**
  - Medication Type Validation: Exactly one of fdb_code, compound_medication_id, or compound_medication_data must be provided
  - Compound Medication ID: When using compound_medication_id, the system validates that the compound medication exists
  - Compound Medication Data: When using compound_medication_data:
    - All required fields in the dataclass must be provided
    - If controlled substance is not "N" (None), then controlled_substance_ndc is required
    - The formulation is limited to 105 characters
    - Any dashes in the NDC are automatically removed
    - Before creating a new compound medication, the system checks if a compound with the same formulation and potency unit code already exists. If it does, it reuses the existing compound medication instead of creating a new one.
  - Potency Unit and Controlled Substance Values: Must use valid enum values from PotencyUnit and ControlledSubstanceSchedule
**Limits**
A prescription has to fit what can be transmitted to the pharmacy, so four fields are bounded. These apply to Refill and AdjustPrescription as well, which share the fields.
Field| Limit  
---|---  
`sig`| 1000 characters  
`note_to_pharmacist`| 210 characters  
`refills`| 0 to 99  
`quantity_to_dispense`| greater than 0  
All four are checked when the command is turned into an effect, not when the field is set. Building a command up field by field therefore never fails part-way through, and `originate()` or `edit()` reports every value that is out of bounds at once:
    ```python
    from canvas_sdk.commands import PrescribeCommand
    def compute():
        prescribe = PrescribeCommand(note_uuid='c4d1e4b8-6a5f-4b3a-9e2d-7f8a9b0c1d2e')
        # Neither assignment raises.
        prescribe.refills = 100
        prescribe.quantity_to_dispense = 0
        # This raises a validation error naming both values.
        return [prescribe.originate()]
    ```
* * *
###  PhysicalExam 
**Note:** The PhysicalExamCommand is a subclass of the QuestionnaireCommand, so it supports all the questionnaire features. That includes recording responses either with the `answers` parameter or with the `questions` property and `add_response()` — see Recording responses.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`questionnaire_id`|  _string_| `true`| The id of the [Questionnaire](/sdk/data-questionnaire/#questionnaire) being answered by the patient. The questionnaire's use case in charting must be **Physical Exam** , and it must be set to originate in charting.  
`answers`|  _list ofAnswer_| `false`| The responses to record, one per question. Defaults to an empty list.  
####  Toggle Questions Feature 
The PhysicalExamCommand and the ReviewOfSystemsCommand both support toggling questions on/off, so practitioners can enable or disable specific questions based on patient relevance. The methods, property, and behavior described here are identical for both commands.
The following methods are available. In each, `question_id` is the [Question](/sdk/data-questionnaire/#question) `dbid` (an integer, accepted as `int` or `str`):
**Methods** :
Method| Parameters| Returns| Description  
---|---|---|---  
`is_question_enabled`| `question_id: str` or `int`| `bool`| Check if a specific question is enabled (not skipped).  
`set_question_enabled`| `question_id: str` or `int, enabled: bool`| `None`| Enable or disable a specific question.  
**Properties** :
Property| Type| Description  
---|---|---  
`question_toggles`| `dict`| All current toggle states, mapping `question_id` → `enabled` — e.g. `{"12": True, "13": False, "14": True}`.  
**Example - Working with Existing Commands** :
A common use case is retrieving existing PhysicalExam commands from a note and modifying their toggle states. Here's how to work with the Canvas SDK data objects:
    ```python
    from canvas_sdk.commands import PhysicalExamCommand
    from canvas_sdk.v1.data import Command, Note
    from logger import log
    # Get existing physical exam commands from a note
    note = Note.objects.get(id="ff287601-fff4-46c4-b21f-04760e88adf1")
    physical_exam_commands = Command.objects.filter(
        note=note,
        schema_key="exam"  # Physical exam commands have schema_key "exam"
    ).all()
    effects = []
    for command in physical_exam_commands:
        # The command.data contains the question responses and skip states
        # Example structure of command.data:
        # {
        #     "questionnaire": {"value": "83d93454-25a9-404d-83a5-e0ed2ec3af00"},
        #     "question-12": "70",  # Body length response
        #     "question-13": None,   # Head circumference (no response)
        #     "skip-12": True,   # Body length is enabled (counterintuitive: skip=True means enabled)
        #     "skip-13": False,  # Head circumference is disabled
        # }
        # Create a PhysicalExamCommand instance from the existing command
        exam = PhysicalExamCommand(command_uuid=str(command.id))
        # The exam.questions property gives you access to all questions with their IDs
        log.info(f"Processing Physical Exam Command: {exam.command_uuid}")
        for question in exam.questions:
            # Each question object has an 'id' property with the question ID
            question_id = question.dbid
            if exam.is_question_enabled(question_id):
                log.info(f"Question {question_id} is enabled")
                # Check if there's a response in the command data
                question_key = f"question-{question_id}"
                if question_key in command.data:
                    response = command.data[question_key]
                    if response:
                        log.info(f"Response: {response}")
        # Example: Enable all questions that have responses, disable those without
        for question in exam.questions:
            question_id = question.dbid
            question_key = f"question-{question_id}"
            # Check if question has a response in command.data
            has_response = question_key in command.data and command.data[question_key]
            if has_response:
                exam.set_question_enabled(question_id, True)
            else:
                # Optionally disable questions without responses
                exam.set_question_enabled(question_id, False)
        effects.append(exam.edit())
    ```
**Example - Creating a New Physical Exam** :
    ```python
    from canvas_sdk.commands import PhysicalExamCommand
    # Create a new physical exam
    exam = PhysicalExamCommand(
      note_uuid='a229456f-c10d-4f85-a04e-e8675d4e56dd',
      questionnaire_id='83d93454-25a9-404d-83a5-e0ed2ec3af00',
    )
    questions = exam.questions  # Retrieve the list of questions
    # Returns: [
    #               Question(
    #                       self.name='question-12',
    #                       self.label='Body length (in)',
    #                       self.type='TXT',
    #                       self.options=[ResponseOption(self.dbid=38, self.name='Body length (in)', self.code='8306-3', self.value='')],
    #                       self.response=None
    #               ),
    #               Question(
    #                       self.name='question-13',
    #                       self.label='Head circumference (cm)',
    #                       self.type='TXT', self.options=[ResponseOption(self.dbid=39, self.name='Head circumference (cm)', self.code='8287-5', self.value='')],
    #                       self.response=None
    #               )
    # Check if a question is enabled
    if exam.is_question_enabled("12"):
      print("Body length question is enabled.")
    # Disable irrelevant questions
    exam.set_question_enabled("13", False)
    # Get all toggle states
    states = exam.question_toggles
    # Returns: {"12": True, "13": False, "14": True, ...}, where keys are question IDs and values are enabled states.
    # Working with existing exam - toggle states are preserved
    existing_exam = PhysicalExamCommand(command_uuid='d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f80')
    # All previously set toggle states are automatically loaded
    ```
* * *
###  Questionnaire 
####  Overview 
The `QuestionnaireCommand` is used to present a questionnaire to a patient and commit their responses to an interview. It requires the ID of the questionnaire
**Automatic Questionnaire ID Loading** : When instantiating a QuestionnaireCommand with an existing `command_uuid`, the questionnaire_id will be automatically loaded from the database if not explicitly provided. This means you don't need to specify the questionnaire_id when working with existing commands.
**Note on the scoring narrative:** Setting a `result` value on the command instance has no effect — it is ignored by the command methods (`originate`, `edit`, `commit`). The questionnaire scoring narrative is instead set through the [Create a Questionnaire Result](/sdk/effect-questionnaires/#creating-a-questionnaire-result) effect. Once set, the narrative can be read from the command's `data` attribute, displays in the UI command, and (if the questionnaire is configured to show in the Social Determinants section) displays there too.
In addition to the basic parameters, this command records responses in either of two ways:
  - **The`answers` parameter** — you pass the responses in, one per question, and the command works out how to apply each one. Nothing in your code branches on a question's type. Use this when you already have the question and option ids.
  - **The`questions` property with `add_response()`** — you read the questionnaire's questions off the command and record a response on each question object. The keyword you pass differs by question type, so your code branches on it. Use this when you need to inspect the questions or their options at runtime to decide what to answer.
Both arrive at the same result, and they can be combined. `answers` is applied when the command's effect is built: it replaces whatever was recorded on the questions it names, and leaves a response recorded with `add_response()` on any other question alone. `answers` is not itself carried in the effect.
**Recording responses with`answers`**
The `answers` parameter takes a list of `Answer` objects, one per question. Each names a question and the response it takes; the command looks up the question, dispatches on its type, and resolves an option id to the option itself. A question id that is not in the questionnaire, an option id the question does not offer, or a response the question's type does not allow raises a `ValueError` when the effect is built.
**`Answer` fields**:
Name| Type| Required| Description  
---|---|---|---  
`question_id`|  _integer_| `true`| The [Question](/sdk/data-questionnaire/#question) `dbid`.  
`response`|  _string_ , _integer_ , or _list ofSelection_| `true`| Text for a text question, a number for an integer question, a [ResponseOption](/sdk/data-questionnaire/#responseoption) `dbid` for a radio question, an ISO 8601 `YYYY-MM-DD` string for a date question, or a list of `Selection` objects for a checkbox question.  
A checkbox question is the only kind whose responses carry comments, and each of its selections carries its own — so a comment belongs to a `Selection` rather than to the answer as a whole.
> **Warning:** A date answer given through `answers` must be a string. `response` accepts a string, an integer or a list of `Selection`, so a `datetime.date` is refused. The question's own `add_response(date=...)` is the path that takes a `datetime.date` or a `datetime.datetime`.
**`Selection` fields**:
Name| Type| Required| Description  
---|---|---|---  
`option_id`|  _integer_| `true`| The [ResponseOption](/sdk/data-questionnaire/#responseoption) `dbid` to tick.  
`comment`|  _string_| `false`| What this selection is qualified with.  
`selected`|  _boolean_| `false`| Defaults to `true`. Set it to `false` to untick the option — one a payload says nothing about keeps the state it already had.  
**Recording responses with`questions` and `add_response()`**
Retrieve the list of questions via the `questions` property and record responses for each question using the question object's `add_response()` method. Each question type enforces its expected response format:
  - **Text questions (TYPE_TEXT):** Accept a keyword argument `text` (a string).
  - **Integer questions (TYPE_INTEGER):** Accept a keyword argument `integer` (a value convertible to an integer; a non-convertible value raises an error).
  - **Radio questions (TYPE_RADIO):** Accept a keyword argument `option` (a `ResponseOption` instance); only one option may be selected.
  - **Checkbox questions (TYPE_CHECKBOX):** Accept a keyword argument `option` (a `ResponseOption` instance) along with an optional boolean `selected` (defaulting to True) and an optional string `comment`. Multiple responses can be recorded.
  - **Date questions (TYPE_DATE):** Accept a keyword argument `date` (a `datetime.date`, a `datetime.datetime` normalized to its date, or an ISO 8601 date string `YYYY-MM-DD`). The value is stored as a normalized `YYYY-MM-DD` string; a string carrying a time component, an unparseable string, or a wrong type raises an error.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`questionnaire_id`|  _string_| `true`| The id of the [Questionnaire](/sdk/data-questionnaire/#questionnaire) being answered by the patient.  
`answers`|  _list ofAnswer_| `false`| The responses to record, one per question. Defaults to an empty list.  
**Example** — instantiating an empty questionnaire:
    ```python
    from canvas_sdk.commands import QuestionnaireCommand
    questionnaire = QuestionnaireCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        questionnaire_id='c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
    )
    ```
####  Usage Example 
Below is an example that answers a questionnaire with `answers`. Each `Answer` names a question by its `dbid` and gives the response in the form that question takes, so nothing branches on the question's type:
    ```python
    from canvas_sdk.commands.commands.questionnaire import Answer, QuestionnaireCommand, Selection
    from canvas_sdk.effects import Effect
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Note, Questionnaire
    class MyHandler(BaseHandler):
        def compute(self) -> list[Effect]:
          questionnaire = Questionnaire.objects.filter(name="Exercise").first()
          note = Note.objects.last()
          command = QuestionnaireCommand(
              note_uuid=str(note.id),
              questionnaire_id=str(questionnaire.id),
              answers=[
                  # A text question.
                  Answer(question_id=12, response="Thanks for all the fish"),
                  # An integer question.
                  Answer(question_id=13, response=42),
                  # A radio question, answered with the id of one of its options.
                  Answer(question_id=14, response=101),
                  # A date question. Give the date as a string, not a datetime.date.
                  Answer(question_id=15, response="2026-07-14"),
                  # A checkbox question, answered with one Selection per option ticked.
                  Answer(
                      question_id=16,
                      response=[
                          Selection(option_id=201),
                          Selection(option_id=202, comment="Don't panic"),
                      ],
                  ),
              ],
          )
          # The responses are included when the command is originated.
          return [command.originate()]
    ```
An option id that the question does not offer, or a question id that is not in the questionnaire, raises a `ValueError` rather than recording something the questionnaire does not define.
Below is the same thing written the other way, retrieving the questions and adding responses to them based on their type:
    ```python
    from canvas_sdk.commands.commands.questionnaire import QuestionnaireCommand
    from canvas_sdk.commands.commands.questionnaire.question import ResponseOption
    from canvas_sdk.effects import Effect
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Note, Questionnaire
    class MyHandler(BaseHandler):
        def compute(self) -> list[Effect]:
          q = Questionnaire.objects.filter(name="Exercise").first()
          note = Note.objects.last()
          # Create a QuestionnaireCommand instance.
          command = QuestionnaireCommand(questionnaire_id=str(q.id))
          command.note_uuid = str(note.id)
          # Alternatively you can just retrieve an existing questionnaire command, and only return an `edit` effect.
          # Retrieve the list of questions.
          questions = command.questions
          # Record responses for each question.
          for question in questions:
              if question.type == ResponseOption.TYPE_TEXT:
                  # For text questions, pass a 'text' keyword argument.
                  question.add_response(text=f"Thanks for all the fish")
              elif question.type == ResponseOption.TYPE_INTEGER:
                  # For integer questions, pass an 'integer' keyword argument.
                  question.add_response(integer=42)
              elif question.type == ResponseOption.TYPE_RADIO:
                  # For radio questions, pass an 'option' keyword argument (a ResponseOption instance).
                  first_option = question.options[0]
                  question.add_response(option=first_option)
              elif question.type == ResponseOption.TYPE_CHECKBOX:
                  # For checkbox questions, add responses with option, selected flag, and optionally a comment.
                  first_option = question.options[0]
                  last_option = question.options[-1]
                  question.add_response(option=first_option, selected=True, comment="Don't panic")
                  question.add_response(option=last_option, selected=True)
              elif question.type == ResponseOption.TYPE_DATE:
                  # For date questions, pass a 'date' keyword argument.
                  question.add_response(date="2026-01-15")
          # The responses are included when the command is originated.
          return [command.originate()]
    ```
####  Explanation 
  - **Retrieving Questions:** The `questions` property returns a list of question objects created from the questionnaire's data.
  - **Recording Responses:** Either set `answers` and let the command resolve each response against its question, or record them one at a time. Each question object provides an `add_response()` method that enforces the correct response format:
    - For **TextQuestion** , you must pass a `text` parameter.
    - For **IntegerQuestion** , you must pass an `integer` parameter.
    - For **RadioQuestion** , you must pass an `option` parameter (a `ResponseOption` instance) that corresponds to one of the allowed options.
    - For **CheckboxQuestion** , you must pass an `option` parameter along with an optional `selected` flag (defaulting to True) and an optional `comment`. Multiple responses can be recorded for checkbox questions.
    - **Note for Checkboxes:** Only the responses explicitly provided in the command payload will be updated in the UI. If a checkbox response is already selected and is not sent as unselected in the payload, its state remains unchanged.
    - For **DateQuestion** , you must pass a `date` parameter (a `datetime.date`, a `datetime.datetime`, or an ISO 8601 date string), stored as a normalized `YYYY-MM-DD` string.
  - **Creating and editing:** responses recorded with `answers` or `add_response()` are included when the command is originated, so `[command.originate()]` inserts the questionnaire already filled in, and `command.originate(commit=True)` also commits it. To change the responses of a questionnaire command that is already in the note, set them on a command with the same `command_uuid` and return its `edit()`.
* * *
###  ReasonForVisit 
**Command-specific parameters** :
Name| Type| Required| Description  
---|---|---|---  
`structured`|  _boolean_| `false`| Whether the RFV is structured or not. Defaults to False.  
`coding`|  _Coding_ or _UUID (str)_| `true` if structured=True| The coding for the structured RFV. Either a full Coding object (with `code`, `system`, `display`) or a UUID string referencing a verified coding record. If a Coding is provided, it is validated against existing [ReasonForVisitSettingCoding](/sdk/data-reason-for-visit/#reasonforvisitsettingcoding) records  
`comment`|  _string_| `false`| Additional commentary on the RFV.  
**Example** :
    ```python
    from canvas_sdk.commands import ReasonForVisitCommand
    structured_rfv = ReasonForVisitCommand(
      note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
      structured=True,
      coding={'code': '49727002', 'system': 'http://snomed.info/sct', 'display': 'Cough'},
      comment='also wants to discuss treatment options'
    )
    # Example with a UUID string referencing a Coding record
    structured_rfv2 = ReasonForVisitCommand(
      note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
      structured=True,
      coding="e2b1e1e3-3f52-4a0a-bb3a-123456789abc",  # Must correspond to an existing coding record
      comment="Discuss treatment options"
    )
    unstructured_rfv = ReasonForVisitCommand(
      note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
      comment='also wants to discuss treatment options'
    )
    ```
###  Refer 
**Command-specific parameters** :
Name| Type| Required to delegate / sign| Description  
---|---|---|---  
`service_provider`|  _ServiceProvider_| `true`| The service provider associated with the referral command. Search with the [contacts endpoint](/sdk/utils/#searching-for-contacts-and-service-providers).  
`diagnosis_codes`|  _list[string]_| `true`| A list of relevant ICD-10 Diagnosis. Search with the [ICD-10 condition endpoint](/sdk/utils/#get-icdcondition--icd-10-conditions).  
`clinical_question`|  _ClinicalQuestion enum_| `true`| The clinical question prompting the referral. Must be one of `ReferCommand.ClinicalQuestion`  
`priority`|  _Priority enum_| `false`| Priority of the imaging order. Must be one of `ReferCommand.Priority`.  
`notes_to_specialist`|  _string_| `true`| Notes or additional information directed to the specialist.  
`include_visit_note`|  _boolean_| `false`| Flag indicating whether the visit note should be included in the referral.  
`comment`|  _string_| `false`| An optional comment providing further details about the referral.  
`linked_items_urns`|  _list[string]_| `false`| List of URNs for items linked to the referral command.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment). Linking also adds the assessed condition's ICD-10 codes to `diagnosis_codes` unless they're already listed.  
**Command-specific actions** :
Action Name| Available When| Description  
---|---|---  
`delegate_action`| command is staged| Delegates the order by creating a task.  
`sign_action`| command is staged| Signs the order, transitioning it from staged to committed state.  
`print_specialist`| command is committed| Prints the order using a specialist-focused template.  
`print_patient`| command is committed| Prints the order using a patient-friendly template.  
`fax`| command is committed| Transmits the order electronically via fax.  
**Enums and Types** :
**`Priority`**
Priority| Value| Description  
---|---|---  
`ROUTINE`| `"Routine"`| A routine referral.  
`URGENT`| `"Urgent"`| An urgent referral.  
`STAT`| `"STAT"`| A STAT (immediate) referral.  
**`ClinicalQuestion`**
Clinical Question| Value| Description  
---|---|---  
`COGNITIVE_ASSISTANCE`| `"Cognitive Assistance (Advice/Guidance)"`| Cognitive assistance (advice/guidance).  
`ASSISTANCE_WITH_ONGOING_MANAGEMENT`| `"Assistance with Ongoing Management"`| Assistance with ongoing management.  
`SPECIALIZED_INTERVENTION`| `"Specialized intervention"`| Specialized intervention.  
`DIAGNOSTIC_UNCERTAINTY`| `"Diagnostic Uncertainty"`| Diagnostic uncertainty.  
**Example** :
    ```python
    from canvas_sdk.commands import ReferCommand
    from canvas_sdk.commands.constants import ServiceProvider
    refer_command = ReferCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        diagnosis_codes=["E119"],
        priority=ReferCommand.Priority.ROUTINE,
        clinical_question=ReferCommand.ClinicalQuestion.DIAGNOSTIC_UNCERTAINTY,
        comment="this is a comment",
        notes_to_specialist="This is a note to specialist",
        include_visit_note=True,
        service_provider=ServiceProvider(
          first_name="Clinic",
          last_name="Acupuncture",
          practice_name="Clinic Acupuncture",
          specialty="Acupuncture",
          business_address="Street Address",
          business_phone="1234569874",
          business_fax="1234569874"
     ),
    )
    ```
* * *
###  Reference 
Embeds a diagnostic view in the note. A diagnostic view is a saved combination of lab tests and questionnaire codes configured on your instance; referencing one renders that patient's results for those codes as a timeseries inside the note, so a reviewer sees the trend without leaving the chart.
The command renders as a read-only table. There are no fields for a user to fill in, so the diagnostic view has to be chosen by whatever inserts the command — a user can only commit or delete it, and enter it in error once committed.
Unlike ChartSectionReview, it is not committed on origination: it stays staged until you pass `commit=True` to `originate()` or send a separate `commit()`.
Read the committed reference back with the [Reference](/sdk/data-reference/#reference) data model.
> **Warning:** The rendered name and table are derived from the diagnostic view when the command is originated, and are not recalculated afterwards. Pointing an existing command at a different diagnostic view with `edit()` leaves the previous view's name and table on display. To change the view, delete the command and originate a new one.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`diagnostic_view_id`|  _UUID_ or _string_| `true`| The id of the [DiagnosticView](/sdk/data-diagnostic-view/#diagnosticview) to embed. An id that does not match a diagnostic view on the instance is discarded, leaving the command with no view to render.  
**Example** :
    ```python
    from canvas_sdk.commands import ReferenceCommand
    from canvas_sdk.v1.data import DiagnosticView
    def compute():
        a1c_view = DiagnosticView.objects.filter(name="Hemoglobin A1c").first()
        if not a1c_view:
            return []
        reference = ReferenceCommand(
            note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
            diagnostic_view_id=a1c_view.id,
        )
        return [reference.originate(commit=True)]
    ```
* * *
###  ReferralReview 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`report_ids`|  _list[string]_| `true`| List of [ReferralReport](/sdk/data-referral/#referralreport) IDs to review. Must be reports on that patient's chart.  
`message_to_patient`|  _string_| `false`| Message to communicate findings to the patient.  
`communication_method`|  _ReportReviewCommunicationMethod enum_| `false`| Method for patient communication. Must be one of `ReportReviewCommunicationMethod`.  
`linked_items_urns`|  _list[string]_| `false`| List of URNs for items linked to the review.  
`comment`|  _string_| `false`| Internal comment about the review.  
**Example** :
    ```python
    from canvas_sdk.commands import ReferralReviewCommand
    from canvas_sdk.commands.commands.review import ReportReviewCommunicationMethod
    from canvas_sdk.v1.data import Patient, ReferralReport
    patient = Patient.objects.get(id="patient-id")
    # Get referral reports to review
    referral_reports = ReferralReport.objects.filter(patient=patient, review__isnull=True, review_mode='RR')
    report_ids = [str(report.id) for report in referral_reports]
    referral_review = ReferralReviewCommand(
        note_uuid="a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        report_ids=report_ids,
        message_to_patient="Your referral has been reviewed and approved.",
        communication_method=ReportReviewCommunicationMethod.DELEGATED_CALL_CAN_LEAVE_MESSAGE,
        comment="Referral approved, patient notified."
    )
    ```
* * *
###  Refill 
Renews a prescription for a medication the patient is already on, and can send it to a pharmacy. See Recording a medication for how it compares to the other medication commands.
**Command-specific parameters** :
Check the Prescribe command for the parameters used in the Refill command. Refill supports `send()` under the same electronic prescribing validations.
**Example** :
    ```python
    from canvas_sdk.commands import RefillCommand, PrescribeCommand
    from canvas_sdk.commands.constants import ClinicalQuantity
    RefillCommand(
        fdb_code="216092",
        icd10_codes=["R51"],
        sig="Take one tablet daily after meals",
        days_supply=30,
        quantity_to_dispense=30,
        type_to_dispense=ClinicalQuantity(
            representative_ndc="12843016128",
            ncpdp_quantity_qualifier_code="C48542"
        ),
        refills=3,
        substitutions=PrescribeCommand.Substitutions.ALLOWED,
        pharmacy="pharmacy_ncpdp_id",
        prescriber_id="a7c2e9d1-3b4f-4a6c-8e0d-5f1a2b3c4d5e",
        supervising_provider_id="c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
        note_to_pharmacist="Please verify patient's insurance before processing."
    )
    ```
* * *
###  RemoveAllergy 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`allergy_id`|  _string_| `true`| The id of the [AllergyIntolerance](/sdk/data-allergy-intolerance/#allergyintolerance) to remove. Must be an allergy already recorded on that patient's chart.  
`narrative`|  _string_| `false`| Additional context or narrative for the removal (max length: 512 characters).  
**Example** :
    ```python
    from canvas_sdk.commands import RemoveAllergyCommand
    RemoveAllergyCommand(
        allergy_id="e5f6a7b8-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
        narrative="Allergy no longer applies after reassessment."
    )
    ```
* * *
###  Remove Past Medical History 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`condition_id`|  _string_| `true`| The id of the [Condition](/sdk/data-condition/#condition) being removed from the patient's past medical history. Must be a committed, resolved, non-surgical condition already recorded on that patient's chart, with no committed assessment against it. An assessment that was entered in error, or is not committed yet, does not block removal.  
`rationale`|  _string_| `false`| Additional context or narrative for the removal (max length: 512 characters).  
Committing this command enters the target condition in error, removing it from the patient's conditions list. The Past Medical History command that originally recorded the entry stays committed and visible in the note. Entering this command in error reverses the removal, returning the entry to the patient's chart. Each removal is recorded as a [RemovePastMedicalHistoryEvent](/sdk/data-remove-past-medical-history-event/), which you can query from the data module.
> **Info:** An entry with a committed assessment cannot be removed, because the assessment would be left describing nothing. The in-note picker leaves these entries out, and a plugin that names one gets a validation error: `Condition {id} has assessments recorded against it, so this command cannot remove it`. The rule also applies at commit, so an assessment committed after the removal was originated still blocks the commit.
**Example** :
    ```python
    from canvas_sdk.commands import RemovePastMedicalHistoryCommand
    from canvas_sdk.v1.data import Condition
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    # Leave out entries with a committed assessment, which this command refuses.
    past_medical_history_entry = (
        Condition.objects.for_patient(patient_id)
        .committed()
        .filter(clinical_status="resolved", surgical=False)
        .exclude(assessments__committer__isnull=False, assessments__entered_in_error__isnull=True)
        .first()
    )
    RemovePastMedicalHistoryCommand(
        condition_id=past_medical_history_entry.id,
        rationale="Imported in error from the HIE feed.",
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
    )
    ```
* * *
###  Resolve Condition 
Closes an active condition that is no longer relevant to track. See Updating or removing a condition for how it compares to the other condition commands.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`condition_id`|  _string_| `true`| The id of the [Condition](/sdk/data-condition/#condition) being resolved. Must be an **active** condition on that patient's chart — committed, not entered in error, and not already resolved.  
`show_in_condition_list`|  _boolean_| `false`| Determines whether the condition remains visible in patient chart summary.  
`rationale`|  _string_| `false`| Additional context.  
    ```python
    from canvas_sdk.commands.commands.resolve_condition import ResolveConditionCommand
    from canvas_sdk.v1.data import Condition
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    patient_condition = Condition.objects.for_patient(patient_id).committed().active().first()
    ResolveConditionCommand(
       condition_id=patient_condition.id,
       show_in_condition_list=True,
       rationale="Additional notes.",
       note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
    )
    ```
* * *
###  Review of Systems 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`questionnaire_id`|  _string_| `true`| The id of the [Questionnaire](/sdk/data-questionnaire/#questionnaire) being answered by the patient. The questionnaire's use case in charting must be **Review of Systems** , and it must be set to originate in charting.  
`answers`|  _list ofAnswer_| `false`| The responses to record, one per question. Defaults to an empty list.  
####  Toggle Questions Feature 
The ReviewOfSystemsCommand supports the same question-toggling functionality as the PhysicalExamCommand, allowing practitioners to enable or disable specific system-review questions based on patient relevance. The available methods (`is_question_enabled`, `set_question_enabled`) and the `question_toggles` property are documented once under the PhysicalExam Toggle Questions Feature — they behave identically here.
**Example** :
    ```python
    from canvas_sdk.commands import ReviewOfSystemsCommand
    # Create a new review of systems
    ros = ReviewOfSystemsCommand(
      note_uuid='8a18931a-acd9-474b-9070-ccd6fd472313',
      questionnaire_id='ed92577b-a023-4370-bc85-2b57e8afc4d8',
    )
    questions = ros.questions  # Retrieve the list of questions
    # Returns: [
    #               Question(
    #                       self.name='question-14',
    #                       self.label='Recurrent fever or chills',
    #                       self.type='TXT',
    #                       self.options=[]],
    #                       self.response=None
    #               ),
    #               Question(
    #                       self.name='question-25',
    #                       self.label='Other',
    #                       self.type='TXT', self.options=[],
    #                       self.response=None
    #               )
    # Check if a question is enabled
    if ros.is_question_enabled("14"):
      print("Recurrent fever or chills question is enabled.")
    # Disable irrelevant questions
    ros.set_question_enabled("25", False)
    # Get all toggle states
    states = ros.question_toggles
    # Returns: {"14": True, "25": False, "26": True, ...}, where keys are question IDs and values are enabled states.
    # Working with existing ros - toggle states are preserved
    existing_ros = ReviewOfSystemsCommand(command_uuid='d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f80')
    # All previously set toggle states are automatically loaded
    ```
**Note:** The ReviewOfSystemsCommand is a subclass of the QuestionnaireCommand, so it supports all the questionnaire features. That includes recording responses either with the `answers` parameter or with the `questions` property and `add_response()` — see Recording responses.
* * *
###  StopMedication 
Records that a patient is stopping a medication, along with the reason. See Recording a medication for how it compares to the other medication commands.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`medication_id`|  _string_| `true`| The id of the [Medication](/sdk/data-medication/#medication) being stopped. Must be a medication already recorded on that patient's chart.  
`rationale`|  _string_| `false`| The reason for stopping the medication.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
**Example** :
    ```python
    from canvas_sdk.commands import StopMedicationCommand
    stop_medication = StopMedicationCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        medication_id='f0a1b2c3-d4e5-4f6a-8b9c-0d1e2f3a4b5c',
        rationale='In remission'
    )
    ```
* * *
###  StructuredAssessment 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`questionnaire_id`|  _string_| `true`| The id of the [Questionnaire](/sdk/data-questionnaire/#questionnaire) being answered by the patient. The questionnaire's use case in charting must be **Structured Assessment** , and it must be set to originate in charting.  
`answers`|  _list ofAnswer_| `false`| The responses to record, one per question. Defaults to an empty list.  
**Note:** The StructuredAssessmentCommand is a subclass of the QuestionnaireCommand, so it supports all the questionnaire features. That includes recording responses either with the `answers` parameter or with the `questions` property and `add_response()` — see Recording responses.
**Example** :
    ```python
    from canvas_sdk.commands import StructuredAssessmentCommand
    questionnaire = StructuredAssessmentCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        questionnaire_id='c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
    )
    ```
* * *
###  Task 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`title`|  _string_| `true`| The title or summary of the task.  
`assign_to`|  _TaskAssigner_| `true`| Specifies the assignee (role, team, or individual).  
`due_date`|  _date_| `false`| Due date for completing the task.  
`priority`|  _TaskPriority enum_| `false`| Priority of the task. Must be one of `TaskPriority`.  
`comment`|  _string_| `false`| Additional comments or notes about the task.  
`labels`|  _list[string]_| `false`| Labels to apply to the task. Each value is matched (case-insensitive) against an existing [TaskLabel](/sdk/data-task/#tasklabel) by name; values that don't match an existing label are ignored.  
`linked_items_urns`|  _list[string]_| `false`| URNs for items linked to the task.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
**Enums and Types** :
**`TaskPriority`**
Priority| Description  
---|---  
`STAT`| The request should be actioned immediately — highest possible priority. E.g. an emergency.  
`URGENT`| The request should be actioned promptly — higher priority than routine.  
`ROUTINE`| The request has normal priority.  
**TaskAssigner Type** :
Key| Type| Required| Description  
---|---|---|---  
`to`|  _AssigneeType_| `true`| Type of assignee (e.g., role, team, etc.).  
`id`|  _integer_| `false`| The `dbid` of the assignee, in the table selected by `to`: a [CareTeamRole](/sdk/data-care-team/#careteamrole) when `to` is `ROLE`, a [Team](/sdk/data-team/#team) when `to` is `TEAM`, or a [Staff](/sdk/data-staff/#staff) when `to` is `STAFF`. Omit when `to` is `UNASSIGNED`.  
AssigneeType| Value| Description  
---|---|---  
`ROLE`| `"role"`| Task assigned to a specific [CareTeamRole](/sdk/data-care-team/#careteamrole) (`id` is the role's `dbid`).  
`TEAM`| `"team"`| Task assigned to a specific [Team](/sdk/data-team/#team) (`id` is the team's `dbid`).  
`UNASSIGNED`| `"unassigned"`| Task is unassigned.  
`STAFF`| `"staff"`| Task assigned to a specific [Staff](/sdk/data-staff/#staff) member (`id` is the staff member's `dbid`).  
**Example** :
    ```python
    from canvas_sdk.commands import TaskCommand
    from canvas_sdk.commands.commands.task import TaskAssigner, AssigneeType
    from canvas_sdk.v1.data.task import TaskPriority
    from datetime import date
    TaskCommand(
        title="Follow-up appointment scheduling",
        assign_to=TaskAssigner(to=AssigneeType.STAFF, id=123),
        due_date=date(2024, 12, 15),
        priority=TaskPriority.URGENT,
        comment="Ensure the patient schedules a follow-up within 30 days.",
        labels=["Urgent"],
        linked_items_urns=["urn:task:123", "urn:note:456"]
    )
    ```
* * *
###  UncategorizedDocumentReview 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`report_ids`|  _list[string]_| `true`| List of [UncategorizedClinicalDocument](/sdk/data-uncategorized-clinical-document/#uncategorizedclinicaldocument) ids to review. Must be documents already on that patient's chart.  
`message_to_patient`|  _string_| `false`| Message to communicate findings to the patient.  
`communication_method`|  _ReportReviewCommunicationMethod enum_| `false`| Method for patient communication. Must be one of `ReportReviewCommunicationMethod`.  
`linked_items_urns`|  _list[string]_| `false`| List of URNs for items linked to the review.  
`comment`|  _string_| `false`| Internal comment about the review.  
**Example** :
    ```python
    from canvas_sdk.commands import UncategorizedDocumentReviewCommand
    from canvas_sdk.v1.data import UncategorizedClinicalDocument, Patient
    from canvas_sdk.commands.commands.review import ReportReviewCommunicationMethod
    patient = Patient.objects.last()
    # Get uncategorized documents to review
    uncategorized_documents = UncategorizedClinicalDocument.objects.filter(patient=patient, review__isnull=True, review_mode='RR')
    report_ids = [str(doc.id) for doc in uncategorized_documents]
    uncategorized_review = UncategorizedDocumentReviewCommand(
        note_uuid="a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        report_ids=report_ids,
        message_to_patient="Your document has been reviewed.",
        communication_method=ReportReviewCommunicationMethod.DELEGATED_CALL_CAN_LEAVE_MESSAGE,
        comment="Document reviewed, no further action needed."
    )
    ```
* * *
###  UpdateDiagnosis 
Replaces an existing diagnosis with a different code, carrying the original's history onto the new condition. See Updating or removing a condition for how it compares to the other condition commands.
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`condition_code`|  _string_| `true`| The ICD-10 code of the existing diagnosis to update. Must match an active [Condition](/sdk/data-condition/#condition) on that patient's chart, including encounter diagnoses recorded with Assess's `show_in_problem_list=False`.  
`new_condition_code`|  _string_| `true`| The new ICD-10 code to replace the existing diagnosis, looked up via [`GET /icd/condition/`](/sdk/utils/#get-icdcondition--icd-10-conditions).  
`background`|  _string_| `false`| Background information or notes related to the updated diagnosis (max length: 2048 characters).  
`narrative`|  _string_| `false`| A narrative or explanation about the update (max length: 2048 characters).  
* * *
**Example**
    ```python
    from canvas_sdk.commands import UpdateDiagnosisCommand
    UpdateDiagnosisCommand(
        condition_code="E119",
        new_condition_code="E109",
        background="Patient previously diagnosed with diabetes type 2; now updated to diabetes type 1.",
        narrative="Updating condition based on recent clinical findings."
    )
    ```
* * *
###  UpdateGoal 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`goal_id`|  _string_| `true`| The `id` of the [Goal](/sdk/data-goal/#goal) being updated. Must be a goal on that patient's chart.  
`due_date`|  _datetime_| `false`| The date the goal is due.  
`achievement_status`|  _AchievementStatus enum_| `false`| The current achievement status of the goal.  
`priority`|  _Priority enum_| `false`| The priority of the goal.  
`progress`|  _string_| `false`| A narrative about the patient's progress toward the goal.  
`assessment_id`|  _string_| `false`| The id (a UUID) of an [Assessment](/sdk/data-assessment/#assessment) made in the same note as this command. A cross-note reference or an unknown id is rejected on `originate` and `edit`. The link clears automatically if that Assessment is deleted or entered in error, or if [a move puts the two in different notes](/sdk/data-assessment/#commands-linked-to-an-assessment).  
`AchievementStatus`| Value| Description  
---|---|---  
`IN_PROGRESS`| `"in-progress"`| The goal is being pursued.  
`IMPROVING`| `"improving"`| Progress toward the goal is improving.  
`WORSENING`| `"worsening"`| Progress toward the goal is worsening.  
`NO_CHANGE`| `"no-change"`| No change in progress toward the goal.  
`ACHIEVED`| `"achieved"`| The goal has been achieved.  
`SUSTAINING`| `"sustaining"`| The achieved goal is being sustained.  
`NOT_ACHIEVED`| `"not-achieved"`| The goal was not achieved.  
`NO_PROGRESS`| `"no-progress"`| No progress has been made toward the goal.  
`NOT_ATTAINABLE`| `"not-attainable"`| The goal is not attainable.  
`Priority`| Value| Description  
---|---|---  
`HIGH`| `"high-priority"`| High priority.  
`MEDIUM`| `"medium-priority"`| Medium priority.  
`LOW`| `"low-priority"`| Low priority.  
**Example** :
    ```python
    from canvas_sdk.commands import UpdateGoalCommand, GoalCommand
    from datetime import datetime
    update_goal = UpdateGoalCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        goal_id='b7c8d9e0-1a2b-4c3d-5e6f-7a8b9c0d1e2f',
        due_date=datetime(2025, 3, 31),
        achievement_status=GoalCommand.AchievementStatus.WORSENING,
        priority=GoalCommand.Priority.MEDIUM,
        progress='patient has slowed down progress and requesting to move due date out'
    )
    ```
* * *
###  VisualExamFinding 
Records a titled image of a clinical observation, with a narrative, on a note. The Visual Exam Finding command must be enabled on the instance to attach an image.
**Command-specific parameters** :
Name| Type| Description  
---|---|---  
`title`|  _string_|  The title of the finding. Up to 255 characters.  
`narrative`|  _string_|  A description of the observation.  
`image_upload_key`|  _string_|  The upload key of a PNG or JPEG image, from a SimpleAPI route declared with `file_uploads="stored"`. See [Storing uploaded files](/sdk/handlers-simple-api-http/#storing-uploaded-files). Canvas copies the file to the finding and then deletes the upload, so each key works only once. A key of `None` attaches no image. Not allowed in a recommendation, such as one on a protocol card.  
The command supports `originate`, `edit`, `delete`, `commit`, and `enter_in_error`. To read findings, see [VisualExamFinding](/sdk/data-visual-exam-finding/).
**Example** :
    ```python
    from canvas_sdk.commands import VisualExamFindingCommand
    finding = VisualExamFindingCommand(
        note_uuid='8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47',
        title='Rash',
        narrative='Erythematous rash on the left forearm',
        image_upload_key='acme/plugin-uploads/my_plugin/20261014T120000Z-abc-rash.jpg',
    )
    effect = finding.originate()
    ```
In a SimpleAPI handler, set `image_upload_key` to the `key` of the uploaded `StoredFilePart` rather than a literal string.
**Example with an uploaded photo** :
This SimpleAPI route adds a Visual Exam Finding to a note from a `multipart/form-data` request that carries the note's id, a title, a narrative, and the photo. The route uses the [API key mixin](/sdk/handlers-simple-api-http/#api-key-1), so declare the `simpleapi-api-key` secret in your manifest and set it on your instance:
    ```python
    from http import HTTPStatus
    from canvas_sdk.commands import VisualExamFindingCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPI, api
    class VisualExamFindingAPI(APIKeyAuthMixin, SimpleAPI):
        @api.post("/visual-exam-finding", file_uploads="stored")
        def visual_exam_finding(self) -> list[Response | Effect]:
            form = self.request.form_data()
            image = form["image"]
            if image.error:
                return [JSONResponse({"error": "upload failed"}, status_code=HTTPStatus.BAD_GATEWAY)]
            finding = VisualExamFindingCommand(
                note_uuid=form["note_id"].value,
                title=form["title"].value,
                narrative=form["narrative"].value,
                image_upload_key=image.key,
            )
            return [finding.originate(), JSONResponse({}, status_code=HTTPStatus.ACCEPTED)]
    ```
Call the route with a `multipart/form-data` POST, sending the photo as a file and the API key in the `Authorization` header:
    ```shell
    curl --request POST \
         --url 'https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/visual-exam-finding' \
         --header 'Authorization: <api-key>' \
         --form 'note_id=8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47' \
         --form 'title=Rash' \
         --form 'narrative=Erythematous rash on the left forearm' \
         --form 'image=@rash.jpg;type=image/jpeg'
    ```
The same request from a Python script, uploading a photo saved on disk, using the [`requests`](https://requests.readthedocs.io/) library:
    ```python
    from pathlib import Path
    import requests
    url = "https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/visual-exam-finding"
    image_path = Path("rash.jpg")
    with image_path.open("rb") as image:
        response = requests.post(
            url,
            headers={"Authorization": "<api-key>"},
            data={
                "note_id": "8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
                "title": "Rash",
                "narrative": "Erythematous rash on the left forearm",
            },
            files={"image": (image_path.name, image, "image/jpeg")},
            timeout=30,
        )
    print(response.status_code)
    ```
* * *
###  Vitals 
**Command-specific parameters** :
Name| Type| Required to commit| Description  
---|---|---|---  
`height`|  _integer_| `false`| Height in inches.  
`weight_lbs`|  _integer_| `false`| Weight in pounds.  
`weight_oz`|  _integer_| `false`| Weight in ounces.  
`waist_circumference`|  _integer_| `false`| Waist circumference in inches.  
`body_temperature`|  _float_| `false`| Body temperature in Fahrenheit.  
`body_temperature_site`|  _BodyTemperatureSite_| `false`| Site of body temperature measurement.  
`blood_pressure_systole`|  _integer_| `false`| Systolic blood pressure.  
`blood_pressure_diastole`|  _integer_| `false`| Diastolic blood pressure.  
`blood_pressure_position_and_site`|  _BloodPressureSite_| `false`| Position and site of blood pressure measurement.  
`pulse`|  _integer_| `false`| Pulse rate in beats per minute.  
`pulse_rhythm`|  _PulseRhythm_| `false`| Rhythm of the pulse.  
`respiration_rate`|  _integer_| `false`| Respiration rate in breaths per minute.  
`oxygen_saturation`|  _integer_| `false`| Oxygen saturation in percentage.  
`supplemental_oxygen`|  _SupplementalOxygen_| `false`| Type of supplemental oxygen the patient is receiving.  
`note`|  _string_| `false`| Additional notes (max length: 150 characters).  
For an example of how weight (`weight_lbs` / `weight_oz`) and other vitals values are stored and read back via the SDK, see the [vitals visualizer](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/vitals_visualizer_plugin) example plugin, which retrieves a patient's weight and displays it in a side modal.
**Enums and Types** :
BodyTemperatureSite| Value| Description  
---|---|---  
`AXILLARY`| `0`| Measurement taken from the armpit.  
`ORAL`| `1`| Measurement taken from the mouth.  
`RECTAL`| `2`| Measurement taken from the rectum.  
`TEMPORAL`| `3`| Measurement taken from the forehead.  
`TYMPANIC`| `4`| Measurement taken from the ear.  
BloodPressureSite| Value| Description  
---|---|---  
`SITTING_RIGHT_UPPER`| `0`| Sitting position, right upper arm.  
`SITTING_LEFT_UPPER`| `1`| Sitting position, left upper arm.  
`STANDING_RIGHT_UPPER`| `4`| Standing position, right upper arm.  
`SUPINE_LEFT_LOWER`| `11`| Supine position, left lower arm.  
PulseRhythm| Value| Description  
---|---|---  
`REGULAR`| `0`| Regular rhythm.  
`IRREGULARLY_IRREGULAR`| `1`| Completely irregular rhythm.  
`REGULARLY_IRREGULAR`| `2`| Regularly irregular rhythm.  
SupplementalOxygen| Value| Description  
---|---|---  
`CONTINUOUS_HIGH_FLOW`| `"LA28684-1"`| Continuous high-flow supplemental oxygen.  
`CONTINUOUS_LOW_FLOW`| `"LA28685-8"`| Continuous low-flow supplemental oxygen.  
`INTERMITTENT`| `"LA28686-6"`| Intermittent supplemental oxygen.  
**Example** :
    ```python
    from canvas_sdk.commands import VitalsCommand
    VitalsCommand(
        height=70,
        weight_lbs=150,
        body_temperature=98,
        body_temperature_site=VitalsCommand.BodyTemperatureSite.ORAL,
        blood_pressure_systole=120,
        blood_pressure_diastole=80,
        blood_pressure_position_and_site=VitalsCommand.BloodPressureSite.SITTING_RIGHT_UPPER,
        pulse=72,
        pulse_rhythm=VitalsCommand.PulseRhythm.REGULAR,
        oxygen_saturation=98,
        supplemental_oxygen=VitalsCommand.SupplementalOxygen.INTERMITTENT,
        note="Vitals are within normal range."
    )
    ```
##  Command Constants 
The `canvas_sdk.commands.constants` module provides essential classes and enumerations used across various Canvas SDK command implementations. These constants ensure consistency and provide structured data types for common medical and administrative elements.
###  ClinicalQuantity 
`ClinicalQuantity` represents detailed information about the form or unit of medication, particularly for prescription-related commands.
Field Name| Type| Required| Description  
---|---|---|---  
`representative_ndc`|  _string_| `true`| National Drug Code (NDC) representing the medication.  
`ncpdp_quantity_qualifier_code`|  _string_| `true`| NCPDP code indicating the quantity qualifier.  
`description`|  _string_| `false`| The clinical quantity description to dispense (e.g. `"0.5 mL vial"`). Use this field to narrow the selection to the correct clinical quantity when multiple options are available for the same NDC and qualifier code. If omitted, the first available clinical quantity is used.  
These values come from the `clinical_quantities` array returned by the [medication search](/sdk/utils/#searching-for-medications): `representative_ndc` ← `representative_ndc`, `ncpdp_quantity_qualifier_code` ← `erx_ncpdp_script_quantity_qualifier_code`, and `description` ← `clinical_quantity_description`.
**Usage Example** :
    ```python
    from canvas_sdk.commands import PrescribeCommand
    from canvas_sdk.commands.constants import ClinicalQuantity
    # Without description — selects the first available clinical quantity
    clinical_quantity = ClinicalQuantity(
        representative_ndc="12843016128",
        ncpdp_quantity_qualifier_code="C48542"
    )
    # With description — narrows to the correct clinical quantity when multiple options share the same NDC and qualifier code
    clinical_quantity = ClinicalQuantity(
        representative_ndc="00002024304",
        ncpdp_quantity_qualifier_code="C28254",
        description="0.5 mL vial"
    )
    prescribe = PrescribeCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        fdb_code="216092",
        icd10_codes=["R51"],
        sig="Take one tablet daily after meals",
        days_supply=30,
        quantity_to_dispense=30,
        type_to_dispense=clinical_quantity,
        refills=3,
        substitutions=PrescribeCommand.Substitutions.ALLOWED
    )
    ```
**Looking up`representative_ndc` and `ncpdp_quantity_qualifier_code`:** When a Prescribe command uses an `fdb_code`, `type_to_dispense` requires a `ClinicalQuantity` with both `representative_ndc` and `ncpdp_quantity_qualifier_code`. You can obtain these values from the [ontologies service](/sdk/utils/#making-requests-to-the-ontologies-service). The FDB code is the `med_medication_id` returned by a medication search; query the grouped-medication endpoint directly by that ID to read its clinical quantities:
    ```python
    from canvas_sdk.utils.http import ontologies_http
    med_medication_id = 436095  # this is the fdb_code
    response_json = ontologies_http.get_json(f"/fdb/grouped-medication/{med_medication_id}/").json()
    ```
A single FDB code can contain multiple `clinical_quantities`, so filter to the correct one by matching its `clinical_quantity_description` to your medication's form. The fields map to `ClinicalQuantity` as follows: `representative_ndc` → `representative_ndc`, and `erx_ncpdp_script_quantity_qualifier_code` → `ncpdp_quantity_qualifier_code`.
###  ServiceProvider 
`ServiceProvider` represents detailed information about healthcare service providers, used in referral, imaging order, and Order DME commands.
Field Name| Type| Description  
---|---|---  
`first_name`|  _string_|  Service provider's first name (max length 512)  
`last_name`|  _string_|  Service provider's last name (max length 512)  
`specialty`|  _string_|  Provider's specialty (max length 512)  
`practice_name`|  _string_|  Name of the practice (max length 512)  
`business_fax`|  _Optional[string]_|  Business fax number (optional, max length 512)  
`business_phone`|  _Optional[string]_|  Business phone number (optional, max length 512)  
`business_address`|  _Optional[string]_|  Business address (optional, max length 512)  
`notes`|  _Optional[string]_|  Additional notes (optional, max length 512)  
**Usage Example** :
    ```python
    from canvas_sdk.commands import ReferCommand
    from canvas_sdk.commands.constants import ServiceProvider
    # Creating a referral with service provider information
    service_provider = ServiceProvider(
        first_name="John",
        last_name="Smith",
        specialty="Cardiology",
        practice_name="Heart Health Center",
        business_phone="555-0123",
        business_address="123 Medical Plaza, Suite 100"
    )
    refer = ReferCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        diagnosis_codes=["E119"],
        priority=ReferCommand.Priority.ROUTINE,
        clinical_question=ReferCommand.ClinicalQuestion.DIAGNOSTIC_UNCERTAINTY,
        notes_to_specialist="Patient needs cardiac evaluation",
        service_provider=service_provider
    )
    ```
###  CodeSystems 
`CodeSystems` provides standardized medical coding system identifiers used throughout Canvas for consistent medical code classification.
**Available Code Systems** :
Code System| System URI| Description  
---|---|---  
`SNOMED`| `http://snomed.info/sct`| Systematized Nomenclature of Medicine Clinical Terms  
`RXNORM`| `http://www.nlm.nih.gov/research/umls/rxnorm`| RxNorm — standardized nomenclature for medications  
`LOINC`| `http://loinc.org`| Logical Observation Identifiers Names and Codes (labs/observations)  
`FDB`| `http://www.fdbhealth.com/`| First Databank drug knowledge base  
`ICD10`| `ICD-10`| International Classification of Diseases, 10th Revision  
`CVX`| `http://hl7.org/fhir/sid/cvx`| CDC codes for administered vaccines  
`CPT`| `http://www.ama-assn.org/go/cpt`| Current Procedural Terminology (AMA procedure codes)  
`NUCC`| `http://www.nucc.org/`| National Uniform Claim Committee provider taxonomy codes  
`NDC`| `http://hl7.org/fhir/sid/ndc`| National Drug Code  
`HCPCS`| `http://www.cms.gov/medicare/coding/medhcpcsgeninfo`| Healthcare Common Procedure Coding System  
`UNITS_OF_MEASURE`| `http://unitsofmeasure.org`| Unified Code for Units of Measure (UCUM)  
`FULLSCRIPT`| `http://fullscript.com`| Fullscript supplement/dispensary code system  
`UNSTRUCTURED`| `UNSTRUCTURED`| Canvas-specific system for unstructured or custom codes  
**Usage Example** :
    ```python
    from canvas_sdk.commands.constants import CodeSystems, Coding
    # Using different code systems
    icd10_coding = Coding(
        system=CodeSystems.ICD10,
        code="E11.9",
        display="Type 2 diabetes mellitus without complications"
    )
    snomed_coding = Coding(
        system=CodeSystems.SNOMED,
        code="65921008",
        display="Drink plenty of fluids"
    )
    unstructured_coding = Coding(
        system=CodeSystems.UNSTRUCTURED,
        code="Custom instruction text"
    )
    ```
###  Coding 
`Coding` represents a coded value from a medical terminology system, providing structured representation of medical concepts.
Field Name| Type| Description  
---|---|---  
`system`|  _string_|  The coding system identifier (e.g., ICD-10, SNOMED)  
`code`|  _string_|  The specific code within the system  
`display`|  _Optional[string]_|  Human-readable description of the code  
**Usage Example** :
    ```python
    from canvas_sdk.commands import InstructCommand
    from canvas_sdk.commands.constants import CodeSystems, Coding
    # Using structured coding with SNOMED
    instruct_snomed = InstructCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        coding=Coding(
            system=CodeSystems.SNOMED,
            code="65921008",
            display="Drink plenty of fluids"
        ),
        comment="To address mild dehydration symptoms"
    )
    # Using unstructured coding for custom instructions
    instruct_custom = InstructCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        coding=Coding(
            system=CodeSystems.UNSTRUCTURED,
            code="Physical medicine neuromuscular training"
        )
    )
    ```
###  ReportReviewCommunicationMethod 
The `communication_method` value shared by the review commands — ImagingReview, LabReview, ReferralReview, and UncategorizedDocumentReview.
    ```python
    from canvas_sdk.commands.commands.review import ReportReviewCommunicationMethod
    ```
Communication Method| Value| Description  
---|---|---  
`DELEGATED_CALL_CAN_LEAVE_MESSAGE`| `"DM"`| Delegated call - can leave message  
`DELEGATED_CALL_NEED_ANSWER`| `"DA"`| Delegated call - need answer  
`DELEGATED_LETTER`| `"DL"`| Delegated letter to be sent to patient  
`ALREADY_LEFT_MESSAGE`| `"AM"`| Already left message for patient  
`ALREADY_REVIEWED_WITH_PATIENT`| `"AR"`| Already reviewed with patient  

---

# Provider Companion

Source: https://docs.canvasmedical.com/sdk/companion/

The **Provider Companion** is a mobile-optimized, provider-facing web app that runs alongside Canvas. It's designed for the phone-in-hand moments in a clinician's day — looking something up between rooms, triaging a message list, checking in on a patient's tasks — rather than the sit-down charting workflows the desktop app covers.
Your plugins can contribute applications to the companion just like they do to the desktop. This page covers how plugins integrate, the three companion-specific application scopes, and how to share code when you want the same plugin to work across multiple scopes.
##  Accessing the companion 
The companion lives at `/companion/` on your Canvas instance:
    ```text
    https://<instance>.canvasmedical.com/companion/
    ```
Any staff user who can log in to the desktop Canvas app can log in to the companion with the same credentials. Patients don't have access — it's a provider surface only.
##  How plugins extend the companion 
Canvas plugins contribute embedded apps through the `Application` handler — a Python class with an `on_open()` method that returns a URL for Canvas to iframe into its UI. Which surface your app appears on is controlled by the `scope` value in your plugin's [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#applications). Companion apps work exactly the same way; they just use one of three companion-specific `scope` values. If you haven't built an embedded app before, start with the [Applications](/sdk/handlers-applications/) page — this page assumes you know the basics and focuses on what's companion-specific.
There are three companion scopes:
Scope| Where the app shows up  
---|---  
`provider_companion_global`| Icon in the app launcher on the companion's main page, outside of any patient context  
`provider_companion_patient_specific`| Tab on the patient page, next to the built-in Timeline tab  
`provider_companion_note_specific`| Tab within an opened note on the patient page  
When a user opens your app, Canvas fires an `APPLICATION__ON_OPEN` event and your handler's `on_open()` runs. Return a `LaunchModalEffect` pointing at whatever URL you want embedded — typically a page served by a SimpleAPI handler in the same plugin.
##  `provider_companion_global`
Global-scope apps appear in the companion's launcher on the main page. They run with no patient or note context — they're the right surface for workflows that span many patients, or administrative work that isn't tied to a chart.
![](/assets/images/sdk/companion/companion-global.png) ![](/assets/images/sdk/companion/global-app.png)
###  Event context 
`self.event.context` contains the acting user but no patient or note keys.
###  Use cases 
  - A **task queue** showing every task assigned to the logged-in provider across all patients.
  - A **schedule viewer** for the day's appointments.
  - A **secure chat** for the care team.
  - An **administrative dashboard** — e.g. open lab orders awaiting review.
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class TaskDashboardGlobal(Application):
        """Companion global app — every task for the logged-in provider."""
        def on_open(self) -> Effect:
            return LaunchModalEffect(
                url="/plugin-io/api/task_dashboard/app/tasks",
                target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
            ).apply()
    ```
`CANVAS_MANIFEST.json`:
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "0.0.1",
      "name": "task_dashboard",
      "description": "A task dashboard for the provider companion.",
      "components": {
        "applications": [
          {
            "class": "task_dashboard.applications.global_app:TaskDashboardGlobal",
            "name": "Tasks",
            "description": "All tasks assigned to me.",
            "scope": "provider_companion_global",
            "icon": "assets/tasks.png"
          }
        ],
        "handlers": [
          {
            "class": "task_dashboard.handlers.api:TaskDashboardAPI",
            "description": "Serves the task dashboard page the iframe loads."
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
The `TaskDashboardAPI` class is the [SimpleAPI handler](/sdk/handlers-simple-api/) that actually serves the page `on_open` iframes. `on_open` only returns the launch effect; the page itself has to be served by something, and that something is a SimpleAPI handler registered here.
##  `provider_companion_patient_specific`
Patient-scope apps appear as tabs on the patient page. Your tab sits next to the built-in Timeline tab, and when the user taps it, your handler's `on_open()` fires with the patient in `event.context`.
![](/assets/images/sdk/companion/patient-timeline.png) ![](/assets/images/sdk/companion/patient-app.png)
###  Event context 
    ```python
    self.event.context["patient"]["id"]  # Patient id (UUID string)
    ```
###  Use cases 
  - A **chart summary** of conditions, meds, allergies, vitals, etc. for the open patient.
  - A **risk-score panel** tied to the patient.
  - A **care-plan checklist** for this patient's current programs.
  - A **patient-scoped task list** — the same tasks view as the global app, but filtered to just this patient's tasks.
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class TaskDashboardPatient(Application):
        """Companion patient app — tasks filtered to one patient."""
        def on_open(self) -> Effect:
            patient_id = self.event.context.get("patient", {}).get("id", "")
            return LaunchModalEffect(
                url=f"/plugin-io/api/task_dashboard/app/tasks?patient_id={patient_id}",
                target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
            ).apply()
    ```
`CANVAS_MANIFEST.json`:
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "0.0.1",
      "name": "task_dashboard",
      "description": "A patient-scoped task dashboard for the provider companion.",
      "components": {
        "applications": [
          {
            "class": "task_dashboard.applications.patient_app:TaskDashboardPatient",
            "name": "Tasks",
            "description": "Tasks for this patient.",
            "scope": "provider_companion_patient_specific",
            "icon": "assets/tasks.png"
          }
        ],
        "handlers": [
          {
            "class": "task_dashboard.handlers.api:TaskDashboardAPI",
            "description": "Serves the task dashboard page the iframe loads."
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
##  `provider_companion_note_specific`
Note-scope apps appear as tabs inside an opened note on the patient page. Use these for workflows scoped to a single encounter. Both the patient and the note are passed in the event context.
![](/assets/images/sdk/companion/note.png) ![](/assets/images/sdk/companion/note-app.png)
###  Event context 
    ```python
    self.event.context["patient"]["id"]  # Patient id (UUID string)
    self.event.context["note"]["id"]     # Note UUID
    ```
###  Use cases 
  - A **documentation assistant** that reads the note's commands and suggests improvements.
  - A **coding / billing helper** that computes E&M level from the note's content.
  - A **visit-specific questionnaire** the provider fills out per encounter.
  - An **inline scribe** that writes note content from dictation or an LLM.
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class ScribeAssistant(Application):
        """Companion note app — inline scribe for the open note."""
        def on_open(self) -> Effect:
            patient_id = self.event.context.get("patient", {}).get("id", "")
            note_id = self.event.context.get("note", {}).get("id", "")
            return LaunchModalEffect(
                url=(
                    f"/plugin-io/api/scribe/app/compose"
                    f"?patient_id={patient_id}&note_id={note_id}"
                ),
                target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
            ).apply()
    ```
`CANVAS_MANIFEST.json`:
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "0.0.1",
      "name": "scribe",
      "description": "Inline scribe for the provider companion.",
      "components": {
        "applications": [
          {
            "class": "scribe.applications.note_app:ScribeAssistant",
            "name": "Scribe",
            "description": "Inline scribe for this note.",
            "scope": "provider_companion_note_specific",
            "icon": "assets/scribe.png"
          }
        ],
        "handlers": [
          {
            "class": "scribe.handlers.api:ScribeAPI",
            "description": "Serves the scribe page the iframe loads."
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
###  Originating commands on the note 
The note scope's real payoff is that your app can contribute to the note it's running in. Take the `note_uuid` from the event context, build an SDK command with it, and return the command's `originate()` effect alongside your JSON response — the platform will materialize the command in the note after your handler returns.
    ```python
    from http import HTTPStatus
    from canvas_sdk.commands.commands.vitals import VitalsCommand
    from canvas_sdk.effects.simple_api import JSONResponse
    from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin, api
    class VitalsEntryAPI(StaffSessionAuthMixin, SimpleAPI):
        PREFIX = "/app"
        @api.post("/vitals")
        def submit(self):
            note_id = self.request.query_params.get("note_id", "")
            body = self.request.json() or {}
            command = VitalsCommand(
                note_uuid=note_id,
                blood_pressure_systole=body.get("bp_sys"),
                blood_pressure_diastole=body.get("bp_dia"),
                pulse=body.get("pulse"),
            )
            return [
                command.originate(),
                JSONResponse(
                    {"status": "submitted"},
                    status_code=HTTPStatus.ACCEPTED,
                ),
            ]
    ```
The Application passes `note_id` through to the iframe on the launch URL's query string; the iframe sends it along on the POST to `/vitals`. The same pattern works for any SDK command that exposes an `originate()` method — assessments, prescriptions, lab orders, imaging orders, etc.
**Attribution is the plugin author's responsibility.** Commands don't carry an explicit originator field; the platform attributes them to whoever the authenticated session belongs to when the effect is applied. The [`StaffSessionAuthMixin`](/sdk/handlers-simple-api-http/#staff-session) on the handler above ensures the request is gated on a logged-in staff session, so the originated command is attributed to that staff user rather than a generic plugin service identity. If your handler doesn't enforce a staff session, commands it originates won't be tied to the provider using the app — gate every command-originating route with `StaffSessionAuthMixin` (or a stricter equivalent).
##  Sharing code across scopes 
You don't need a separate plugin per scope — a single plugin can register several applications, all backed by the same SimpleAPI handler and the same UI bundle. The Application subclasses differ only in which scope they declare and what they put in the launch URL's query string; the shared handler branches on what it receives.
The task dashboard is a natural example. The global view and the patient-scoped view show the same UI — a list of task cards — but one shows every task assigned to the provider and the other shows only tasks tied to the open patient. They can share everything except the scope declaration and one query-string parameter.
###  Manifest — two applications, one handler 
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "0.0.1",
      "name": "task_dashboard",
      "description": "Task dashboard — global and patient-scoped from one codebase.",
      "components": {
        "applications": [
          {
            "class": "task_dashboard.applications.global_app:TaskDashboardGlobal",
            "name": "Tasks",
            "description": "All tasks assigned to me.",
            "scope": "provider_companion_global",
            "icon": "assets/tasks.png"
          },
          {
            "class": "task_dashboard.applications.patient_app:TaskDashboardPatient",
            "name": "Tasks",
            "description": "Tasks for this patient.",
            "scope": "provider_companion_patient_specific",
            "icon": "assets/tasks.png"
          }
        ],
        "handlers": [
          {
            "class": "task_dashboard.handlers.api:TaskDashboardAPI",
            "description": "Serves the task dashboard page and JSON bundle."
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
###  Shared SimpleAPI handler 
The handler serves the same HTML for both scopes and branches on `patient_id` in its data endpoint: present → filter to that patient, absent → return the provider's entire task queue.
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects.simple_api import HTMLResponse, JSONResponse
    from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin, api
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data.task import Task
    class TaskDashboardAPI(StaffSessionAuthMixin, SimpleAPI):
        PREFIX = "/app"
        @api.get("/tasks")
        def page(self):
            return [HTMLResponse(
                render_to_string("static/tasks.html"),
                status_code=HTTPStatus.OK,
            )]
        @api.get("/tasks/data.json")
        def data(self):
            user_id = self.request.headers["canvas-logged-in-user-id"]
            patient_id = self.request.query_params.get("patient_id")
            tasks = Task.objects.filter(assigned_to_id=user_id)
            if patient_id:
                tasks = tasks.filter(patient__key=patient_id)
            return [JSONResponse(
                {"tasks": [serialize(t) for t in tasks]},
                status_code=HTTPStatus.OK,
            )]
    ```
The HTML/JS bundle (served by `/app/tasks`) fetches `/app/tasks/data.json` relative to its own URL, so it gets the right slice of tasks without knowing which scope launched it — the scope is encoded in whether the Application handler appended `?patient_id=...` to the launch URL.
This pattern generalizes: any time the _same UI_ works on a filtered or unfiltered dataset, you can register one Application per scope and share the handler, templates, and client-side code underneath.
##  Dismissing your modal 
Shortly after your iframe loads, Canvas transfers a `MessagePort` to it via a `postMessage` event. The plugin stores that port and posts `{type: 'CLOSE_MODAL'}` through it whenever it wants to dismiss itself — typically right after a successful form submit, or from a Cancel button.
    ```javascript
    let messagePort = null;
    window.addEventListener('message', (event) => {
        if (event.data?.type === 'INIT_CHANNEL' && event.ports?.[0]) {
            messagePort = event.ports[0];
            messagePort.start();
        }
    });
    function closeModal() {
        if (messagePort) {
            messagePort.postMessage({ type: 'CLOSE_MODAL' });
        } else {
            window.close();  // fallback if the port never arrived
        }
    }
    ```
Register the `message` listener at module scope, not inside a `DOMContentLoaded` handler — the port can arrive before your DOM is ready, and a listener attached later will miss it.
##  Async effects from SimpleAPI handlers 
Effects returned from a SimpleAPI route execute **after** the handler returns — they're dispatched to a platform worker, not applied inside your handler's transaction. That means you can't emit e.g. `Patient(...).create()` and then query for the new patient in the same request — the effect hasn't been processed yet and the record doesn't exist.
If you need the new record's UUID (for example to deep-link to it), do the lookup on a follow-up request from the iframe. The simplest shape: `POST /create` emits the effect and returns `202 Accepted` with everything needed to identify the new record; the iframe polls a separate `GET /find` endpoint until the record appears (or a short timeout fires).
    ```python
    import datetime
    from http import HTTPStatus
    from canvas_sdk.effects.patient import Patient as PatientEffect
    from canvas_sdk.effects.simple_api import JSONResponse
    from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin, api
    from canvas_sdk.v1.data.patient import Patient
    class RegisterPatientAPI(StaffSessionAuthMixin, SimpleAPI):
        PREFIX = "/app"
        @api.post("/create")
        def create(self):
            body = self.request.json() or {}
            # ... validate the submission ...
            effect = PatientEffect(
                first_name=body["first_name"],
                last_name=body["last_name"],
                birthdate=body["birth_date"],
            ).create()
            return [
                effect,
                JSONResponse({
                    "status": "submitted",
                    "lookup_params": {
                        "first_name": body["first_name"],
                        "last_name": body["last_name"],
                        "birth_date": body["birth_date"],
                    },
                    "lookup_started_at":
                        datetime.datetime.now(datetime.timezone.utc).isoformat(),
                }, status_code=HTTPStatus.ACCEPTED),
            ]
        @api.get("/find")
        def find(self):
            params = self.request.query_params
            found = (
                Patient.objects
                .filter(
                    first_name=params["first_name"],
                    last_name=params["last_name"],
                    birth_date=params["birth_date"],
                    created__gte=params["after"],
                )
                .order_by("-created")
                .first()
            )
            return [JSONResponse(
                {"patient_id": str(found.id) if found else None},
                status_code=HTTPStatus.OK,
            )]
    ```
On the iframe, poll `/find` at ~500 ms intervals for ~5 s. On the first hit, deep-link to the new record. On timeout, surface a clear error message — the effect failed and there's nothing to link to. Don't claim success before the lookup confirms the record exists.
##  Common patterns 
The conventions are the same as any other SDK application — the companion just chooses where and when to render your iframe.
  - **Serve your UI from a[SimpleAPI handler](/sdk/handlers-simple-api/)** in the same plugin. `on_open()` returns a `LaunchModalEffect` pointing at a URL like `/plugin-io/api/<plugin_name>/...`.
  - **Authenticate with[`StaffSessionAuthMixin`](/sdk/handlers-simple-api-http/#staff-session).** The companion is staff-only, so every request hitting your plugin's SimpleAPI should be gated on a valid staff session. Mix the class in instead of writing your own `authenticate()` — it rejects non-staff sessions (including patient-portal sessions) up front:
        ```python
        from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin
        class TaskDashboardAPI(StaffSessionAuthMixin, SimpleAPI):
            PREFIX = "/app"
            # ... routes ...
        ```
The logged-in user is then available via `self.request.headers["canvas-logged-in-user-id"]`.
  - **Push live updates with a plugin-owned WebSocket.** If your app needs to stay in sync when data changes, add a `BaseHandler` that listens for the relevant domain events and broadcasts on a channel the iframe subscribes to. See [WebSocket API](/sdk/handlers-simple-api-websocket/) for the handler shape and authentication flow.
  - **Keep it mobile-first.** The companion runs on phones. System fonts, stacked sections, generous tap targets, no hover interactions — your app should feel native inside the companion's shell.
  - **Drop your own top chrome in patient and note scope.** The companion harness already renders the patient's name (and, in note scope, the note type and date) above your iframe. If your plugin also renders a title bar, the result is a doubled-up header. Suppress the iframe's header when running in patient or note scope — either branch in your Application and pass a hint through the launch URL, or scope the CSS on a body class your shell sets from the query string.
  - **Link out to another patient with`window.top.location`.** To navigate from inside your modal to another patient's companion view — for example, a "tap a patient name to jump there" pattern — set `window.top.location = "/companion/patient/<uuid>/"`. That tears down the iframe and replaces the parent page. Setting only the iframe's `location` leaves the modal open showing the patient page on top of whatever was behind it, which is rarely what you want.
##  Further reading 
  - [Applications](/sdk/handlers-applications/) — the base `Application` handler class, `on_open()`, and other application scopes.
  - [SimpleAPI](/sdk/handlers-simple-api/) — serving HTML and JSON from a plugin.
  - [WebSocket API](/sdk/handlers-simple-api-websocket/) — pushing live updates to an iframe.
  - [Data module](/sdk/data/) — read-only clinical data models.
  - Example plugin: [`example_provider_companion_app`](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/example_provider_companion_app) demonstrates one plugin registering apps at all three companion scopes.

---

# AttributeHubs

Source: https://docs.canvasmedical.com/sdk/custom-data-attribute-hubs/

##  Overview 
`AttributeHubs` provide a simple mechanism for storing arbitrary data that doesn't belong to existing models, or does not conform to a traditional database schema. An AttributeHub is merely a collection of named attributes with values. This approach is ideal for cross-cutting concerns that span multiple models, temporary data storage, external system state tracking, data model prototyping, or plugin-specific configuration.
**Best for:**
  - Cross-cutting state that spans multiple models (sync cursors, external IDs)
  - One-off or small-collection configuration and state
  - Data with no natural schema (varying fields per record)
  - External system state tracking
**Example use cases:**
  - API synchronization state
  - External system identifiers
  - Plugin configuration and feature flags
**Not ideal for** entities with relationships, large collections you need to search or paginate, or data requiring aggregation or reporting. See [Design Considerations](/sdk/custom-data-design-considerations/) for detailed guidance.
##  Prerequisites 
AttributeHub tables live inside your plugin's custom data namespace, so a plugin must declare a `custom_data` block in its [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#custom-data) before it can read or write hubs:
    ```json
    "custom_data": {
        "namespace": "my_org__my_plugin",
        "access": "read_write"
    }
    ```
Use `read_write` to create hubs or set attributes. `read` is enough to query hubs in a namespace that another plugin already owns.
A plugin that creates its own namespace needs no access key. Canvas generates `namespace_read_access_key` and `namespace_read_write_access_key` when the first `read_write` plugin initializes the namespace, and stores both on that plugin so you can retrieve them from the Admin UI.
A plugin joining a namespace another plugin owns declares the matching key as a variable, so that an operator can set the value at install time:
    ```json
    "variables": [
        {"name": "namespace_read_write_access_key", "sensitive": true}
    ]
    ```
Defining a [CustomModel](/sdk/custom-data-custom-models/) is optional. AttributeHubs need only the `custom_data` block, with no `models` directory. See the [Quick Start](/sdk/custom-data-quick-start/) for full namespace setup and [Namespace Lifecycle](/sdk/custom-data-namespace-lifecycle/) for how namespaces are created and shared between plugins.
> **Info:** A plugin with no `custom_data` block has no namespace, and every AttributeHub query it makes fails with `psycopg.errors.UndefinedTable: relation "attribute_hub" does not exist`.
##  Creating an AttributeHub 
Create a hub for a specific purpose using the `type` and `id` fields, which together form a unique key. There is a database constraint on these two fields to ensure uniqueness, and creating a duplicate will raise a `UniqueViolation` exception.
    ```python
    from canvas_sdk.v1.data import AttributeHub
    # Create a hub for a specific purpose
    hub = AttributeHub.objects.create(
        type="staff_profile",
        id="staff_id:abc123"
    )
    ```
##  Storing Data in AttributeHub 
Store individual attributes or complex data as JSON. Here's an example of a meal tracker that records patient meals and calories:
    ```python
    from datetime import datetime
    from canvas_sdk.v1.data import AttributeHub, Patient
    patient = Patient.objects.get(id="patient-uuid-here")
    # Create a hub to track a specific meal
    hub = AttributeHub.objects.create(
        type="meal_entry",
        id=f"patient:{patient.id}:meal:{datetime.now().isoformat()}"
    )
    # Store individual attributes
    hub.set_attribute("meal_type", "lunch")
    hub.set_attribute("calories", 650)
    hub.set_attribute("recorded_at", datetime.now())
    # Store complex data as JSON
    meal_details = {
        "foods": [
            {"name": "Grilled chicken salad", "calories": 350, "protein_g": 35},
            {"name": "Whole grain roll", "calories": 150, "protein_g": 5},
            {"name": "Apple", "calories": 95, "protein_g": 0},
            {"name": "Water", "calories": 0, "protein_g": 0}
        ],
        "notes": "Patient reported feeling satisfied after meal"
    }
    hub.set_attribute("meal_details", meal_details)
    # Store multiple attributes at once
    hub.set_attributes({
        "total_protein_g": 40,
        "meal_location": "home",
        "logged_by": "patient_self_report"
    })
    ```
##  Retrieving Data from AttributeHub 
Use the get-or-create pattern to retrieve existing hubs or create new ones:
    ```python
    from canvas_sdk.v1.data import AttributeHub, Patient
    patient = Patient.objects.get(id="patient-uuid-here")
    # Get or create a hub for tracking daily calorie totals
    hub, created = AttributeHub.objects.get_or_create(
        type="daily_calorie_summary",
        id=f"patient:{patient.id}:date:2024-01-15"
    )
    if created:
        # Initialize a new day's tracking
        hub.set_attributes({
            "total_calories": 0,
            "meal_count": 0,
            "calorie_goal": 2000
        })
    # Retrieve attributes
    total_calories = hub.get_attribute("total_calories")
    meal_count = hub.get_attribute("meal_count")
    calorie_goal = hub.get_attribute("calorie_goal")
    # Handle missing attributes gracefully
    notes = hub.get_attribute("daily_notes")  # Returns None if not set
    ```
##  Supported Value Types 
Attributes are automatically stored in appropriately typed database columns. The column is selected based on the Python type of the value you pass to `set_attribute()`:
    ```python
    from datetime import date, datetime
    from canvas_sdk.v1.data import AttributeHub
    hub = AttributeHub.objects.get(type="staff_profile", id="staff_id:abc123")
    # String values
    hub.set_attribute("bio", "Board-certified cardiologist")
    # Integer values
    hub.set_attribute("patient_capacity", 100)
    # Boolean values
    hub.set_attribute("accepting_patients", True)
    # Decimal values
    hub.set_attribute("rating", 4.8)
    # Date values
    hub.set_attribute("creation_date", date.today())
    # Datetime values
    hub.set_attribute("last_updated", datetime.now())
    # JSON/Complex objects (dicts, lists)
    hub.set_attribute("preferences", {
        "notification_email": True,
        "notification_sms": False
    })
    ```
Each attribute is a `CustomAttribute` row, and the column a value lands in is chosen from its Python type:
Field Name| Python Type| Django Field Type| PostgreSQL Data Type  
---|---|---|---  
`text_value`| `str`| `TextField`| `text`  
`int_value`| `int`| `IntegerField`| `integer`  
`bool_value`| `bool`| `BooleanField`| `boolean`  
`decimal_value`| `float`, `Decimal`| `DecimalField`| `decimal(20,10)`  
`date_value`| `date`| `DateField`| `date`  
`timestamp_value`| `datetime`| `DateTimeField`| `timestamp with time zone`  
`json_value`| `dict`, `list`| `JSONField`| `jsonb`  
These typed columns can be referenced directly in queries. See When to Use Explicit Field Names for cases where you need to target a specific column.
##  Querying AttributeHubs by Attribute Values 
Find AttributeHubs based on the values stored in their attributes using `custom_attributes__value`. The SDK automatically routes the filter to the correct typed column based on the Python type of the value you pass in:
    ```python
    from canvas_sdk.v1.data import AttributeHub
    # Find hubs with a specific string attribute
    lunch_hubs = AttributeHub.objects.filter(
        type="meal_entry",
        custom_attributes__name="meal_type",
        custom_attributes__value="lunch",
    )
    # Find hubs with a calorie count above a threshold
    high_calorie = AttributeHub.objects.filter(
        type="meal_entry",
        custom_attributes__name="calories",
        custom_attributes__value__gte=500,
    )
    # Find hubs with a boolean flag
    active_flags = AttributeHub.objects.filter(
        type="feature_flags",
        custom_attributes__name="enabled",
        custom_attributes__value=True,
    )
    ```
You can also filter attribute objects directly, for example when working with a hub's related attributes:
    ```python
    from canvas_sdk.v1.data import AttributeHub
    hub = AttributeHub.objects.get(type="meal_entry", id="patient:abc:meal:2024-01-15T12:00")
    # Filter the hub's own attributes
    high_cal_attrs = hub.custom_attributes.filter(value__gte=500)
    ```
###  When to Use Explicit Field Names 
In most cases `custom_attributes__value` (or `value` on a hub's related attributes) is sufficient. However, you must reference the typed column directly in the following cases:
  - **JSON containment queries.** PostgreSQL's `@>` containment operator on `jsonb` has different semantics from the `LIKE '%...%'` that `__contains` produces on a text column. Since `value__contains` with a string argument targets `text_value`, you must use `json_value__contains` to perform JSON containment checks:
        ```python
        from django.db.models import Q
        from canvas_sdk.v1.data import AttributeHub
        # Find hubs whose "specialties" JSON array contains "Cardiology"
        AttributeHub.objects.filter(
            type="staff_profile",
            custom_attributes__name="specialties",
            custom_attributes__json_value__contains="Cardiology",
        )
        # OR across multiple JSON values
        specialty_filters = Q()
        for specialty in ["Cardiology", "Internal Medicine"]:
            specialty_filters |= Q(custom_attributes__json_value__contains=specialty)
        AttributeHub.objects.filter(
            Q(custom_attributes__name="specialties") & specialty_filters
        )
        ```
  - **Custom JSON lookups.** Django's `JSONField` supports lookups like `__has_key`, `__contained_by`, and key-path access (`json_value__key__nested`). These are only available on the `json_value` column directly.
  - **Ambiguous Python types.** The `value` rewriter uses `type()` (not `isinstance()`) to select the column. If you pass a string but intend to query `json_value` (or vice versa), the rewriter will target the wrong column. Use the explicit field name when the Python type of your filter value doesn't match the storage column.
  - **Null checks across relations.** `custom_attributes__value=None` and `custom_attributes__value__isnull` are not supported on `AttributeHub.objects.filter(...)` and will raise `TypeError`. Null checks require testing every typed column, which produces unreliable results when combined with Django's cross-relation JOIN machinery. Use explicit column names instead:
        ```python
        from canvas_sdk.v1.data import AttributeHub
        # Check whether a specific column is null across the relation
        AttributeHub.objects.filter(
            type="staff_profile",
            custom_attributes__name="specialty",
            custom_attributes__text_value__isnull=True,
        )
        ```
Note that `value=None` and `value__isnull` _are_ supported for direct queries on a hub's own attributes (e.g., `hub.custom_attributes.filter(value__isnull=True)`), where no cross-relation join is involved.
Refer to Supported Value Types for the mapping between Python types and database columns.
##  Optimizing Queries with Prefetch 
By default, the AttributeHub manager prefetches all custom attributes when you query hubs. This means accessing `hub.get_attribute(...)` after a query does not trigger additional database queries:
    ```python
    from canvas_sdk.v1.data import AttributeHub
    # All custom attributes are prefetched automatically
    hubs = AttributeHub.objects.filter(type="meal_entry")
    for hub in hubs:
        # No additional queries — attributes are already loaded
        meal_type = hub.get_attribute("meal_type")
        calories = hub.get_attribute("calories")
    ```
###  Prefetching Specific Attributes 
When a hub has many attributes but you only need a few, use `with_only()` to prefetch only the attributes you need. This reduces the amount of data transferred from the database:
    ```python
    from canvas_sdk.v1.data import AttributeHub
    # Prefetch only the "calories" and "meal_type" attributes
    hubs = AttributeHub.objects.with_only(["calories", "meal_type"]).filter(type="meal_entry")
    for hub in hubs:
        calories = hub.get_attribute("calories")       # Loaded from prefetch cache
        meal_type = hub.get_attribute("meal_type")     # Loaded from prefetch cache
        notes = hub.get_attribute("notes")             # Falls back to a DB query (not prefetched)
    # Prefetch a single attribute
    hub = AttributeHub.objects.with_only("campaign_status").get(
        type="crm_sync", id="patient:abc123"
    )
    ```
If you access an attribute that was not included in `with_only()`, it will fall back to a database query. Use `with_only()` as an optimization, not a filter.
##  Use Case Example: CRM Campaign Sync 
Store synchronization state between a custom data model and an external CRM using AttributeHub:
    ```python
    from canvas_sdk.handlers.simple_api import SimpleAPI, api
    from canvas_sdk.effects.simple_api import JSONResponse
    from canvas_sdk.v1.data import AttributeHub, Patient
    from datetime import datetime
    class CRMSyncAPI(SimpleAPI):
        """API endpoint for syncing campaign data with external CRM."""
        PREFIX = "/crm"
        @api.post("/campaign/<campaign_id>/patient/<patient_id>")
        def sync_patient_campaign(self):
            campaign_id = self.request.path_params["campaign_id"]
            patient_id = self.request.path_params["patient_id"]
            patient = Patient.objects.get(id=patient_id)
            crm_data = self.request.json()
            # Store CRM sync state in AttributeHub
            hub, created = AttributeHub.objects.get_or_create(
                type="crm_campaign_sync",
                id=f"patient:{patient.id}:campaign:{campaign_id}"
            )
            hub.set_attributes({
                "crm_contact_id": crm_data.get("contact_id"),
                "campaign_status": crm_data.get("status"),
                "enrollment_date": crm_data.get("enrolled_at"),
                "last_synced": datetime.now(),
                "sync_direction": "crm_to_canvas"
            })
            return [JSONResponse({"status": "success", "hub_id": str(hub.id)})]
    ```
Later, retrieve the sync state when processing patient events:
    ```python
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.events import EventType
    from canvas_sdk.v1.data import AttributeHub
    class CampaignEnrollmentHandler(BaseHandler):
        """Handler that checks CRM campaign sync state for patients."""
        RESPONDS_TO = EventType.Name(EventType.PATIENT_UPDATED)
        def compute(self):
            patient_id = self.target.id
            campaign_id = "wellness_2024"  # Your campaign identifier
            # Retrieve CRM sync state from AttributeHub
            hub, created = AttributeHub.objects.get_or_create(
                type="crm_campaign_sync",
                id=f"patient:{patient_id}:campaign:{campaign_id}"
            )
            if not created:
                crm_contact_id = hub.get_attribute("crm_contact_id")
                campaign_status = hub.get_attribute("campaign_status")
                last_synced = hub.get_attribute("last_synced")
                # Use the CRM data to drive clinical workflows
                if campaign_status == "enrolled":
                    # Patient is enrolled in CRM campaign - trigger relevant protocols
                    pass
            return []
    ```
##  Best Practices 
###  Data Organization 
  1. **Use descriptive type values** \- Choose meaningful type names that describe the purpose of the hub (e.g., "external_sync", "api_cache", "feature_flags")
  2. **Use consistent ID patterns** \- Use a consistent pattern for `id` (e.g., "entity_type:entity_id")
  3. **Namespace by purpose** \- Group related data under a single hub rather than creating multiple hubs for the same entity type
###  Data Privacy and Isolation 
  1. **Understand plugin data scoping** \- All AttributeHub data is isolated to your plugin's namespace
  2. **Implement proper authorization** \- Secure all APIs that expose AttributeHub data
  3. **Follow PHI guidelines** \- Treat all patient-related data with appropriate security measures
###  Performance 
  1. **Batch attribute updates** \- Use `set_attributes()` to set multiple values at once
  2. **Cache hub lookups** \- If accessing the same hub multiple times, store the reference
###  Data Integrity 
  1. **Use get_or_create** \- Use `get_or_create()` to avoid duplicate hubs
  2. **Handle None values** \- Always check if an attribute exists before using it
  3. **Validate data** \- Validate data before storing in AttributeHub
  4. **Clean up unused data** \- Remove AttributeHub instances that are no longer needed
###  Testing 
  1. **Use get_or_create in tests** \- This pattern works well for test isolation
  2. **Isolate test data** \- Create all data required by the test, within the test
##  See Also 
  - [Custom Data Overview](/sdk/custom-data/) \- Overview of all custom data techniques
  - [Design Considerations](/sdk/custom-data-design-considerations/) \- Choosing the right technique and avoiding anti-patterns
  - [CustomModels](/sdk/custom-data-custom-models/) \- Structured models with relationships
  - [Sharing Data](/sdk/custom-data-sharing-data/) \- Sharing data among plugins
  - [Testing Custom Data](/sdk/custom-data-testing/) \- Testing utilities and examples
  - [Data Models](/sdk/data/) \- Core SDK data models
  - [Caching API](/sdk/caching) \- Auto-expiring transient data
  - [Secrets](/sdk/secrets/) \- Managing API keys and sensitive configuration

---

# CustomModels

Source: https://docs.canvasmedical.com/sdk/custom-data-custom-models/

##  Overview 
CustomModels allow you to define fully structured, typed data models with relationships among entities and normalized data. Built on Django's ORM, CustomModels provide the most powerful and flexible approach to storing custom data in Canvas plugins.
The functionality expressed is a subset of the total ORM. The SDK omits some features in order to simplify the lifecycle of plugin installation and maintenance.
**Best for:**
  - Structured data with a stable, known schema
  - Relationships between entities (foreign keys, join tables)
  - Data requiring compound filtering, sorting, or aggregation
  - Data consumed by reports or analytics
**Example use cases:**
  - Provider specialties and certifications
  - Constructing new associations among Canvas SDK models
  - Custom workflows and forms
  - Integration-specific data structures
  - Practice-specific business entities
**Not ideal for** simple metadata on existing models, highly variable or schemaless data, or ephemeral data. Tables and columns cannot be dropped once created. See [Design Considerations](/sdk/custom-data-design-considerations/) for detailed guidance.
Custom models may be associated to core SDK data models by extending them with `ModelExtension`, or may be entirely standalone. As an example, a `StaffBiography` CustomModel could attach to a `CustomStaff(Staff, ModelExtension)` class, and be accessible via a `biography` property on `CustomStaff`.
Custom models must be defined within a `models` directory under the plugin top-level directory. E.g., `/my_plugin/models/custom_model_a.py`. If not, then database migrations will not be applied. (Extended SDK models may be defined anywhere since they do not require any database modifications.)
* * *
##  Basic CustomModel 
Create a custom model by extending `CustomModel`:
    ```python
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import BooleanField, DateField, DateTimeField, DecimalField, IntegerField, JSONField, TextField
    class HealthCoach(CustomModel):
        name = TextField()
        practicing_since = IntegerField()
        version = DecimalField(default=1.0, decimal_places=1, max_digits=3)
        is_accepting_patients = BooleanField()
        created_date = DateField(auto_now_add=True)
        last_modified_at = DateTimeField(auto_now_add=True)
        extended_attributes = JSONField()
    ```
This above definition will result in a PostgreSQL table named `healthcoach`. It will have a primary key column named `dbid` of type `serial`, an auto-incrementing integer. It will have six additional columns of `text`, `integer`, `numeric(3,8)`, `boolean`, `jsonb`,`date`, and `timestamp with time zone`, respectively.
* * *
##  Schema Rules and Constraints 
To maintain safety on potentially large datasets, most constraints on CustomModels are not enforced within the database and must be enforced within plugin code.
Unsupported constraints:
  - `not null`
  - `max_length`
  - `references` (database-level foreign key constraints)
If applied to an existing dataset, these constraints could result in a full table rewrite operation, or prevent plugin installation. Note that while database-level `REFERENCES` constraints are not created, Django's ORM enforces `on_delete` behavior (`CASCADE`, `SET_NULL`, `DO_NOTHING`) at the application level — see Delete Behavior below.
Uniqueness constraints **are** supported via `UniqueConstraint` in `Meta.constraints`. See Uniqueness Constraints below.
###  Field Types 
The Canvas SDK provides Django-based field types for defining your models:
Field Type| Description| Supported Parameters  
---|---|---  
`TextField`| Variable-length text| `default`  
`IntegerField`| Integer values| `default`  
`DecimalField`| Decimal numbers| `default`, `max_digits`,`decimal_places`  
`BooleanField`| True/False values| `default`  
`DateField`| Date values| `auto_now`, `auto_now_add`, `default`  
`DateTimeField`| Date and time values| `auto_now`, `auto_now_add`, `default`  
`JSONField`| JSON-serializable data| `default`  
`ForeignKey`| Many-to-one relationship| `related_name`, `on_delete`, `to_field`  
`OneToOneField`| One-to-one relationship| `related_name`, `on_delete`, `to_field`, `primary_key`  
`ManyToManyField`| Many-to-many relationship| `through` (required), `related_name`  
If `default` is supplied it will be applied by the Django ORM, and will not be a PostgreSQL default. As a result, only new records will receive the value, and it will not cause a mass edit of existing records.
The `on_delete` parameter is required on `ForeignKey` and `OneToOneField`. It controls what happens to child records when the referenced parent record is deleted:
Value| Behavior  
---|---  
`CASCADE`| Automatically delete the child record when the parent is deleted.  
`SET_NULL`| Set the foreign key column to `NULL` when the parent is deleted. The child record is kept.  
`DO_NOTHING`| Take no action. The plugin is responsible for cleaning up or preventing orphaned references.  
These behaviors are enforced by Django's ORM at the application level. They apply when deleting via `model.delete()` or `queryset.delete()`, but not when using raw SQL.
###  Indexes 
Add indexes for frequently queried fields:
    ```python
    from canvas_sdk.v1.data.base import CustomModel
    from django.contrib.postgres.indexes import GinIndex
    from django.db.models import BooleanField, DateTimeField, Index, IntegerField, JSONField, TextField
    class ProviderQualification(CustomModel):
        first_name = TextField()
        last_name = TextField()
        board_certified = BooleanField()
        practicing_since_year = IntegerField()
        extended_attributes = JSONField()
        created_at = DateTimeField()
        class Meta:
            indexes = [
                # Single-column index
                Index(fields=["practicing_since_year"]),
                # Composite index for common search combinations
                Index(fields=["first_name", "last_name"]),
                # Descending index for ordering records
                Index(fields=["-created_at"]),
                # Gin index for efficient JSON queries
                GinIndex(fields=["extended_attributes"])
            ]
    ```
**Index Best Practices:**
  - Index fields used in `filter()` and `order_by()`
  - Create composite indexes for common multi-field queries
  - **Do not** index `ForeignKey` or `OneToOneField` columns — they are indexed automatically. The SDK will raise an error if you declare a single-column index that duplicates an auto-indexed column.
###  Uniqueness Constraints 
Use `UniqueConstraint` in `Meta.constraints` to enforce uniqueness on one or more columns. Uniqueness is enforced at the database level via a `CREATE UNIQUE INDEX`.
    ```python
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import TextField, UniqueConstraint
    class Specialty(CustomModel):
        name = TextField()
        code = TextField()
        class Meta:
            constraints = [
                UniqueConstraint(fields=["code"], name="uq_specialty_code"),
            ]
    ```
Composite uniqueness (multiple columns together must be unique):
    ```python
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import DO_NOTHING, ForeignKey, TextField, UniqueConstraint
    from canvas_sdk.v1.data import Staff, ModelExtension
    class CustomStaff(Staff, ModelExtension):
        pass
    class StaffCertification(CustomModel):
        staff = ForeignKey(CustomStaff, to_field="dbid", on_delete=DO_NOTHING, related_name="%(app_label)s__certifications")
        certification_code = TextField()
        class Meta:
            constraints = [
                UniqueConstraint(fields=["staff", "certification_code"], name="uq_staff_cert"),
            ]
    ```
Each `UniqueConstraint` requires a `name` parameter — this is a standard Django requirement. Choose a descriptive name that won't collide with other constraints in your plugin.
Use Django field names (e.g., `"staff"`) rather than database column names (e.g., `"staff_id"`) in the `fields` list — the SDK resolves field names to column names automatically. The same applies to `Index` fields in `Meta.indexes`.
**Important:** Do not use `unique=True` on individual fields. The SDK will reject it with an error directing you to use `UniqueConstraint` instead. This is because `unique=True` modifies the column definition itself, and our DDL pipeline cannot retroactively alter existing columns — meaning a `unique=True` added after the initial deployment would silently have no effect.
**Constraint placement:** `UniqueConstraint` must be placed in `Meta.constraints`, not `Meta.indexes`. Although they are structurally similar to indexes, placing a `UniqueConstraint` in `Meta.indexes` would create a non-unique index. The SDK validates this and raises an error if it detects the mistake.
**Lifecycle:** Unique indexes are created with `CREATE UNIQUE INDEX IF NOT EXISTS`, making them safe to add at any time — they are applied idempotently on every deployment. However, if the table already contains duplicate values for the constrained columns, the index creation will fail. Clean up duplicates before adding the constraint.
Operation| Allowed| Explanation  
---|---|---  
Add UniqueConstraint| Yes| A unique index will be created if it does not already exist.  
Remove UniqueConstraint| No| Remove the constraint from your model and it will be ignored, but the index will remain in the database.  
* * *
##  Creating and Querying 
###  Creating Records 
    ```python
    from my_plugin.models import ProviderQualification
    # Create and save
    qualification = ProviderQualification(
        first_name="Jessica",
        last_name="Smith",
        board_certified=True,
        practicing_since_year=2005,
        extended_attributes={ "biography": "Lives in Fresno with her..." }
    )
    qualification.save()
    # Create in one step
    qualification = ProviderQualification.objects.create(
        first_name="Jessica",
        last_name="Smith",
        board_certified=True,
        practicing_since_year=2005,
        extended_attributes={ "biography": "Lives in Fresno with her..." }
    )
    # Get or create (avoids duplicates)
    qualification = ProviderQualification.objects.get_or_create(
        first_name="Jessica",
        last_name="Smith",
        defaults={
            "board_certified": True,
            "practicing_since_year": 2005,
            "extended_attributes": { "biography": "Lives in Fresno with her..." }
        }
    )
    ```
###  Querying Records 
    ```python
    from my_plugin.models import ProviderQualification
    from datetime import date
    # Get all records
    all_qualifications = ProviderQualification.objects.all()
    # Filter records
    board_certified = ProviderQualification.objects.filter(board_certified=True)
    # Get providers with 10+ years experience
    experienced = ProviderQualification.objects.filter(
        practicing_since_year__lte=date.today().year - 10
    )
    # Get single record by database primary key
    try:
        jessica = ProviderQualification.objects.get(dbid=123)
    except ProviderQualification.DoesNotExist:
        jessica = None
    # Get single record by fields
    try:
        jessica = ProviderQualification.objects.get(first_name="Jessica", last_name="Smith")
    except ProviderQualification.DoesNotExist:
        jessica = None
    # Apply multiple filters
    senior_certified = ProviderQualification.objects.filter(
        board_certified=True,
        practicing_since_year__lte=2010  # Practicing since 2010 or earlier
    )
    # Order results
    by_experience = ProviderQualification.objects.order_by("practicing_since_year")
    # Limit results - get 5 most experienced (earliest practicing_since_year)
    top_five = ProviderQualification.objects.order_by("practicing_since_year")[:5]
    ```
###  Updating Records 
    ```python
    from my_plugin.models import ProviderQualification
    # Update single record
    qualification = ProviderQualification.objects.get(first_name="Jessica", last_name="Smith")
    qualification.practicing_since_year = 2004
    qualification.save()
    # Update multiple records
    ProviderQualification.objects.filter(
        board_certified=False
    ).update(board_certified=True)
    # Update or create
    qualification, created = ProviderQualification.objects.update_or_create(
        first_name="Michael",
        last_name="Johnson",
        defaults={
            "board_certified": True,
            "practicing_since_year": 2015,
            "extended_attributes": { "specialties": ["Cardiology", "Internal Medicine"] }
        }
    )
    ```
###  Deleting Records 
    ```python
    from my_plugin.models import ProviderQualification
    # Delete single record
    qualification = ProviderQualification.objects.get(first_name="Jessica", last_name="Smith")
    qualification.delete()
    # Delete multiple records - remove providers who started this year
    from datetime import date
    ProviderQualification.objects.filter(
        practicing_since_year=date.today().year
    ).delete()
    # Delete all records (use with caution!)
    ProviderQualification.objects.all().delete()
    ```
##  Extending the Canvas Data Model 
CustomModels may reference core SDK models by creating a proxy model with `ModelExtension`. This gives each plugin its own private handle on a shared SDK model, keeping `related_name` attributes isolated across plugins.
    ```python
    from canvas_sdk.v1.data import Staff, ModelExtension
    class CustomStaff(Staff, ModelExtension):
        pass
    ```
No new table is created — `CustomStaff` shares the `Staff` table and behaves identically for queries. Point your `ForeignKey` or `OneToOneField` at the proxy to get clean, un-namespaced reverse lookups.
For a full explanation of why proxy models exist, how `related_name` namespacing works, and how to reference SDK models directly without a proxy, see [Extending SDK Models](/sdk/custom-data-extending-sdk-models/).
* * *
##  One-to-One Relationships 
A one-to-one relationship links one record in a model to exactly one record in another model. Use `OneToOneField` to define this relationship.
###  Basic One-to-One 
    ```python
    from canvas_sdk.v1.data import Staff, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import CASCADE, DateTimeField, DecimalField, OneToOneField, TextField
    class CustomStaff(Staff, ModelExtension):
        """Extends Staff with custom attribute support."""
        pass
    class Biography(CustomModel):
        biography = TextField()
        language = TextField()
        version = DecimalField(default=1.0, decimal_places=1, max_digits=3)
        last_modified_at = DateTimeField(auto_now_add=True)
        staff = OneToOneField(
            CustomStaff, to_field="dbid", on_delete=CASCADE, related_name="biography"
        )
    ```
The above will create a table with a `serial` primary key, two `text` columns, a `numeric(1,3)` column, a `timestamptz` column, and an `integer` column named `staff_id` that contains a foreign key into the SDK `Staff` model. The `CustomStaff` class will contain the reverse mapping via `related_name`.
**Uniqueness:** A `OneToOneField` implies that the foreign key column is unique — each target record can be referenced by at most one row. The SDK automatically creates a `UNIQUE INDEX` on the foreign key column to enforce this at the database level. Do not add a separate `UniqueConstraint` for it — the SDK will raise an error if you declare a single-column `UniqueConstraint` or `Index` on an auto-indexed column.
###  One-to-One with `primary_key=True`
A `OneToOneField` can serve as the table's primary key by setting `primary_key=True`. This replaces the default auto-incrementing `dbid` column — the foreign key column becomes the sole primary key.
This pattern is useful when the child record has a strict 1:1 relationship with its parent and there is no need for a separate surrogate key.
    ```python
    from canvas_sdk.v1.data import Patient, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import CASCADE, JSONField, OneToOneField
    class CustomPatient(Patient, ModelExtension):
        pass
    class PatientPreferences(CustomModel):
        patient = OneToOneField(
            CustomPatient, to_field="dbid", on_delete=CASCADE,
            related_name="preferences", primary_key=True
        )
        preferences = JSONField(default=dict)
    ```
The above will create a table with a single `integer` primary key column `patient_id` (no `dbid` column) and a `jsonb` column. The primary key inherently enforces uniqueness, so no additional unique index is created.
**Note:** `primary_key=True` is only supported on `OneToOneField`. Setting it on a `ForeignKey` or any other field type will raise an error — use a `OneToOneField` instead when you need a shared primary key.
###  Creating One-to-One Records 
    ```python
    from my_plugin.models import CustomStaff, Biography
    # Get the staff member
    staff = CustomStaff.objects.get(id="staff-uuid")
    # Create biography
    biography = Biography.objects.create(
        staff=staff,
        biography="Dr. Smith is a board-certified cardiologist with over 20 years of experience...",
        language="English",
        version=1.0
    )
    ```
###  Querying One-to-One Relationships 
    ```python
    from my_plugin.models import CustomStaff, Biography
    # Access from biography to staff
    biography = Biography.objects.get(dbid=1)
    staff_member = biography.staff
    # Access from staff to biography (using related_name)
    staff = CustomStaff.objects.get(id="staff-uuid")
    try:
        bio = staff.biography
    except Biography.DoesNotExist:
        print("No biography found")
    # Find all staff with biographies in Spanish
    spanish_providers = CustomStaff.objects.filter(
        biography__language="Spanish"
    )
    # Find staff whose biography was last updated before a certain date
    from datetime import datetime, timedelta
    outdated_bios = CustomStaff.objects.filter(
        biography__last_modified_at__lte=datetime.now() - timedelta(days=365)
    )
    ```
* * *
##  One-to-Many Relationships 
A one-to-many (or many-to-one) relationship allows one record to be associated with multiple records in another model. Use `ForeignKey` to define this relationship.
###  Basic One-to-Many 
    ```python
    from canvas_sdk.v1.data import Staff, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import CASCADE, DateTimeField, DecimalField, ForeignKey, TextField
    class CustomStaff(Staff, ModelExtension):
      """Extends Staff with custom attribute support."""
      pass
    class Biography(CustomModel):
      biography = TextField()
      language = TextField()
      version = DecimalField(default=1.0, decimal_places=1, max_digits=3)
      last_modified_at = DateTimeField(auto_now_add=True)
      # Same as one-to-one, but a Foreign key with a plural 'related_name'. Now, each staff may have multiple biographies,
      # perhaps in different languages.
      staff = ForeignKey(
        CustomStaff, to_field="dbid", on_delete=CASCADE, related_name="biographies"
      )
    ```
###  Creating One-to-Many Records 
    ```python
    from my_plugin.models import CustomStaff, Biography
    # Get staff member
    staff = CustomStaff.objects.get(id="staff-uuid")
    # Create multiple biographies for one provider (e.g., in different languages)
    english_bio = Biography.objects.create(
        staff=staff,
        biography="Dr. Smith is a board-certified cardiologist with over 20 years of experience in interventional cardiology.",
        language="English",
        version=1.0
    )
    spanish_bio = Biography.objects.create(
        staff=staff,
        biography="La Dra. Smith es una cardióloga certificada con más de 20 años de experiencia en cardiología intervencionista.",
        language="Spanish",
        version=1.0
    )
    ```
###  Querying One-to-Many Relationships 
    ```python
    from my_plugin.models import CustomStaff, Biography
    # Access from biography to staff (forward)
    biography = Biography.objects.get(language="Spanish")
    provider = biography.staff
    print(f"Provider: {provider.first_name} {provider.last_name}")
    # Access from staff to biographies (reverse, using related_name)
    staff = CustomStaff.objects.get(id="staff-uuid")
    biographies = staff.biographies.all()
    for bio in biographies:
        print(f"- {bio.language}: {bio.biography[:50]}... (v{bio.version})")
    # Filter reverse relationship
    english_bios = staff.biographies.filter(language="English")
    # Query across relationship
    # Find all staff who have biographies in Spanish
    spanish_speaking_providers = CustomStaff.objects.filter(
        biographies__language="Spanish"
    )
    # Find staff with multiple biography versions
    from django.db.models import Count
    providers_with_multiple_bios = CustomStaff.objects.annotate(
        bio_count=Count('biographies')
    ).filter(bio_count__gt=1)
    # Count related records
    biography_count = staff.biographies.count()
    # Check existence
    has_spanish_bio = staff.biographies.filter(language="Spanish").exists()
    ```
* * *
##  Many-to-Many Relationships 
A many-to-many relationship allows multiple records in one model to be associated with multiple records in another model.
Many-to-many relationships require an **explicit through model** — a CustomModel that contains ForeignKey fields to both sides of the relationship. Standard Django allows `ManyToManyField` to create an implicit join table automatically, but the Canvas SDK does not support implicit through tables because each table must be a CustomModel with a managed schema lifecycle.
You can define the relationship in two ways:
  1. **Through model only** — Define the through model with ForeignKeys and query through it directly.
  2. **Through model +`ManyToManyField`** — Add a `ManyToManyField` with an explicit `through` parameter for cleaner ORM access.
Both approaches create the same database tables. The `ManyToManyField` adds ORM convenience (e.g., `specialty.staff.all()` instead of traversing the join table manually) but does not change the underlying schema.
###  Through Model Only 
The simplest approach is to define just the through model. This works well when the through model has additional metadata fields or when you prefer to query the join table directly.
    ```python
    from django.db.models import CASCADE, ForeignKey, Index, TextField, UniqueConstraint
    from canvas_sdk.v1.data.base import CustomModel
    from canvas_sdk.v1.data import Staff, ModelExtension
    class CustomStaff(Staff, ModelExtension):
      """Extends Staff with custom attribute support."""
      pass
    class Specialty(CustomModel):
      """Medical specialty (e.g., Cardiology, Neurology)."""
      name = TextField()
      class Meta:
        indexes = [
          Index(fields=["name"]),
        ]
    # Declaring this class will result in a join table called `staffspecialty`
    class StaffSpecialty(CustomModel):
      """Many-to-many relationship: Staff can have many specialties, specialties can have many staff."""
      staff = ForeignKey(
        CustomStaff,
        to_field="dbid",
        on_delete=CASCADE,
        related_name="staff_specialties"
      )
      specialty = ForeignKey(
        Specialty,
        to_field="dbid",
        on_delete=CASCADE,
        related_name="staff_specialties"
      )
      class Meta:
        constraints = [
          UniqueConstraint(
            fields=["staff", "specialty"],
            name="unique_staff_specialty",
          ),
        ]
    ```
This creates a many-to-many relationship where:
  - One staff member can have multiple specialties
  - One specialty can be assigned to multiple staff members
  - `StaffSpecialty` is the through model that connects them
**Preventing duplicate associations:** Through models typically need a uniqueness constraint on the pair of foreign key columns to prevent the same association from being created twice. Add a `UniqueConstraint` to the through model's `Meta.constraints` referencing both FK field names (e.g., `staff` and `specialty`). Without this, calling `StaffSpecialty.objects.create(staff=staff, specialty=cardiology)` twice would create two identical rows. See Uniqueness Constraints for more details on constraint naming and lifecycle.
###  Through Model + ManyToManyField 
Adding a `ManyToManyField` with an explicit `through` parameter gives you direct ORM access to the related objects without manually traversing the join table.
**Important:** The `through` parameter is **required**. A `ManyToManyField` without `through` will cause an error because the SDK cannot manage implicit join tables.
    ```python
    from django.db.models import CASCADE, ForeignKey, Index, ManyToManyField, TextField, UniqueConstraint
    from canvas_sdk.v1.data.base import CustomModel
    from canvas_sdk.v1.data import Staff, ModelExtension
    class CustomStaff(Staff, ModelExtension):
      """Extends Staff with custom attribute support."""
      pass
    class Specialty(CustomModel):
      """Medical specialty (e.g., Cardiology, Neurology)."""
      name = TextField()
      staff = ManyToManyField(
        CustomStaff,
        through="StaffSpecialty",
        related_name="%(app_label)s_specialties",
      )
      class Meta:
        indexes = [
          Index(fields=["name"]),
        ]
    class StaffSpecialty(CustomModel):
      """Through model for the staff-specialty relationship."""
      staff = ForeignKey(
        CustomStaff,
        to_field="dbid",
        on_delete=CASCADE,
        related_name="%(app_label)s_staff_specialties",
      )
      specialty = ForeignKey(
        Specialty,
        to_field="dbid",
        on_delete=CASCADE,
        related_name="staff_specialties",
      )
      class Meta:
        constraints = [
          UniqueConstraint(
            fields=["staff", "specialty"],
            name="unique_staff_specialty",
          ),
        ]
    ```
With the `ManyToManyField` declared, you can traverse the relationship directly:
    ```python
    # Direct access to related objects (returns Staff queryset, not StaffSpecialty)
    specialty = Specialty.objects.get(name="Cardiology")
    staff_members = specialty.staff.all()
    # Reverse access from staff to specialties
    staff = CustomStaff.objects.get(id="staff-uuid")
    specialties = staff.staff_plus_specialties.all()  # uses the ManyToManyField's related_name
    ```
Compare this with the through-model-only approach, where you must navigate through the join table:
    ```python
    # Without ManyToManyField — must traverse the join table
    staff_members = [ss.staff for ss in specialty.staff_specialties.all()]
    ```
####  Differences from Standard Django ManyToManyField 
Behavior| Standard Django| Canvas SDK  
---|---|---  
`through` parameter| Optional — Django creates an implicit join table| **Required** — must reference a CustomModel  
`.add()`, `.remove()`, `.set()`| Available when no explicit through model| **Not available** — use the through model's `.objects.create()` and `.delete()` instead  
`.clear()`| Available| **Not available** — use `StaffSpecialty.objects.filter(...).delete()` instead  
`.all()`, filtering, `prefetch_related`| Available| Available  
Because Django requires you to use the through model directly for creating and deleting relationships when an explicit `through` is declared, the CRUD patterns are the same whether or not you add the `ManyToManyField`. The field's value is in query convenience — direct `.all()` access and cleaner `prefetch_related` lookups.
####  related_name with ManyToManyField 
When a `ManyToManyField` targets a core SDK model (like `Staff` or `Patient`), you **must** use the `%(app_label)s_` prefix in `related_name` to avoid naming collisions between plugins:
    ```python
    staff = ManyToManyField(
        CustomStaff,
        through="StaffSpecialty",
        related_name="%(app_label)s_specialties",  # becomes e.g. "my_plugin_specialties"
    )
    ```
This is the same namespacing requirement that applies to `ForeignKey` and `OneToOneField` when targeting SDK models. See [Extending SDK Models](/sdk/custom-data-extending-sdk-models/) for a full explanation of when namespacing is required and how proxy models avoid it.
###  Creating Many-to-Many Records 
Regardless of whether you use `ManyToManyField`, create and delete relationships through the through model directly:
    ```python
    from my_plugin.models import CustomStaff, Specialty, StaffSpecialty
    # Create specialties
    cardiology = Specialty.objects.create(name="Cardiology")
    internal_medicine = Specialty.objects.create(name="Internal Medicine")
    emergency_medicine = Specialty.objects.create(name="Emergency Medicine")
    # Get staff member
    staff = CustomStaff.objects.get(id="staff-uuid")
    # Create associations between staff and specialties
    StaffSpecialty.objects.create(staff=staff, specialty=cardiology)
    StaffSpecialty.objects.create(staff=staff, specialty=internal_medicine)
    # Bulk create multiple associations at once
    specialties_to_add = [emergency_medicine, cardiology]
    staff_specialties = [
        StaffSpecialty(staff=staff, specialty=specialty) for specialty in specialties_to_add
    ]
    StaffSpecialty.objects.bulk_create(staff_specialties)
    # Replace all specialties for a staff member
    # First, remove existing associations
    StaffSpecialty.objects.filter(staff=staff).delete()
    # Then create new associations
    new_specialties = [cardiology, emergency_medicine]
    new_staff_specialties = [
        StaffSpecialty(staff=staff, specialty=specialty) for specialty in new_specialties
    ]
    StaffSpecialty.objects.bulk_create(new_staff_specialties)
    ```
**Note:** Do not use `.add()`, `.remove()`, `.set()`, or `.clear()` on the `ManyToManyField`. Django disables these methods when an explicit `through` model is declared. Use the through model's manager (e.g., `StaffSpecialty.objects`) for all create and delete operations.
###  Querying Many-to-Many Relationships 
    ```python
    from my_plugin.models import CustomStaff, Specialty, StaffSpecialty
    # Access staff member's specialties through the join table
    staff = CustomStaff.objects.get(id="staff-uuid")
    staff_specialty_records = staff.staff_specialties.all()
    for staff_specialty in staff_specialty_records:
        print(f"- {staff_specialty.specialty.name}")
    # Get just the specialty names
    specialty_names = [ss.specialty.name for ss in staff.staff_specialties.all()]
    # Access all staff members with a specific specialty (reverse)
    cardiology = Specialty.objects.get(name="Cardiology")
    cardiology_staff_records = cardiology.staff_specialties.all()
    for staff_specialty in cardiology_staff_records:
        staff_member = staff_specialty.staff
        print(f"- {staff_member.first_name} {staff_member.last_name}")
    # Find staff IDs with specific specialties
    staff_ids = StaffSpecialty.objects.filter(
        specialty__name__in=["Cardiology", "Internal Medicine"]
    ).values_list("staff_id", flat=True)
    # Find staff members with a specific specialty
    cardiologists = CustomStaff.objects.filter(
        staff_specialties__specialty__name="Cardiology"
    ).distinct()
    # Check if a staff member has a specific specialty
    has_cardiology = staff.staff_specialties.filter(specialty__name="Cardiology").exists()
    # Count specialties for a staff member
    specialty_count = staff.staff_specialties.count()
    # Efficient querying with prefetch_related
    staff_with_specialties = (
        CustomStaff.objects
        .prefetch_related("staff_specialties__specialty")
        .all()
    )
    for staff in staff_with_specialties:
        specialties = [ss.specialty.name for ss in staff.staff_specialties.all()]
        print(f"{staff.first_name} {staff.last_name}: {', '.join(specialties)}")
    ```
**Key points about many-to-many relationships:**
  - Both sides of the relationship can access the through model using `related_name`
  - Without `ManyToManyField`: `staff.staff_specialties.all()` returns `StaffSpecialty` objects — access the related object via `ss.specialty`
  - With `ManyToManyField`: `specialty.staff.all()` returns `Staff` objects directly
  - You can add additional fields to the through model to store metadata about the relationship (e.g., date assigned, certification level, etc.)
  - Query across the relationship using double underscores: `CustomStaff.objects.filter(staff_specialties__specialty__name="Cardiology")`
##  Delete Behavior 
The `on_delete` parameter on `ForeignKey` and `OneToOneField` controls what happens to child records when a parent record is deleted. The SDK supports three values:
  - **`CASCADE`** — Delete the child record automatically. This is the most common choice for tightly-coupled relationships like join table entries, child records that have no meaning without their parent, or `OneToOneField` with `primary_key=True`.
  - **`SET_NULL`** — Set the foreign key column to `NULL`, keeping the child record. Useful when the child has independent value even if its parent is removed (e.g., an audit log entry whose associated staff member has been deactivated).
  - **`DO_NOTHING`** — Take no automatic action. The plugin is fully responsible for preventing orphaned references.
These behaviors are enforced at the Django ORM level, not by database-level foreign key constraints. They apply when deleting via `model.delete()` or `queryset.delete()`.
**Tip:** Use `CASCADE` on through-model (join table) foreign keys so that deleting either side of a many-to-many relationship automatically cleans up the association rows.
##  The CustomModel Lifecycle 
Managing database schemas necessarily introduces complexity, because there is state to maintain over time as the software evolves. Common pitfalls include expensive table rewrite operations, migrations that fail in some environments due to manual changes, database system-specific nuances, unsatisfied foreign key constraints due to data corruption or improper order of operations, etc.
The Canvas SDK Custom Data feature aims to simplify maintenance, while sacrificing some rigor found in a full migration system like Django's.
Operation| Allowed| Explanation  
---|---|---  
Create Model| Yes| A table corresponding to your CustomModel will be created if it does not exist. An autoincrementing column named `dbid` will be its sole attribute.  
Add Field| Yes| A column corresponding to a Field declared within your CustomModel will be added to the table if it does not exist. It will be nullable, without defaults to eliminate table rewrites.  
Add UniqueConstraint| Yes| A unique index will be created if it does not already exist. Fails if existing data contains duplicates for the constrained columns.  
Add Index| Yes| An index will be created if it does not already exist.  
Alter Field| No| This can cause a table rewrite, and requires a full migration metadata system. Create a new Field in your model. Copy data from old to new.  
Drop Field| No| This will cause a table rewrite, and requires a full migration metadata system. Remove the Field from your model and it will be ignored.  
Drop UniqueConstraint| No| Remove the constraint from your model and it will be ignored, but the unique index will remain in the database.  
Drop Index| No| Remove the index from your model and it will be ignored, but the index will remain in the database.  
Alter Model| No| Requires a full migration metadata system. Create a new Model in your plugin. Copy data from old to new.  
Drop Model| No| Requires a full migration metadata system. Remove the model from your plugin and it will be ignored.  
###  Best Practices 
  1. Emphasize local development over use of a development EMR instance.
  2. Write [automated tests](/sdk/custom-data-testing/) exercising your business logic.
  3. Extract business logic and CRUD operations into "service" classes that can be tested in isolation.
##  Advanced Patterns 
###  Combining Approaches 
You can combine CustomModels with [AttributeHubs](/sdk/custom-data-attribute-hubs/) for maximum flexibility:
    ```python
    from canvas_sdk.v1.data.base import CustomModel
    from canvas_sdk.v1.data import AttributeHub, Staff, ModelExtension
    from django.db.models import CASCADE, ForeignKey, SET_NULL, TextField
    class CustomStaff(Staff, ModelExtension):
        pass
    class Department(CustomModel):
        """Structured department model."""
        name = TextField()
        code = TextField()
    class StaffDepartment(CustomModel):
        """Staff can belong to multiple departments."""
        staff = ForeignKey(
            CustomStaff, on_delete=SET_NULL, related_name="department_assignments"
        )
        department = ForeignKey(
            Department, on_delete=CASCADE, related_name="staff_members"
        )
        role = TextField()
    # Use CustomModels for structured data with relationships
    staff = CustomStaff.objects.get(id="staff-uuid")
    dept = Department.objects.get(code="CARDIO")
    StaffDepartment.objects.create(
        staff=staff,
        department=dept,
        role="Lead Physician"
    )
    # Use an AttributeHub for flexible, unstructured data
    hub, created = AttributeHub.objects.get_or_create(
        type="staff_preferences",
        id=f"staff:{staff.id}"
    )
    hub.set_attributes({
        "pager_number": "555-1234",
        "preferred_contact": "email",
        "office_hours": {"monday": "9-5", "tuesday": "9-5"}
    })
    ```
###  Query Optimization 
Optimize database queries using `select_related` and `prefetch_related`:
    ```python
    from my_plugin.models import Specialty, StaffSpecialty, CustomStaff
    # Use select_related for ForeignKey (SQL JOIN)
    # Load StaffSpecialty with related staff and specialty in one query
    staff_specialties = StaffSpecialty.objects.select_related("staff", "specialty").all()
    for ss in staff_specialties:
        # No additional queries - both staff and specialty are already loaded
        print(f"{ss.staff.first_name} {ss.staff.last_name}: {ss.specialty.name}")
    # Use prefetch_related for reverse ForeignKey relationships
    # Load staff with all their specialties efficiently
    staff_list = CustomStaff.objects.prefetch_related("staff_specialties__specialty").all()
    for staff in staff_list:
        # No additional queries - staff_specialties and specialties are already loaded
        for ss in staff.staff_specialties.all():
            print(f"{staff.first_name}: {ss.specialty.name}")
    # Prefetch specialties for multiple staff members
    specialties_list = Specialty.objects.prefetch_related("staff_specialties__staff").all()
    for specialty in specialties_list:
        staff_members = [ss.staff for ss in specialty.staff_specialties.all()]
        print(f"{specialty.name}: {len(staff_members)} staff members")
    # Use Prefetch for custom filtering
    from django.db.models import Prefetch
    # Only load staff specialties with specific specialty names
    staff_with_filtered_specialties = CustomStaff.objects.prefetch_related(
        Prefetch(
            "staff_specialties",
            queryset=StaffSpecialty.objects.filter(
                specialty__name__in=["Cardiology", "Neurology"]
            ).select_related("specialty")
        )
    ).all()
    ```
###  Complex Queries 
Use Django's Q objects for complex filtering and aggregation:
    ```python
    from django.db.models import Q, Count
    from my_plugin.models import CustomStaff, Specialty, StaffSpecialty
    # OR conditions - Find staff with Cardiology OR Neurology specialty
    staff_with_cardio_or_neuro = CustomStaff.objects.filter(
        Q(staff_specialties__specialty__name="Cardiology") |
        Q(staff_specialties__specialty__name="Neurology")
    ).distinct()
    # AND conditions - Find specialties with "Cardiology" or "Medicine" in the name
    cardio_or_medicine = Specialty.objects.filter(
        Q(name__icontains="Cardiology") | Q(name__icontains="Medicine")
    )
    # Negation - Find staff WITHOUT a specific specialty
    staff_without_cardiology = CustomStaff.objects.exclude(
        staff_specialties__specialty__name="Cardiology"
    )
    # Complex filtering - Staff with multiple specific specialties
    # Note: This requires DISTINCT because joins can create duplicate rows
    staff_with_multiple = CustomStaff.objects.filter(
        staff_specialties__specialty__name="Cardiology"
    ).filter(
        staff_specialties__specialty__name="Internal Medicine"
    ).distinct()
    # Count related objects - Staff with specialty counts
    staff_with_counts = CustomStaff.objects.annotate(
        specialty_count=Count("staff_specialties")
    ).filter(specialty_count__gte=2)
    # Group by and aggregate - Count how many staff have each specialty
    specialty_counts = Specialty.objects.annotate(
        staff_count=Count("staff_specialties")
    ).order_by("-staff_count")
    for specialty in specialty_counts:
        print(f"{specialty.name}: {specialty.staff_count} staff members")
    ```
##  Best Practices 
###  Model Design 
  1. **Use appropriate field types** \- Choose the most specific field type for your data
  2. **Define related_name** \- Always specify `related_name` for clear reverse relationships
  3. **Keep models focused** \- Each model should represent a single, well-defined concept
###  Relationships 
  1. **Choose the right relationship type** \- OneToOne for 1:1, ForeignKey for 1:many, join tables and "through" models for many:many
  2. **Use through models** \- To create a join table bridging two other entities, create a CustomModel representing the relationship
  3. **Handle deletions** \- Use `CASCADE` on join table foreign keys so associations are cleaned up automatically. Use `SET_NULL` when child records should survive parent deletion. Use `DO_NOTHING` only when you manage cleanup explicitly in plugin code
###  Performance 
  1. **Add indexes strategically** \- Index frequently filtered fields - foreign key fields are automatically indexed
  2. **Use select_related** \- For ForeignKey and OneToOneField to reduce queries
  3. **Use prefetch_related** \- For reverse ForeignKey fields (including join tables for many-to-many fields)
  4. **Avoid N+1 queries** \- Always prefetch related data when iterating
  5. **Use exists() for checks** \- More efficient than count() or len()
  6. **Use iterator() for large datasets** \- Reduces memory usage for processing many records
###  Data Integrity 
  1. **Enforce uniqueness with UniqueConstraint** \- Use `UniqueConstraint` in `Meta.constraints` to prevent duplicate data at the database level
  2. **Validate in model methods** \- Add custom validation in `clean()` method
  3. **Use transactions** \- Wrap multiple operations in atomic transactions
  4. **Handle DoesNotExist** \- Always catch exceptions when using `get()`
###  Testing 
  1. **Use model factories** \- Create test data with factory patterns
  2. **Test model methods** \- Verify custom model methods and properties
  3. **Test relationships** \- Ensure relationships work in both directions
  4. **Test data quality** \- The plugin is responsible for ensuring uniqueness and validity of foreign keys
  5. **Test edge cases** \- Test with null values, empty strings, boundary conditions
##  See Also 
  - [Custom Data Overview](/sdk/custom-data/) \- Overview of all custom data techniques
  - [Extending SDK Models](/sdk/custom-data-extending-sdk-models/) \- Proxy models, `related_name` namespacing, and referencing SDK models
  - [Design Considerations](/sdk/custom-data-design-considerations/) \- Choosing the right technique and avoiding anti-patterns
  - [AttributeHubs](/sdk/custom-data-attribute-hubs/) \- Standalone key-value storage
  - [Transactions](/sdk/custom-data-transactions/) \- All-or-nothing writes with `transaction.atomic()`
  - [Sharing Data](/sdk/custom-data-sharing-data/) \- Sharing data among plugins
  - [Testing Custom Data](/sdk/custom-data-testing/) \- Testing utilities and examples
  - [Data Models](/sdk/data/) \- Core SDK data models
  - [Caching API](/sdk/caching) \- Auto-expiring transient data

---

# Design Considerations

Source: https://docs.canvasmedical.com/sdk/custom-data-design-considerations/

Choosing the right storage technique prevents performance problems, data inconsistencies, and unnecessary code complexity down the road. This page describes common anti-patterns for each technique and recommends alternatives.
For an overview of available techniques, see the [Custom Data Overview](/sdk/custom-data/).
##  Extending SDK Models with Custom Data 
To attach custom fields to existing SDK models (Patient, Staff, etc.), use a [CustomModel](/sdk/custom-data-custom-models/) with a `OneToOneField` pointing at the SDK model. This gives you typed, indexed columns with full ORM support — `select_related`, reverse lookups via `related_name`, and compound filtering in a single query.
    ```python
    from canvas_sdk.v1.data import Patient, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import BooleanField, DO_NOTHING, IntegerField, OneToOneField, TextField
    class CustomPatient(Patient, ModelExtension):
        pass
    class PatientProfile(CustomModel):
        patient = OneToOneField(
            CustomPatient, to_field="dbid", on_delete=DO_NOTHING,
            related_name="profile"
        )
        preferred_language = TextField()
        risk_score = IntegerField()
        is_vip = BooleanField()
    ```
CustomModels with `OneToOneField` are preferred because they offer typed columns, indexing, compound queries, and a schema that is visible and self-documenting. See [Extending SDK Models](/sdk/custom-data-extending-sdk-models/) for details on proxy models and `related_name` namespacing.
For truly simple, one-off metadata that doesn't justify a table (e.g., a single configuration flag), an [AttributeHub](/sdk/custom-data-attribute-hubs/) can be a lighter-weight alternative.
##  AttributeHubs — When to Reconsider 
AttributeHubs use EAV (entity-attribute-value) storage and are standalone — not attached to any Canvas model. They are convenient for one-off state and configuration, but the same EAV limitations apply when used at scale. Their best application is storing a collection of attributes that will mainly be retrieved by identifier rather than by value.
###  Modeling entities with relationships 
If you have "departments" and need to assign staff to them, encoding `staff_id` as a string attribute means no JOINs, no referential integrity, potentially duplicated data. The plugin must manually maintain consistency.
**Use instead:** [CustomModels](/sdk/custom-data-custom-models/) with `ForeignKey` fields and junction tables handle relationships naturally, with ORM-level traversal and `prefetch_related` support.
###  Large homogeneous collections 
Storing thousands of hubs of `type="patient_visit"` where you need to filter, sort, or paginate across them becomes expensive. Each filter condition requires a JOIN to the attribute table.
**Use instead:** A [CustomModel](/sdk/custom-data-custom-models/) with typed, indexed columns. Filtering, sorting, and pagination use standard SQL operations.
###  Data requiring aggregation 
Trying to SUM, AVG, or COUNT across AttributeHub attributes requires joining to the attribute table and selecting the correct typed column (`int_value`, `decimal_value`, etc.) per attribute name. This is fragile and slow.
**Use instead:** [CustomModel](/sdk/custom-data-custom-models/) columns make Django ORM aggregation (`annotate`, `aggregate`) straightforward.
###  Data with a consistent schema 
If every hub of a given `type` has the same set of attributes, you've designed a schema — just without enforcement or indexes. You're paying the cost of EAV without the benefit of flexibility.
**Use instead:** A [CustomModel](/sdk/custom-data-custom-models/) gives you type safety, column-level indexes, and cleaner queries.
##  CustomModels — When to Reconsider 
CustomModels create real database tables with typed columns. They are the most powerful option but carry a commitment: tables can be added but never dropped via the SDK, and fields can be added but never altered or removed.
###  Simple metadata on existing models 
For a small number of independent metadata fields on an SDK model (e.g., a single `is_vip` flag on Patient), a full CustomModel with `OneToOneField` is the recommended approach — it gives you typed columns, indexing, and compound queries. However, if the overhead of a table feels excessive for truly one-off data, an [AttributeHub](/sdk/custom-data-attribute-hubs/) keyed by entity type and ID can serve as a lightweight alternative.
###  Highly dynamic or schemaless data 
If every record has different fields — for example, caching responses from external APIs where the payload varies per endpoint — a CustomModel forces a rigid schema. You'll accumulate nullable columns for each variation, and fields can never be dropped.
**Use instead:** [AttributeHubs](/sdk/custom-data-attribute-hubs/) for truly schemaless data, or a CustomModel with a single `JSONField` if you still want a table but need flexible contents.
###  Ephemeral data 
CustomModel tables are permanent. Once created, they cannot be dropped via the SDK. For short-lived data like session tokens, rate-limit windows, or temporary processing state, a persistent table is the wrong tool.
**Use instead:** The [Caching API](/sdk/caching) for data with a natural TTL. For semi-persistent unstructured state, [AttributeHubs](/sdk/custom-data-attribute-hubs/) are lighter weight.
###  Premature normalization 
Don't create five interrelated CustomModels with foreign keys when the data is simple and queried infrequently. Over-engineering the schema early is costly because tables cannot be dropped if you change your mind.
**Use instead:** Start with fewer models. A single `JSONField` column or an [AttributeHub](/sdk/custom-data-attribute-hubs/) can hold loosely structured data until access patterns stabilize and justify a richer schema.
##  Quick Reference 
Situation| Recommended Approach  
---|---  
Custom fields on Patient, Staff, or other SDK models| CustomModel with `OneToOneField`  
Provider preferences (notification settings, display options)| CustomModel with `OneToOneField`  
API sync cursors, external system state| AttributeHub  
Plugin configuration or feature flags| AttributeHub  
One-off key-value data unrelated to a Canvas model| AttributeHub  
Rapid prototyping before committing to a schema| AttributeHub  
Structured entities with a stable, known schema| CustomModel  
Relationships between entities (foreign keys, join tables)| CustomModel  
Data requiring compound filtering, sorting, or aggregation| CustomModel  
Data consumed by reports or analytics| CustomModel  
High-write-frequency counters or accumulators| CustomModel  
Short-lived data that should auto-expire| [Caching API](/sdk/caching)  
##  See Also 
  - [Custom Data Overview](/sdk/custom-data/) \- Introduction to custom data storage
  - [Extending SDK Models](/sdk/custom-data-extending-sdk-models/) \- Proxy models and referencing SDK models
  - [AttributeHubs](/sdk/custom-data-attribute-hubs/) \- Standalone key-value storage
  - [CustomModels](/sdk/custom-data-custom-models/) \- Django models for structured data
  - [Transactions](/sdk/custom-data-transactions/) \- All-or-nothing writes with `transaction.atomic()`
  - [Caching API](/sdk/caching) \- Auto-expiring transient data

---

# Extending SDK Models

Source: https://docs.canvasmedical.com/sdk/custom-data-extending-sdk-models/

##  Overview 
SDK models like `Patient`, `Staff`, and `Note` are shared across all plugins. To attach custom data or create relationships to these models from your [CustomModels](/sdk/custom-data-custom-models/), extend them with `ModelExtension` to create a plugin-private proxy model.
* * *
##  Creating a Model Extension 
Subclass the SDK model together with `ModelExtension`:
    ```python
    from canvas_sdk.v1.data import Staff, ModelExtension
    class CustomStaff(Staff, ModelExtension):
        pass
    ```
What happens automatically:
  - **`proxy = True`** is set by the `ModelExtensionMetaClass`. No new database table is created — the proxy shares the parent model's table.
  - **`app_label`** is set to your plugin name (derived from the module path).
  - `CustomStaff` behaves identically to `Staff` for queries — `CustomStaff.objects.all()` returns the same rows as `Staff.objects.all()`.
You can name the class anything, but it **must** subclass both a concrete SDK model and `ModelExtension`.
Extended SDK models may be defined anywhere in your plugin since they do not require database modifications. However, placing them in the `models` directory alongside your CustomModels is recommended for clarity.
* * *
##  Why Proxy Models? 
SDK models are shared across every plugin in the system. If two plugins each added a bare `related_name="biography"` on a `ForeignKey` pointing at `Staff`, Django would raise a clash error — both reverse relations would compete for the same attribute on the shared `Staff` class.
Proxy models solve this by giving each plugin its own private subclass of the SDK model. Because `CustomStaff` is a distinct model (even though it shares the same table), reverse relations registered on `CustomStaff` are scoped to the plugin that defined it. The shared SDK model stays clean and unaffected.
* * *
##  Referencing SDK Models from CustomModels 
When a CustomModel needs a `ForeignKey` or `OneToOneField` pointing at an SDK model, you have two approaches.
###  Approach 1: Via Proxy (Recommended) 
Create a `ModelExtension` proxy and point your relationship field at it. Because the target is plugin-private, `related_name` can be any simple name — no namespacing required.
    ```python
    from canvas_sdk.v1.data import Staff, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import DO_NOTHING, OneToOneField, TextField
    class CustomStaff(Staff, ModelExtension):
        pass
    class Biography(CustomModel):
        staff = OneToOneField(
            CustomStaff, to_field="dbid", on_delete=DO_NOTHING,
            related_name="biography"
        )
        text = TextField()
    ```
Reverse lookup works through the proxy:
    ```python
    staff = CustomStaff.objects.get(id="some-uuid")
    bio = staff.biography  # accesses the Biography via related_name
    ```
###  Approach 2: Direct SDK Model with Namespaced `related_name`
Point directly at the SDK model, but you **must** namespace the `related_name` to prevent collisions across plugins. Two formats are accepted:
Format| Example| Notes  
---|---|---  
`%(app_label)s_` prefix (recommended)| `related_name="%(app_label)s_biography"`| Django substitutes your plugin's `app_label` at class creation time  
Hardcoded plugin prefix| `related_name="my_plugin_biography"`| Works, but breaks if you rename the plugin  
`"+"`| `related_name="+"`| Disables the reverse relation entirely  
    ```python
    from canvas_sdk.v1.data import Staff
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import DO_NOTHING, OneToOneField, TextField
    class Biography(CustomModel):
        staff = OneToOneField(
            Staff, to_field="dbid", on_delete=DO_NOTHING,
            related_name="%(app_label)s_biography"
        )
        text = TextField()
    ```
###  Comparison 
| Via Proxy| Direct SDK Model  
---|---|---  
`related_name` namespacing required?| No| Yes  
Reverse lookup available?| Yes, via the proxy class| Yes, via the SDK model  
Reverse attribute name| Simple (e.g., `staff.biography`)| Prefixed (e.g., `staff.my_plugin_biography`)  
Extra class needed?| Yes (`ModelExtension` proxy)| No  
In most cases, Approach 1 is preferred — it keeps `related_name` values short and readable, and the proxy class is reusable across multiple CustomModels in the same plugin.
* * *
##  Proxying Related Objects with `proxy_field`
When you use `ModelExtension` proxies and follow related objects through ForeignKey fields, the returned instance is the base SDK class — not your proxy. For example:
    ```python
    from canvas_sdk.v1.data import Note, Patient, ModelExtension
    class CustomPatient(Patient, ModelExtension):
        def full_display_name(self):
            # custom method only available on CustomPatient
            return f"{self.first_name} {self.last_name} (DOB: {self.birth_date})"
    class CustomNote(Note, ModelExtension):
        pass
    note = CustomNote.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    note.patient                       # returns a Patient, not CustomPatient
    note.patient.full_display_name()   # AttributeError!
    ```
This happens because Django's ForeignKey descriptor resolves the relation to the concrete model (`Patient`), unaware of your proxy class. You would need an extra query to "re-fetch" the object as a `CustomPatient`.
###  The `proxy_field` descriptor 
`proxy_field` solves this by intercepting the ForeignKey access and transparently returning the proxy class instead:
    ```python
    from canvas_sdk.v1.data import Note, Patient, ModelExtension, proxy_field
    class CustomPatient(Patient, ModelExtension):
        def full_display_name(self):
            return f"{self.first_name} {self.last_name} (DOB: {self.birth_date})"
    class CustomNote(Note, ModelExtension):
        patient = proxy_field(CustomPatient)
    note = CustomNote.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    note.patient                       # returns a CustomPatient instance
    note.patient.full_display_name()   # works!
    ```
No extra queries are issued — `proxy_field` reuses the already-fetched row and swaps its Python class to the proxy. Because proxy models share the same database table, this is safe and efficient.
###  How it works 
`proxy_field` is a Python [descriptor](https://docs.python.org/3/howto/descriptor.html). When you declare `patient = proxy_field(CustomPatient)` on a model class:
  1. `__set_name__` runs at class creation time and finds the original FK descriptor (`patient`) from the parent class in the MRO.
  2. `__get__` delegates to that original descriptor to load the related object, then sets `__class__` on the result to your proxy class.
  3. `__set__` passes assignment through to the original descriptor, so `note.patient = some_patient` continues to work normally.
  4. Accessing the attribute on the class (e.g., `CustomNote.patient`) returns the descriptor itself, not a model instance.
###  When to use `proxy_field`
Use `proxy_field` when:
  - You have `ModelExtension` proxies for multiple SDK models and need to navigate between them while keeping access to your custom methods or `related_name` fields.
  - You want to avoid extra database queries to "re-fetch" a related object as the proxy type.
`proxy_field` is not needed when:
  - You don't add custom methods, properties or `related_name` fields to your proxy class.
  - You access the related object's fields directly (e.g., `note.patient.first_name`) without needing proxy-specific behavior.
###  Null foreign keys 
`proxy_field` handles nullable ForeignKeys safely — if the relation is `None`, it returns `None` without error:
    ```python
    note = CustomNote.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    note.patient  # returns None if the FK is null, not an error
    ```
* * *
##  Common Errors 
###  `ValueError`: non-namespaced `related_name` on SDK model target 
If you point a `ForeignKey` or `OneToOneField` directly at an SDK model with a plain `related_name`, installation will fail with:
    ```text
    ValueError: CustomModel 'Biography' declares related_name='biography' on field 'staff'
    targeting SDK model 'Staff'. To prevent collisions across plugins, use a namespaced
    related_name like related_name='%(app_label)s_biography', or related_name='+' to
    disable the reverse relation.
    ```
**Fix:** Either switch to a proxy target (Approach 1) or add the `%(app_label)s_` prefix to your `related_name` (Approach 2).
This validation applies to `ForeignKey` and `OneToOneField`. Fields targeting other CustomModels or proxy models are exempt because those targets are already plugin-private.
* * *
##  See Also 
  - [CustomModels](/sdk/custom-data-custom-models/) \- Defining structured models, relationships, and queries
  - [AttributeHubs](/sdk/custom-data-attribute-hubs/) \- Standalone key-value storage
  - [Design Considerations](/sdk/custom-data-design-considerations/) \- Choosing the right technique and avoiding anti-patterns
  - [Transactions](/sdk/custom-data-transactions/) \- All-or-nothing writes with `transaction.atomic()`
  - [Sharing Data](/sdk/custom-data-sharing-data/) \- Sharing data with other plugins and external services
  - [Data Models](/sdk/data/) \- Core SDK data models

---

# Namespace Lifecycle

Source: https://docs.canvasmedical.com/sdk/custom-data-namespace-lifecycle/

Every plugin that uses custom data operates within a **namespace** — an isolated PostgreSQL schema that holds the plugin's AttributeHubs and CustomModels. During iterative development, namespaces accumulate tables, columns, and data that can get in the way. This page explains how namespaces are created and managed, and how to use the Canvas CLI to inspect and clean up namespaces as you work.
##  Namespace Naming Rules 
Namespace names use the format `org__name` (two parts separated by a double underscore). Each part must start with a lowercase letter and contain only lowercase letters, digits, and single underscores. The total length must not exceed **63 characters** (PostgreSQL's identifier limit).
Examples of valid names: `acme__shared_data`, `myorg__analytics`
##  How Namespaces Are Created 
A namespace is created automatically when the **first plugin** with `"access": "read_write"` is installed into it. The installation process:
  1. Creates a PostgreSQL schema named after the namespace
  2. Establishes two authentication keys (`namespace_read_access_key` and `namespace_read_write_access_key`) — auto-generated UUIDs by default, or values supplied by the installer (see [Pre-Supplying Keys at Creation](/sdk/custom-data-sharing-data/#pre-supplying-keys-at-creation))
  3. Stores the keys as secrets in the plugin
  4. Creates any CustomModel tables defined by the plugin
Subsequent plugins can join the namespace with the appropriate access key. See [Sharing Data](/sdk/custom-data-sharing-data/) for details on multi-plugin namespaces.
###  Installation Flow 
![](/assets/images/sdk/custom-data/installation_flowchart.jpg)
The path depends on the declared access level and whether the namespace already exists:
Declared Access| Namespace Exists| Key Provided| Result  
---|---|---|---  
`read_write`| No| Neither| Creates namespace and tables; auto-generates both keys  
`read_write`| No| Both `namespace_read_access_key` and `namespace_read_write_access_key`| Creates namespace and tables using the supplied keys (see [Pre-Supplying Keys at Creation](/sdk/custom-data-sharing-data/#pre-supplying-keys-at-creation))  
`read_write`| Yes| Valid `namespace_read_write_access_key`| Plugin installed, tables created  
`read_write`| Yes| Invalid or missing| Installation fails  
`read`| Yes| Valid `namespace_read_access_key`| Plugin installed with read access  
`read`| No| N/A| Installation fails  
`read`| Yes| Invalid or missing| Installation fails  
##  Development Workflow 
When developing a plugin with custom data, you'll typically iterate through cycles of changing your models, reinstalling the plugin, and testing. Each reinstall can leave behind tables from previous iterations — renamed models leave orphaned tables, and test data accumulates. The `canvas namespace` CLI commands let you inspect what's in a namespace and clean it up without having to connect to the database directly.
###  Typical Iteration Cycle 
  1. Edit your CustomModel definitions or manifest
  2. Redeploy the plugin: `canvas deploy acme__my_plugin --instance dev-instance`
  3. Test your changes
  4. If models were renamed or removed, use `canvas namespace reset` to clean up orphaned tables
  5. Repeat
##  CLI Commands 
All namespace commands require a running Canvas instance. Pass `--host` to specify which instance to connect to. They connect with the [instance API credentials](/sdk/canvas_cli/#instance-api-credentials-credentialsini-deprecated) in `~/.canvas/credentials.ini` until they move to your Canvas Platform sign-in, before December 14, 2026.
###  Listing Namespaces 
See all custom data namespaces on an instance:
    ```bash
    canvas namespace list --host dev-instance
    ```
Output shows each namespace with its total table count and the number of custom (non-system) tables:
    ```text
    acme_corp__shared_data    tables: 7    custom: 3
    acme_corp__analytics      tables: 5    custom: 1
    ```
###  Inspecting a Namespace 
View the tables and columns in a specific namespace:
    ```bash
    canvas namespace inspect acme_corp__shared_data --host dev-instance
    ```
Output separates system tables (managed by the framework) from custom tables (defined by your plugin), and shows column details for custom tables:
    ```text
    Namespace: acme_corp__shared_data
    System tables:
      namespace_auth       ~2 rows
      schema_version       ~2 rows
      custom_attribute     ~150 rows
      attribute_hub        ~3 rows
    Custom tables:
      customnote   ~25 rows
        dbid     bigint    not null
        title    text      nullable
        body     text      nullable
      specialty    ~8 rows
        dbid     bigint    not null
        name     character varying    nullable
    ```
This is useful for verifying that your models were created correctly after installation, or for understanding what's in a namespace before deciding whether to reset or drop it.
###  Resetting a Namespace 
Reset drops your custom tables and truncates the data in system tables, but preserves the namespace itself and its authentication keys. This is the right choice when you want to start fresh with your models while keeping the namespace intact for reinstallation.
By default, reset runs in **dry-run mode** and only shows what would happen:
    ```bash
    canvas namespace reset acme_corp__shared_data --host dev-instance
    ```
    ```text
    Namespace: acme_corp__shared_data
    Custom tables to drop:
      customnote    ~25 rows
      specialty     ~8 rows
    Data tables to truncate:
      custom_attribute    ~150 rows
      attribute_hub       ~3 rows
    This is a dry run. To execute, re-run with --execute
    ```
To actually perform the reset, add `--execute`. You will be prompted to confirm by typing the full namespace name:
    ```bash
    canvas namespace reset acme_corp__shared_data --host dev-instance --execute
    ```
    ```text
    This will reset namespace 'acme_corp__shared_data'. This cannot be undone.
    Type the full namespace name to confirm: acme_corp__shared_data
    Namespace 'acme_corp__shared_data' has been reset.
      Dropped tables: customnote, specialty
      Truncated tables: custom_attribute, attribute_hub
    ```
After a reset, reinstall your plugin to recreate the tables with your updated model definitions.
###  Dropping a Namespace 
Drop removes the entire namespace — the schema, all tables, all data, and all authentication keys. Use this when you want to completely remove a namespace and start over, or when you're done with a development namespace and want to clean up.
Dry-run mode (default):
    ```bash
    canvas namespace drop acme_corp__shared_data --host dev-instance
    ```
    ```text
    Namespace: acme_corp__shared_data
    All tables that will be dropped:
      attribute_hub        ~3 rows
      custom_attribute     ~150 rows
      customnote           ~25 rows
      schema_version       ~4 rows
      namespace_auth       ~2 rows
      specialty            ~8 rows
    This is a dry run. To execute, re-run with --execute
    ```
To execute:
    ```bash
    canvas namespace drop acme_corp__shared_data --host dev-instance --execute
    ```
After a drop, the next plugin installation with that namespace name will create it from scratch, generating new authentication keys. Any other plugins that were sharing the namespace will need to be reconfigured with the new keys.
##  Uninstalling and Reinstalling a Plugin 
Uninstalling a plugin **deletes its secrets** , including the system-generated `namespace_read_access_key` and `namespace_read_write_access_key`. The namespace schema and its data, however, **survive the uninstall**. This is by design: uninstalling a plugin should never destroy custom data, and a namespace shared by multiple plugins must not be torn down while another plugin is still using it.
A plugin deployed with [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy) keeps its access across an uninstall: Canvas Platform holds the namespace's keys and sends them with every install, so the next deploy restores them. The rest of this section applies to plugins installed with the deprecated `canvas install`.
Because the namespace still exists, reinstalling the plugin does **not** regenerate the keys — key generation only happens when the namespace is first created. The reinstalled plugin is therefore left without valid access keys and cannot read or write its own data, even though configuring the secrets appeared to succeed.
This applies in production as well as during development. To avoid getting stuck:
  - **Before uninstalling** , copy the namespace keys from the Canvas admin UI into an external secret store such as 1Password. On reinstall, set them back as plugin secrets and the plugin regains access immediately. (To find the keys: open the Canvas admin UI, find the plugin that created the namespace, and read the `namespace_read_access_key` / `namespace_read_write_access_key` secret values.)
  - **If the keys are already lost** , run `canvas namespace drop <namespace> --host <instance> --execute` to remove the namespace, then reinstall. Installation recreates the namespace and generates fresh keys. Any other plugins that were sharing the namespace must be reconfigured with the new keys.
##  When to Reset vs. Drop 
Scenario| Command  
---|---  
You renamed or removed a CustomModel and want to clean up the old table| `reset`  
Test data has accumulated and you want a clean slate| `reset`  
You changed your namespace name in the manifest| `drop` the old, then reinstall  
You're done developing and want to remove all traces| `drop`  
Other plugins share this namespace and you want to preserve their access| `reset` (keys are preserved)  
You want to regenerate the namespace authentication keys| `drop`, then reinstall  
You uninstalled a plugin and a reinstall can't access its data (keys were deleted)| `drop`, then reinstall — or restore the saved keys  
##  See Also 
  - [Quick Start](/sdk/custom-data-quick-start/) \- Get started with custom data in 10 minutes
  - [CustomModels](/sdk/custom-data-custom-models/) \- Define structured database tables
  - [Sharing Data](/sdk/custom-data-sharing-data/) \- Share data between plugins
  - [Testing](/sdk/custom-data-testing/) \- Automated tests for custom data
  - [Design Considerations](/sdk/custom-data-design-considerations/) \- Choosing the right approach

---

# Quick Start

Source: https://docs.canvasmedical.com/sdk/custom-data-quick-start/

##  Getting Started 
To use custom data in your plugin, declare a `custom_data` section in your [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#custom-data) with a namespace and access level. The namespace is a unique identifier scoped to your organization (formatted as `organization__name` with a double underscore), and the access level controls whether the plugin can read only or read and write data. When the first `read_write` plugin is deployed into a namespace, the system automatically initializes a data namespace and prepares tables. Canvas Platform holds the namespace's access keys and sends them to each plugin entitled to the namespace, so other plugins join it with consent rather than a copied key (see [Sharing Data](/sdk/custom-data-sharing-data/#custom-data-on-canvas-platform)).
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "1.0.0",
      "name": "acme_corp__my_plugin",
      "custom_data": {
        "namespace": "acme_corp__shared_data",
        "access": "read_write"
      }
    }
    ```
###  Step by Step 
  1. Sign in with `canvas login`, then run `canvas init`. These steps assume your organization's plugin prefix is `my_org`.
  2. When prompted for a name, enter `Hello Custom Data`
  3. `cd hello-custom-data/my_org__hello_custom_data`
  4. Open `CANVAS_MANIFEST.json` in your preferred editor.
  5. Create a `custom_data` block:
         ```json
         "custom_data": {
           "namespace": "my_org__hello_custom_data",
           "access": "read_write"
         }
         ```
  6. Next, create a `models` directory under the root of your plugin hierarchy, sibling to `CANVAS_MANIFEST.json` and `handlers`
  7. Create an `__init__.py` file inside of `models` and open it in your editor.
  8. Declare the following classes within the `__init__.py` file:
         ```python
         from canvas_sdk.v1.data import Note, ModelExtension
         from canvas_sdk.v1.data.base import CustomModel
         from django.db.models import DO_NOTHING, OneToOneField, TextField
         class CustomNote(Note, ModelExtension):
             """Proxy model — see Extending SDK Models for why this exists."""
             pass
         class NoteTag(CustomModel):
             """Stores a plugin-assigned tag on a note."""
             note = OneToOneField(
                 CustomNote, to_field="dbid", on_delete=DO_NOTHING,
                 related_name="tag", primary_key=True
             )
             tagged_by = TextField()
         ```
  9. Open `handlers/event_handlers.py` in your editor. Update the imports:
         ```python
         from my_org__hello_custom_data.models import CustomNote, NoteTag
         ```
  10. In the code, replace uses of `Note` with `CustomNote`. These objects behave the same as the SDK model. (See [Extending SDK Models](/sdk/custom-data-extending-sdk-models/) for why proxy models are used.)
  11. Add the following lines **after** the `note` reference has been initialized in the code:
         ```python
         tag, created = NoteTag.objects.get_or_create(
             note=note,
             defaults={"tagged_by": "hello-custom-data"}
         )
         log.info(f"Note tagged by: {tag.tagged_by}")
         ```
  12. Deploy the plugin to your development instance: `canvas deploy . --instance <instance>`
  13. Tail the logs with `canvas logs`
  14. Log into Canvas, navigate to a patient chart, and create a new note
In the logs you will see our message: `Note tagged by: hello-custom-data`
What just happened? When you deployed the plugin, a new database namespace called `my_org__hello_custom_data` was created. Within the namespace are tables that hold information owned by, and managed by, the `my_org` plugins. The `NoteTag` model you defined turned into a PostgreSQL table with the following structure:
    ```sql
    create table my_org__hello_custom_data.notetag
    (
        note_id   bigint not null primary key,
        tagged_by text
    );
    ```
Creating the `NoteTag` record caused a new row to be inserted into the `notetag` table in the `my_org__hello_custom_data` namespace. This table is private to the namespace. The Note itself is unmodified — the `NoteTag` CustomModel stores the additional data in its own table and links back to the note via a `OneToOneField`.
[CustomModels](/sdk/custom-data-custom-models) let you define fully structured tables with typed fields and relationships — including linking to SDK models like Note, Patient, and Staff via `OneToOneField` or `ForeignKey`.
###  AttributeHub Alternative 
If you don't need a structured model and just want to store a simple key-value pair, you can use an [AttributeHub](/sdk/custom-data-attribute-hubs/) instead. Replace the `NoteTag` creation in `event_handlers.py` with:
    ```python
    from canvas_sdk.v1.data import AttributeHub
    from logger import log
    note_id = "89992c23-c298-4118-864a-26cb3e1ae822"
    hub = AttributeHub.objects.create(
        type="note_tag",
        id=f"note:{note_id}"
    )
    hub.set_attribute("tagged_by", "hello-custom-data")
    log.info(f"Note tagged by: {hub.get_attribute('tagged_by')}")
    ```
AttributeHubs are standalone key-value stores — they don't require a model definition or a `models` directory. They're a good fit for one-off state, configuration, and data that doesn't have a natural schema. See [Design Considerations](/sdk/custom-data-design-considerations/) for help choosing between the two approaches.
##  See Also 
  - [Extending SDK Models](/sdk/custom-data-extending-sdk-models/) \- Why proxy models exist and how `related_name` namespacing works
  - [Transactions](/sdk/custom-data-transactions/) \- All-or-nothing writes with `transaction.atomic()`
  - [Testing Custom Data](/sdk/custom-data-testing/) \- Testing utilities and examples
  - [Sharing Data](/sdk/custom-data-sharing-data/) \- Sharing data with other plugins and external services
  - [Data Models](/sdk/data/) \- Core SDK data models
  - [Caching API](/sdk/caching) \- Auto-expiring transient data
  - [Simple API](/sdk/handlers-simple-api/) \- Simple API for sharing data between plugins
  - [Secrets](/sdk/secrets/) \- Managing API keys and sensitive configuration

---

# Sharing Data

Source: https://docs.canvasmedical.com/sdk/custom-data-sharing-data/

Plugins can share data in two ways, depending on the relationship between the plugins:
Approach| Use Case| Coupling  
---|---|---  
**Namespace Sharing**|  Plugins owned by the same organization that need direct database access| Tight  
**API Sharing**|  Plugins owned by different organizations, or when loose coupling is preferred| Loose  
##  Namespace Sharing 
Namespace sharing allows multiple plugins to read from and write to the same database tables. This is ideal for organizations that want to build smaller, focused plugins instead of a single monolithic plugin. A plugin may reside within one namespace only. If it needs to access data from multiple namespaces, then it must do so via API calls.
###  When to Use Namespace Sharing 
  - Your organization owns multiple plugins that need to share data
  - You want to break a large plugin into smaller, maintainable pieces
  - You need direct database access for performance
  - You want to avoid the overhead of API calls between plugins
###  Namespace Lifecycle 
For a full overview of how namespaces are created, managed, and cleaned up during development, see [Namespace Lifecycle](/sdk/custom-data-namespace-lifecycle/).
###  Custom data on Canvas Platform 
For a plugin deployed with [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy), Canvas Platform holds each namespace's access keys and sends them to every plugin entitled to them, so no key is copied between plugins:
  - The first plugin that declares `"access": "read_write"` for a namespace on an instance creates it there and owns it.
  - Another plugin that declares the same namespace, to read or to write, needs consent from the organization that runs the instance. `canvas deploy` shows each consent request and asks you to answer it; the deployment starts once every request is approved, and an approval stands for later deploys to that instance.
  - Leave `namespace_read_access_key` and `namespace_read_write_access_key` out of the manifest's `variables`. Canvas Platform supplies them, refuses a manifest that declares them, and refuses `canvas config set` for them.
  - A namespace that already exists on an instance, created by a plugin installed with `canvas install`, needs its keys recorded with Canvas Platform before a deploy can use it. [Moving to Canvas Platform](/guides/moving-to-canvas-platform/#2-rename-the-plugin-with-the-prefix) covers that step.
###  Access keys for plugins installed with `canvas install` (deprecated) 
> **Warning:** `canvas install` is deprecated, and support ends on December 14, 2026. The rest of this section describes how plugins installed straight onto an instance share a namespace. Plugins deployed with `canvas deploy` share a namespace as described in Custom data on Canvas Platform.
####  Discovering Access Keys 
After the namespace is created, you can find the generated keys in the **Canvas admin UI** :
  1. Navigate to **Settings → Plugins**
  2. Find the plugin that created the namespace
  3. Click to view plugin details
  4. The `namespace_read_access_key` and `namespace_read_write_access_key` appear in the **Secrets** section
Share these keys securely with developers of other plugins that need access:
  - Share `namespace_read_access_key` with plugins that only need to read data
  - Share `namespace_read_write_access_key` with plugins that need to modify data
> **Important:** Store these keys in a secure location outside of Canvas, such as 1Password. Removing a key from the manifest's `secrets` array does **not** delete the stored value — it is preserved. However, **uninstalling the plugin deletes its secrets** , including the namespace keys. Because the namespace itself survives an uninstall, a later reinstall will not regenerate the keys, so a copy kept outside Canvas is the only way to restore access. See [Uninstalling and Reinstalling a Plugin](/sdk/custom-data-namespace-lifecycle/#uninstalling-and-reinstalling-a-plugin).
####  Pre-Supplying Keys at Creation 
By default, Canvas auto-generates the two access keys the first time a `read_write` plugin creates a namespace. You can also **supply both keys yourself** at that first install — pass them through the same `--secret` mechanism used for joins:
    ```bash
    canvas install my_plugin \
      --host demo.canvasmedical.com \
      --secret namespace_read_access_key=<your-read-key> \
      --secret namespace_read_write_access_key=<your-read-write-key>
    ```
When both keys are present at the install that creates the namespace, those plaintext values are what get hashed into the namespace's authentication table — Canvas does **not** generate fresh UUIDs.
Rules:
  - Supply **both** keys for your values to take effect. If you provide only one — or leave either value empty — Canvas silently ignores the supplied keys and auto-generates both instead. The install still succeeds; it does not fail.
  - Format is not enforced, but UUID4s are conventional.
  - This only applies to the install that **creates** the namespace. Subsequent joins validate against whatever was written at creation time.
  - If you supply neither key, behavior is unchanged: Canvas generates both for you.
When to use this:
  - You want the keys to be known and persisted outside Canvas before the namespace exists (for example, a deployment system that needs to seed sibling plugins with the same key without round-tripping through the Admin UI).
  - You're restoring access to a previously-dropped namespace and want to reuse known key values.
  - You want deterministic key values across test runs in CI.
####  Configuring Plugin Access 
Each plugin that joins a namespace must:
  1. **Declare the namespace** in `CANVAS_MANIFEST.json`
  2. **Include the access key name** in the manifest's `variables` array
  3. **Provide the access key** during installation
    ```json
    {
      "variables": [
        {"name": "namespace_read_write_access_key", "sensitive": false}
      ],
      "custom_data": {
        "namespace": "acme_corp__shared_data",
        "access": "read_write"
      }
    }
    ```
> Namespace access keys are declared with `"sensitive": false` so the value remains readable in the Admin UI's Secrets inline — that's the surface developers use to copy a key into a sibling plugin that joins the same namespace.
**Installing with the Canvas CLI:**
Provide the access key using the `--secret` flag:
    ```bash
    canvas install my_plugin \
      --host demo.canvasmedical.com \
      --secret namespace_read_write_access_key=3b35fad9-6462-4e83-83f5-c0e4bde49b71
    ```
**Alternative: Setting secrets via Admin UI:**
If you've already installed the plugin without the secret:
  1. Go to **Settings → Plugins → Your Plugin → Secrets**
  2. Set the `namespace_read_access_key` or `namespace_read_write_access_key` value
  3. **Reinstall the plugin** to pick up the secret
###  Manifest Configuration 
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "1.0.0",
      "name": "acme_corp__my_plugin",
      "custom_data": {
        "namespace": "acme_corp__shared_data",
        "access": "read_write"
      }
    }
    ```
A plugin installed with `canvas install` also declares the access key it is given in `variables`, as shown in Configuring Plugin Access.
**Namespace naming requirements:**
  - Must contain `__` (double underscore) to separate organization from name
  - Cannot use reserved PostgreSQL names (`public`, `pg_catalog`, etc.)
  - Organizations and names must start with a letter
**Access levels:**
  - `read` \- Can only read data from the namespace
  - `read_write` \- Can read and write data, and create custom tables
###  Permissions and Restrictions 
Permission| `read`| `read_write`  
---|---|---  
Query AttributeHubs| ✅| ✅  
Query CustomModels| ✅| ✅  
Create/update/delete AttributeHubs| ❌| ✅  
Create/update/delete CustomModel records| ❌| ✅  
Create/update custom database tables| ❌| ✅  
###  Example: Sharing AttributeHubs 
AttributeHubs store standalone key-value data not attached to Canvas models.
**Plugin A (write access) - Creates configuration hub:**
    ```python
    # CANVAS_MANIFEST.json: "access": "read_write"
    from canvas_sdk.v1.data import AttributeHub
    # Create or retrieve a configuration hub
    config, created = AttributeHub.objects.get_or_create(type="clinic_config", id="main")
    config.set_attribute("max_daily_appointments", 50)
    config.set_attribute("appointment_duration_minutes", 30)
    config.set_attribute("accepting_new_patients", True)
    ```
**Plugin B (read access) - Reads configuration:**
    ```python
    # CANVAS_MANIFEST.json: "access": "read"
    from canvas_sdk.v1.data import AttributeHub
    config = AttributeHub.objects.with_only(
        attribute_names=["max_daily_appointments", "appointment_duration_minutes"]
    ).get(type="clinic_config", id="main")
    max_appointments = config.get_attribute("max_daily_appointments")  # 50
    duration = config.get_attribute("appointment_duration_minutes")  # 30
    ```
###  Example: Sharing CustomModels 
CustomModels allow you to define your own database tables with full ORM support.
**Important:** If multiple plugins need to share the same custom tables, each plugin must declare identical model definitions. The `read_write` plugin creates the tables; `read` plugins can query but not modify them.
**Shared model definition (must be identical in both plugins):**
    ```python
    # models/specialty.py
    from django.db import models
    from canvas_sdk.v1.data.base import CustomModel
    class Specialty(CustomModel):
        """A medical specialty that can be assigned to staff members."""
        name = models.CharField(max_length=100, unique=True)
        description = models.TextField(blank=True)
        requires_referral = models.BooleanField(default=False)
        class Meta:
            indexes = [
                models.Index(fields=['name']),
            ]
    ```
**Plugin A (write access) - Creates and manages specialties:**
    ```python
    # CANVAS_MANIFEST.json: "access": "read_write"
    from .models.specialty import Specialty
    # Create specialties
    cardiology = Specialty(
        name="Cardiology",
        description="Heart and cardiovascular system",
        requires_referral=True
    )
    cardiology.save()
    dermatology = Specialty(
        name="Dermatology",
        description="Skin conditions",
        requires_referral=False
    )
    dermatology.save()
    ```
**Plugin B (read access) - Queries specialties:**
    ```python
    # CANVAS_MANIFEST.json: "access": "read"
    from .models.specialty import Specialty
    # Query specialties (read operations work)
    referral_specialties = Specialty.objects.filter(requires_referral=True)
    for specialty in referral_specialties:
        print(f"{specialty.name}: {specialty.description}")
    # Write operations raise NamespaceWriteDenied
    specialty = Specialty.objects.first()
    specialty.description = "Updated"
    specialty.save()  # Raises NamespaceWriteDenied!
    ```
###  Error Handling 
When a plugin with `read` access attempts a write operation, a `NamespaceWriteDenied` exception is raised:
    ```python
    from canvas_sdk.v1.data.base import NamespaceWriteDenied
    try:
        hub.set_attribute("key", "value")
    except NamespaceWriteDenied as e:
        # "Write operation denied: namespace 'acme_corp__shared_data' is read-only.
        #  Plugin must declare 'read_write' access to perform write operations."
        log.error(f"Cannot write to shared namespace: {e}")
    ```
###  Troubleshooting 
**"NamespaceAccessError: secret 'namespace_read_access_key' is not configured"**
  - Add the secret name to the `secrets` array in your manifest
  - Ensure the secret has a value set in the Canvas UI
**"NamespaceAccessError: the key value is not a valid access key"**
  - Verify you're using the correct key from the namespace owner
  - Check that the key hasn't been regenerated
**"NamespaceAccessError: requests 'read_write' access but key only grants 'read'"**
  - You're using `namespace_read_access_key` but declared `"access": "read_write"`
  - Either change to `namespace_read_write_access_key` or change access to `"read"`
**"NamespaceWriteDenied: namespace is read-only"**
  - Your plugin has `"access": "read"` but is attempting a write operation
  - Change to `"access": "read_write"` and use `namespace_read_write_access_key`
##  API Sharing 
API sharing is the recommended approach when:
  - Plugins are owned by different organizations
  - You want loose coupling between plugins
  - You need fine-grained control over what data is exposed
  - You want to version your data interface independently
###  Example: Exposing Provider Profile Data 
    ```python
    from canvas_sdk.handlers.simple_api import SimpleAPI, APIKeyCredentials, api
    from canvas_sdk.effects.simple_api import JSONResponse
    from canvas_sdk.v1.data import Staff, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import BooleanField, DO_NOTHING, OneToOneField, TextField
    class CustomStaff(Staff, ModelExtension):
        pass
    class StaffProfile(CustomModel):
        staff = OneToOneField(
            CustomStaff, to_field="dbid", on_delete=DO_NOTHING,
            related_name="profile"
        )
        specialty = TextField()
        accepting_patients = BooleanField(default=True)
    class ProfileAPI(SimpleAPI):
        """API to share staff profile data with authorized plugins."""
        PREFIX = "/staff-profiles"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            """Validate API key from requesting plugin."""
            from hmac import compare_digest
            provided_key = credentials.key
            expected_key = self.secrets["profile_api_key"]
            return compare_digest(provided_key.encode(), expected_key.encode())
        @api.get("/<staff_id>")
        def get_profile(self):
            """Return staff profile data."""
            staff_id = self.request.path_params["staff_id"]
            staff = CustomStaff.objects.select_related("profile").get(id=staff_id)
            # Explicitly choose what data to expose
            profile = {
                "staff_id": staff.id,
                "first_name": staff.first_name,
                "last_name": staff.last_name,
                "specialty": staff.profile.specialty,
                "accepting_patients": staff.profile.accepting_patients
            }
            return [JSONResponse(profile)]
    ```
###  Consuming Shared Data from Another Plugin 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Response, JSONResponse
    from canvas_sdk.handlers.simple_api import SimpleAPI, api
    from canvas_sdk.utils import Http
    class MyAPI(SimpleAPI):
        PREFIX = "/retrieve"
        @api.get("/profile_for_staff/<staff_id>")
        def get_single_profile_via_api(self) -> list[Response | Effect]:
            staff_id = self.request.path_params["staff_id"]
            canvas_host = f"{self.environment['CUSTOMER_IDENTIFIER']}.canvasmedical.com"
            token = self.secrets["profile_api_token"]
            other_plugin_api = f"https://{canvas_host}/plugin-io/api/other_plugin/staff-profiles/{staff_id}"
            http = Http()
            response = http.get(other_plugin_api, headers={"Authorization": token})
            return [JSONResponse(response.json())]
    ```
###  API Sharing Best Practices 
  1. **Explicit Authorization** \- Always require authentication for APIs that expose plugin data
  2. **Minimal Exposure** \- Only expose the specific data fields that are necessary
  3. **Validate Requests** \- Check permissions and validate that the requester should have access
  4. **Document APIs** \- Provide clear documentation for plugins that will consume your API
  5. **Version APIs** \- Use versioning (e.g., `/v1/profiles`) to allow API evolution
  6. **Audit Access** \- Log API access for security and debugging purposes
  7. **Rate Limiting** \- Consider implementing rate limits to prevent abuse
###  Security Considerations 
  - **Never bypass plugin isolation** by attempting to access another plugin's database schema directly
  - **Use API keys or tokens** stored in secrets, never hardcoded in plugin code
  - **Implement proper error handling** that doesn't leak sensitive information
  - **Consider PHI implications** when exposing patient-related data via APIs
  - **Follow least privilege** principle - grant minimum necessary access
##  Choosing Between Namespace and API Sharing 
Factor| Namespace Sharing| API Sharing  
---|---|---  
**Ownership**|  Same organization| Different organizations  
**Coupling**|  Tight| Loose  
**Performance**|  Direct DB access| HTTP overhead  
**Schema Evolution**|  Coordinated updates| Independent versioning  
**Access Control**|  Binary (read/read_write)| Fine-grained  
**Setup Complexity**|  Lower| Higher  
##  See Also 
  - [Custom Data Overview](/sdk/custom-data/) \- Introduction to custom data storage
  - [Namespace Lifecycle](/sdk/custom-data-namespace-lifecycle/) \- Managing namespaces during development
  - [AttributeHubs](/sdk/custom-data-attribute-hubs/) \- Standalone key-value storage
  - [CustomModels](/sdk/custom-data-custom-models/) \- Django models for structured data
  - [Testing Utils](/sdk/testing-utils/) \- Factories for testing custom data
  - [Caching API](/sdk/caching) \- Auto-expiring transient data
  - [Simple API](/sdk/handlers-simple-api-http) \- HTTP API handlers
  - [Secrets](/sdk/secrets/) \- Managing API keys and sensitive configuration

---

# Testing Custom Data

Source: https://docs.canvasmedical.com/sdk/custom-data-testing/

The Canvas SDK provides comprehensive testing utilities for custom data. Tests run within database transactions that automatically roll back, ensuring isolation between test cases.
##  Test Setup 
Install the test utilities extra to enable pytest-based testing:
    ```bash
    uv add "canvas[test-utils]"
    ```
Run your tests with:
    ```bash
    uv run pytest
    ```
Each test runs inside a transaction and automatically rolls back at the end, providing clean isolation without manual cleanup.
See [Testing Utilities](/sdk/testing-utils/) for complete setup instructions.
##  Creating Factories for Extended Models 
Define factories for extended models by extending the base SDK factories:
    ```python
    import factory
    from canvas_sdk.test_utils.factories import StaffFactory, PatientFactory
    from staff_plus.models import CustomStaff, CustomPatient
    class CustomStaffFactory(StaffFactory, factory.django.DjangoModelFactory[CustomStaff]):
        """Factory for creating CustomStaff instances."""
        class Meta:
            model = CustomStaff
    class CustomPatientFactory(PatientFactory, factory.django.DjangoModelFactory[CustomPatient]):
        """Factory for creating CustomPatient instances."""
        class Meta:
            model = CustomPatient
    ```
##  Creating Factories for Custom Models 
Define factories for your custom models with appropriate field values:
    ```python
    import factory
    from my_plugin.models import Specialty, StaffSpecialty
    from my_plugin.models import Biography
    class SpecialtyFactory(factory.django.DjangoModelFactory):
        """Factory for creating Specialty instances."""
        class Meta:
            model = Specialty
            django_get_or_create = ("name",)  # Avoid duplicate specialties
        name = factory.Faker("random_element", elements=[
            "Cardiology", "Dermatology", "Neurology", "Orthopedics",
            "Pediatrics", "Psychiatry", "Radiology", "Surgery"
        ])
    class BiographyFactory(factory.django.DjangoModelFactory):
        """Factory for creating Biography instances."""
        class Meta:
            model = Biography
        staff = factory.SubFactory(CustomStaffFactory)
        biography = factory.Faker("paragraph", nb_sentences=5)
        language = factory.Faker("language_name")
        practicing_since = factory.Faker("year")
    class StaffSpecialtyFactory(factory.django.DjangoModelFactory):
        """Factory for many-to-many relationship."""
        class Meta:
            model = StaffSpecialty
        staff = factory.SubFactory(CustomStaffFactory)
        specialty = factory.SubFactory(SpecialtyFactory)
    ```
##  Testing AttributeHub 
Test that AttributeHub stores and retrieves data correctly:
    ```python
    from datetime import datetime
    import factory
    from canvas_sdk.test_utils.factories import StaffFactory
    from canvas_sdk.v1.data import AttributeHub, Staff, ModelExtension
    class CustomStaff(Staff, ModelExtension):
        pass
    class CustomStaffFactory(StaffFactory, factory.django.DjangoModelFactory[CustomStaff]):
        class Meta:
            model = CustomStaff
    def test_attribute_hub_creation():
        """Test creating and using AttributeHub."""
        # Create hub
        hub = AttributeHub.objects.create(
            type="staff_profile",
            id="staff_123"
        )
        # Set attributes
        hub.set_attribute("last_sync", datetime.now())
        hub.set_attribute("external_id", "ext_456")
        # Verify persistence
        hub_from_db = AttributeHub.objects.get(dbid=hub.dbid)
        assert hub_from_db.get_attribute("external_id") == "ext_456"
    def test_attribute_hub_get_or_create():
        """Test get_or_create pattern with AttributeHub."""
        staff = CustomStaffFactory.create()
        # First call creates
        hub1, created1 = AttributeHub.objects.get_or_create(
            type="staff_sync",
            id=f"staff:{staff.id}"
        )
        assert created1 is True
        hub1.set_attribute("data", {"key": "value"})
        # Second call retrieves existing
        hub2, created2 = AttributeHub.objects.get_or_create(
            type="staff_sync",
            id=f"staff:{staff.id}"
        )
        assert created2 is False
        assert hub1.dbid == hub2.dbid
        assert hub2.get_attribute("data") == {"key": "value"}
    def test_attribute_hub_json_storage():
        """Test storing complex JSON in AttributeHub."""
        hub = AttributeHub.objects.create(
            type="profile",
            id="test_123"
        )
        profile_data = {
            "biography": "Experienced physician",
            "specialties": ["Cardiology", "Internal Medicine"],
            "languages": ["English", "Spanish"],
            "practicing_since": 2005,
            "accepting_patients": False
        }
        hub.set_attribute("profile", profile_data)
        hub_from_db = AttributeHub.objects.get(dbid=hub.dbid)
        retrieved = hub_from_db.get_attribute("profile")
        assert retrieved == profile_data
        assert retrieved["biography"] == "Experienced physician"
        assert len(retrieved["specialties"]) == 2
    ```
##  Testing Custom Models 
Test custom model creation, relationships, and queries:
    ```python
    import factory
    from datetime import datetime
    from django.db.models import (
        ForeignKey, ManyToManyField, OneToOneField, TextField, IntegerField,
        DateTimeField, Index, DO_NOTHING
    )
    from canvas_sdk.test_utils.factories import StaffFactory
    from canvas_sdk.v1.data import Staff, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    class CustomStaff(Staff, ModelExtension):
        pass
    class CustomStaffFactory(StaffFactory, factory.django.DjangoModelFactory[CustomStaff]):
        class Meta:
            model = CustomStaff
    class Specialty(CustomModel):
        class Meta:
            indexes = [
                Index(fields=["name"]),
            ]
        name = TextField()
        staff_members = ManyToManyField(
            "CustomStaff",
            through="StaffSpecialty",
            related_name="specialties",
        )
    class Biography(CustomModel):
        staff = OneToOneField(
            CustomStaff,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="biography"
        )
        biography = TextField()
        language = TextField()
        practicing_since = IntegerField()
    class Language(CustomModel):
        staff = ForeignKey(
            CustomStaff,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="languages"
        )
        name = TextField()
        code = TextField()
        created = DateTimeField(default=datetime.now)
    class StaffSpecialty(CustomModel):
        staff = ForeignKey(
            CustomStaff,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="staff_specialties"
        )
        specialty = ForeignKey(
            Specialty,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="staff_specialties"
        )
    def test_custom_model_creation():
        """Test creating custom models."""
        specialty = Specialty.objects.create(name="Cardiology")
        assert specialty.dbid is not None
        assert specialty.name == "Cardiology"
        # Verify persistence
        specialty_from_db = Specialty.objects.get(dbid=specialty.dbid)
        assert specialty_from_db.name == "Cardiology"
    def test_one_to_one_relationship():
        """Test one-to-one relationships."""
        staff = CustomStaffFactory.create()
        # Create related biography
        biography = Biography.objects.create(
            staff=staff,
            biography="Experienced cardiologist",
            language="English",
            practicing_since=2005
        )
        # Access from biography to staff
        assert biography.staff.id == staff.id
        # Access from staff to biography (reverse relation)
        staff_from_db = CustomStaff.objects.get(id=staff.id)
        assert staff_from_db.biography.biography == "Experienced cardiologist"
        assert staff_from_db.biography.practicing_since == 2005
    def test_one_to_many_relationship():
        """Test one-to-many relationships."""
        staff = CustomStaffFactory.create()
        # Create multiple related languages
        Language.objects.create(staff=staff, name="English", code="en")
        Language.objects.create(staff=staff, name="Spanish", code="es")
        Language.objects.create(staff=staff, name="French", code="fr")
        # Access all languages via reverse relation
        languages = staff.languages.all()
        assert languages.count() == 3
        language_names = [lang.name for lang in languages]
        assert "English" in language_names
        assert "Spanish" in language_names
        assert "French" in language_names
    def test_many_to_many_relationship():
        """Test many-to-many relationships via junction table."""
        staff = CustomStaffFactory.create()
        cardiology = Specialty.objects.create(name="Cardiology")
        internal_med = Specialty.objects.create(name="Internal Medicine")
        # Create associations
        StaffSpecialty.objects.create(staff=staff, specialty=cardiology)
        StaffSpecialty.objects.create(staff=staff, specialty=internal_med)
        # Query specialties for staff
        staff_specialties = staff.staff_specialties.all()
        assert staff_specialties.count() == 2
        specialty_names = [ss.specialty.name for ss in staff_specialties]
        assert "Cardiology" in specialty_names
        assert "Internal Medicine" in specialty_names
        # Query staff by specialty
        staff_ids = (
            StaffSpecialty.objects
            .filter(specialty__name="Cardiology")
            .values_list("staff_id", flat=True)
        )
        assert staff.dbid in staff_ids
    def test_many_to_many_query_filtering():
        """Test querying across many-to-many relationships."""
        staff1 = CustomStaffFactory.create()
        staff2 = CustomStaffFactory.create()
        cardiology = Specialty.objects.create(name="Cardiology")
        neurology = Specialty.objects.create(name="Neurology")
        StaffSpecialty.objects.create(staff=staff1, specialty=cardiology)
        StaffSpecialty.objects.create(staff=staff2, specialty=neurology)
        StaffSpecialty.objects.create(staff=staff2, specialty=cardiology)
        # Find all staff with cardiology
        cardiology_staff_ids = (
            StaffSpecialty.objects
            .filter(specialty__name="Cardiology")
            .values_list("staff_id", flat=True)
        )
        assert staff1.dbid in cardiology_staff_ids
        assert staff2.dbid in cardiology_staff_ids
        # Find staff with multiple specialties
        multi_specialty_ids = (
            StaffSpecialty.objects
            .filter(specialty__name__in=["Cardiology", "Neurology"])
            .values_list("staff_id", flat=True)
            .distinct()
        )
        assert len(multi_specialty_ids) == 2
    def test_many_to_many_through_field():
        """Test direct M2M traversal via ManyToManyField(through=...)."""
        staff = CustomStaffFactory.create()
        cardiology = Specialty.objects.create(name="Cardiology")
        internal_med = Specialty.objects.create(name="Internal Medicine")
        StaffSpecialty.objects.create(staff=staff, specialty=cardiology)
        StaffSpecialty.objects.create(staff=staff, specialty=internal_med)
        # Direct M2M traversal — Specialty → staff
        assert staff in cardiology.staff_members.all()
        # Reverse M2M traversal — staff → specialties
        specialty_names = [s.name for s in staff.specialties.all()]
        assert "Cardiology" in specialty_names
        assert "Internal Medicine" in specialty_names
    ```
##  Testing with Factories 
Use factories to simplify test data creation:
    ```python
    import factory
    from django.db.models import OneToOneField, TextField, IntegerField, DO_NOTHING
    from canvas_sdk.test_utils.factories import StaffFactory
    from canvas_sdk.v1.data import Staff, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    class CustomStaff(Staff, ModelExtension):
        pass
    class CustomStaffFactory(StaffFactory, factory.django.DjangoModelFactory[CustomStaff]):
        class Meta:
            model = CustomStaff
    class Biography(CustomModel):
        staff = OneToOneField(
            CustomStaff,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="biography"
        )
        biography = TextField()
        language = TextField()
        practicing_since = IntegerField()
    class BiographyFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = Biography
        staff = factory.SubFactory(CustomStaffFactory)
        biography = factory.Faker("paragraph", nb_sentences=5)
        language = factory.Faker("language_name")
        practicing_since = factory.Faker("year")
    def test_with_factories():
        """Test using factories for quick data setup."""
        # Create staff with biography using factories
        biography = BiographyFactory.create()
        assert biography.staff is not None
        assert biography.biography is not None
        assert biography.practicing_since is not None
        # Factory automatically created the related staff
        staff = biography.staff
        assert staff.first_name is not None
    class StaffSpecialty(CustomModel):
        staff = ForeignKey(
            CustomStaff,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="staff_specialties"
        )
        specialty = ForeignKey(
            Specialty,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="staff_specialties"
        )
    class StaffSpecialtyFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = StaffSpecialty
        staff = factory.SubFactory(CustomStaffFactory)
        specialty = factory.SubFactory(SpecialtyFactory)
    def test_many_to_many_with_factories():
        """Test many-to-many relationships with factories."""
        # Create staff-specialty associations
        ss1 = StaffSpecialtyFactory.create()
        ss2 = StaffSpecialtyFactory.create(staff=ss1.staff)  # Same staff, different specialty
        # Verify relationships
        assert ss1.staff.staff_specialties.count() == 2
    ```
##  Testing Queries and Prefetching 
Test that prefetching and query optimization work correctly:
    ```python
    import factory
    from django.db.models import (
        ForeignKey, OneToOneField, TextField, IntegerField,
        Index, DO_NOTHING, Count
    )
    from canvas_sdk.test_utils.factories import StaffFactory
    from canvas_sdk.v1.data import AttributeHub, Staff, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    class CustomStaff(Staff, ModelExtension):
        pass
    class CustomStaffFactory(StaffFactory, factory.django.DjangoModelFactory[CustomStaff]):
        class Meta:
            model = CustomStaff
    class Biography(CustomModel):
        staff = OneToOneField(
            CustomStaff,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="biography"
        )
        biography = TextField()
        practicing_since = IntegerField()
    class Specialty(CustomModel):
        class Meta:
            indexes = [
                Index(fields=["name"]),
            ]
        name = TextField()
    class StaffSpecialty(CustomModel):
        staff = ForeignKey(
            CustomStaff,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="staff_specialties"
        )
        specialty = ForeignKey(
            Specialty,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="staff_specialties"
        )
    class BiographyFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = Biography
        staff = factory.SubFactory(CustomStaffFactory)
        biography = factory.Faker("paragraph")
        practicing_since = factory.Faker("year")
    class SpecialtyFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = Specialty
        name = factory.Faker("word")
    class StaffSpecialtyFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = StaffSpecialty
        staff = factory.SubFactory(CustomStaffFactory)
        specialty = factory.SubFactory(SpecialtyFactory)
    def test_attribute_hub_prefetch():
        """Test prefetching AttributeHub attributes."""
        hub1 = AttributeHub.objects.create(type="profile", id="staff_1")
        hub2 = AttributeHub.objects.create(type="profile", id="staff_2")
        hub1.set_attribute("specialty", "Cardiology")
        hub2.set_attribute("specialty", "Neurology")
        # Query with automatic prefetch (default behavior)
        hubs = AttributeHub.objects.filter(type="profile")
        # Access attributes without additional queries
        for hub in hubs:
            specialty = hub.get_attribute("specialty")
            assert specialty in ["Cardiology", "Neurology"]
    def test_attribute_hub_with_only():
        """Test selective attribute prefetching on AttributeHub."""
        hub = AttributeHub.objects.create(type="profile", id="staff_1")
        hub.set_attributes({
            "specialty": "Cardiology",
            "years_experience": 15,
            "accepting_patients": True
        })
        # Prefetch only specific attributes
        hub_from_db = (
            AttributeHub.objects
            .with_only(["specialty", "accepting_patients"])
            .get(dbid=hub.dbid)
        )
        # Prefetched attributes accessible
        assert hub_from_db.get_attribute("specialty") == "Cardiology"
        assert hub_from_db.get_attribute("accepting_patients") is True
    def test_relationship_prefetch():
        """Test prefetching related models."""
        staff1 = CustomStaffFactory.create()
        staff2 = CustomStaffFactory.create()
        BiographyFactory.create(staff=staff1)
        BiographyFactory.create(staff=staff2)
        cardiology = SpecialtyFactory.create(name="Cardiology")
        StaffSpecialtyFactory.create(staff=staff1, specialty=cardiology)
        StaffSpecialtyFactory.create(staff=staff2, specialty=cardiology)
        # Prefetch all relationships
        all_staff = (
            CustomStaff.objects
            .prefetch_related("biography")
            .prefetch_related("staff_specialties__specialty")
            .all()
        )
        # Access without additional queries
        for staff in all_staff:
            bio = staff.biography.biography
            specialties = [ss.specialty.name for ss in staff.staff_specialties.all()]
            assert bio is not None
            assert len(specialties) > 0
    def test_select_related():
        """Test select_related for FK and OneToOne joins."""
        staff = CustomStaffFactory.create()
        BiographyFactory.create(staff=staff)
        StaffSpecialtyFactory.create(staff=staff)
        # select_related eagerly loads FK/O2O relations in a single query
        specialty_assoc = (
            StaffSpecialty.objects
            .select_related("staff", "specialty")
            .filter(staff=staff)
            .first()
        )
        assert specialty_assoc.staff.first_name is not None
        assert specialty_assoc.specialty.name is not None
    ```
##  Testing Data Integrity 
Test data validation, constraints, and cascade behavior:
    ```python
    from datetime import datetime
    import factory
    import pytest
    from django.db import IntegrityError
    from django.db.models import (
        CASCADE, DateTimeField, ForeignKey, TextField, Index,
        UniqueConstraint, DO_NOTHING
    )
    from canvas_sdk.test_utils.factories import StaffFactory
    from canvas_sdk.v1.data import AttributeHub, Staff, ModelExtension
    from canvas_sdk.v1.data.base import CustomModel
    class CustomStaff(Staff, ModelExtension):
        pass
    class CustomStaffFactory(StaffFactory, factory.django.DjangoModelFactory[CustomStaff]):
        class Meta:
            model = CustomStaff
    class Specialty(CustomModel):
        class Meta:
            indexes = [
                Index(fields=["name"]),
            ]
        name = TextField()
    class SpecialtyFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = Specialty
        name = factory.Faker("word")
    class StaffSpecialty(CustomModel):
        staff = ForeignKey(
            CustomStaff,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="staff_specialties"
        )
        specialty = ForeignKey(
            Specialty,
            to_field="dbid",
            on_delete=DO_NOTHING,
            related_name="staff_specialties"
        )
    class StaffSpecialtyFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = StaffSpecialty
        staff = factory.SubFactory(CustomStaffFactory)
        specialty = factory.SubFactory(SpecialtyFactory)
    class Team(CustomModel):
        class Meta:
            constraints = [
                UniqueConstraint(fields=["name"], name="unique_team_name"),
            ]
        name = TextField()
    class TeamMember(CustomModel):
        class Meta:
            constraints = [
                UniqueConstraint(
                    fields=["team", "staff"],
                    name="unique_team_staff",
                ),
            ]
        team = ForeignKey(Team, to_field="dbid", on_delete=CASCADE, related_name="members")
        staff = ForeignKey(
            CustomStaff, to_field="dbid", on_delete=DO_NOTHING, related_name="team_memberships"
        )
        joined_at = DateTimeField()
    class TeamFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = Team
        name = factory.Sequence(lambda n: f"Team {n + 1}")
    class TeamMemberFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = TeamMember
        team = factory.SubFactory(TeamFactory)
        staff = factory.SubFactory(CustomStaffFactory)
        joined_at = factory.LazyFunction(datetime.now)
    def test_manual_cleanup_on_delete():
        """Test manual cleanup for DO_NOTHING foreign keys.
        ForeignKeys to SDK models (Staff, Patient, etc.) must use DO_NOTHING
        because those tables are managed externally. Related records must be
        deleted manually before deleting the parent.
        """
        staff = CustomStaffFactory.create()
        specialty = SpecialtyFactory.create()
        ss = StaffSpecialtyFactory.create(staff=staff, specialty=specialty)
        # With DO_NOTHING, you must clean up related records manually
        specialty_id = specialty.dbid
        StaffSpecialty.objects.filter(specialty_id=specialty_id).delete()
        specialty.delete()
        # Verify both are gone
        assert not StaffSpecialty.objects.filter(specialty_id=specialty_id).exists()
        assert not Specialty.objects.filter(dbid=specialty_id).exists()
    def test_cascade_delete():
        """Test CASCADE deletion between custom models.
        ForeignKeys between your own CustomModels can use CASCADE to
        automatically delete related records.
        """
        team = TeamFactory.create()
        TeamMemberFactory.create(team=team)
        TeamMemberFactory.create(team=team)
        assert TeamMember.objects.filter(team=team).count() == 2
        # Deleting the team cascades to members
        team.delete()
        assert not TeamMember.objects.filter(team=team).exists()
    def test_unique_constraint_violation():
        """Test that UniqueConstraint prevents duplicate records."""
        team = TeamFactory.create()
        staff = CustomStaffFactory.create()
        TeamMember.objects.create(team=team, staff=staff, joined_at=datetime.now())
        # Same team + staff violates the UniqueConstraint
        with pytest.raises(IntegrityError):
            TeamMember.objects.create(team=team, staff=staff, joined_at=datetime.now())
    def test_attribute_hub_upsert():
        """Test that set_attribute updates existing values rather than creating duplicates."""
        hub = AttributeHub.objects.create(type="test", id="upsert_test")
        # Set attribute
        hub.set_attribute("field", "value1")
        # Setting same attribute name should update, not create duplicate
        hub.set_attribute("field", "value2")
        # Verify only the updated value exists
        hub_from_db = AttributeHub.objects.get(dbid=hub.dbid)
        assert hub_from_db.get_attribute("field") == "value2"
    def test_transaction_rollback():
        """Verify that tests automatically roll back."""
        # This test demonstrates automatic rollback
        # Data created here won't exist in subsequent tests
        staff = CustomStaffFactory.create()
        staff_id = staff.id
        specialty = SpecialtyFactory.create(name="Test Specialty")
        # After this test, these objects won't exist in other tests
        # due to automatic transaction rollback
        assert staff_id is not None
        assert specialty.name == "Test Specialty"
    ```
##  Testing proxy_field 
The `proxy_field` descriptor lets a `ModelExtension` proxy transparently return another proxy class from a ForeignKey lookup, so you can access custom methods on related objects:
    ```python
    from canvas_sdk.v1.data import Note, Patient, Staff, ModelExtension
    from canvas_sdk.v1.data.base import proxy_field
    from canvas_sdk.test_utils.factories import NoteFactory
    class CustomPatient(Patient, ModelExtension):
        @property
        def display_name(self) -> str:
            return f"{self.first_name} {self.last_name}"
    class CustomNote(Note, ModelExtension):
        # Without proxy_field, accessing note.patient returns a plain Patient.
        # With proxy_field, it returns a CustomPatient instead.
        patient = proxy_field(CustomPatient)
    def test_proxy_field_returns_proxy_class():
        """proxy_field swaps __class__ so the returned object is CustomPatient."""
        note = NoteFactory.create()
        custom_note = CustomNote.objects.select_related("patient").get(dbid=note.dbid)
        # The patient is a CustomPatient, not a plain Patient
        assert type(custom_note.patient) is CustomPatient
        assert custom_note.patient.display_name == (
            f"{note.patient.first_name} {note.patient.last_name}"
        )
    def test_proxy_field_handles_null():
        """proxy_field returns None when the FK is null."""
        note = NoteFactory.create(patient=None)
        custom_note = CustomNote.objects.get(dbid=note.dbid)
        assert custom_note.patient is None
    ```
##  Testing Best Practices 
  1. **Use factories** for consistent test data generation
  2. **Test isolation** \- Each test should be independent and not rely on data from other tests
  3. **Test both directions** of relationships (forward and reverse)
  4. **Verify persistence** by reloading objects from the database
  5. **Test edge cases** like None values, empty lists, and missing relationships
  6. **Use descriptive test names** that explain what is being tested
  7. **Test query optimization** to ensure prefetching works as expected
  8. **Verify constraints** like uniqueness behavior
  9. **Choose the right`on_delete`** \- ForeignKeys to SDK models (Staff, Patient, etc.) must use `DO_NOTHING` and related records must be deleted manually. ForeignKeys between your own CustomModels can use `CASCADE` for automatic cleanup
##  See Also 
  - [Custom Data Overview](/sdk/custom-data/) \- Introduction to custom data storage
  - [CustomModels](/sdk/custom-data-custom-models/) \- Django models for structured data
  - [AttributeHubs](/sdk/custom-data-attribute-hubs/) \- Standalone key-value storage
  - [Sharing Data](/sdk/custom-data-sharing-data/) \- Sharing data among plugins
  - [Caching API](/sdk/caching) \- Auto-expiring transient data

---

# Transactions

Source: https://docs.canvasmedical.com/sdk/custom-data-transactions/

##  Overview 
By default, each ORM operation in a plugin (`.save()`, `.create()`, `.update()`, `.delete()`) is committed to the database immediately. There is no automatic transaction wrapping your handler or protocol — if you perform three writes and the third one fails, the first two are already committed.
When you need multiple operations to succeed or fail together, use `transaction.atomic()`.
* * *
##  Using `transaction.atomic()`
Wrap related operations in an `atomic()` block to ensure all-or-nothing behavior:
    ```python
    from django.db.transaction import atomic
    with atomic():
        # All operations inside this block are part of a single transaction.
        # If any operation raises an exception, everything is rolled back.
        specialty, _ = Specialty.objects.get_or_create(name="Cardiology")
        StaffSpecialty.objects.filter(staff=staff).delete()
        StaffSpecialty.objects.bulk_create([
            StaffSpecialty(staff=staff, specialty=specialty)
        ])
        Biography.objects.create(staff=staff, biography="...")
    ```
If an exception occurs anywhere inside the block, all changes are rolled back — the database is left as it was before the block started.
* * *
##  When to Use Transactions 
Use `transaction.atomic()` when your handler performs **multiple related writes** that should not be partially applied:
  - **Replacing associations** — deleting existing records and creating new ones (e.g., replacing a staff member's specialties). Without a transaction, a failure after the delete leaves the staff member with no specialties.
  - **Creating a parent and its children** — e.g., creating a `Biography` and several `Language` records in one request. A partial failure could leave orphaned or incomplete data.
  - **Coordinated updates** — updating multiple models that must stay consistent with each other.
You do **not** need a transaction for:
  - A single `.create()`, `.save()`, or `.update()` call — these are already atomic on their own.
  - Read-only operations — `SELECT` queries don't modify data.
* * *
##  Example: Multi-Model Upsert 
This example accepts a JSON payload and upserts a staff profile spanning multiple CustomModels. The `atomic()` block ensures that either the entire profile is saved or nothing is:
    ```python
    from django.db.transaction import atomic
    from canvas_sdk.effects.simple_api import JSONResponse
    from canvas_sdk.handlers.simple_api import SimpleAPI, api
    class ProfileAPI(SimpleAPI):
        PREFIX = "/profile"
        @api.post("/v2/<staff_id>")
        def post_profile(self):
            with atomic():
                staff_id = self.request.path_params["staff_id"]
                json_body = self.request.json()
                staff = CustomStaff.objects.get(id=staff_id)
                # Upsert languages
                for name in json_body.get("languages", []):
                    Language.objects.get_or_create(name=name, staff=staff)
                # Replace specialty associations
                specialties = []
                for name in json_body.get("specialties", []):
                    specialty, _ = Specialty.objects.get_or_create(name=name)
                    specialties.append(specialty)
                StaffSpecialty.objects.filter(staff=staff).delete()
                StaffSpecialty.objects.bulk_create([
                    StaffSpecialty(staff=staff, specialty=s) for s in specialties
                ])
                # Upsert biography
                biography_text = json_body.get("biography")
                Biography.objects.update_or_create(
                    staff=staff,
                    defaults={
                        "biography": biography_text,
                        "practicing_since": json_body.get("practicing_since"),
                        "is_accepting_patients": json_body.get("accepting_patients"),
                    },
                )
            return [JSONResponse({"status": "ok"})]
    ```
If any operation inside the `atomic()` block raises an exception — a constraint violation, an unexpected data type, a model validation error — the entire block is rolled back and no partial data is written.
* * *
##  How It Works 
Plugin code runs inside a database context that sets the PostgreSQL `search_path` to the plugin's namespace. `transaction.atomic()` operates on this same connection automatically — no `using=` parameter is needed.
Under the hood, `atomic()` issues a `SAVEPOINT` (for nested usage) or manages the transaction directly. When the block exits cleanly, the transaction is committed. When an exception propagates out, it is rolled back.
* * *
##  Nesting 
`atomic()` blocks can be nested. Inner blocks use PostgreSQL savepoints, so a failure in an inner block rolls back only that block's changes (not the entire outer transaction), provided you catch the exception:
    ```python
    from django.db.transaction import atomic
    with atomic():
        Specialty.objects.create(name="Cardiology")
        try:
            with atomic():
                Specialty.objects.create(name="Neurology")
                raise ValueError("something went wrong")
        except ValueError:
            pass  # Only the "Neurology" insert is rolled back
        # "Cardiology" is still pending and will be committed
    ```
If the exception is **not** caught, it propagates to the outer block and rolls back everything.
* * *
##  See Also 
  - [CustomModels](/sdk/custom-data-custom-models/) \- Defining structured models, relationships, and queries
  - [AttributeHubs](/sdk/custom-data-attribute-hubs/) \- Standalone key-value storage
  - [Design Considerations](/sdk/custom-data-design-considerations/) \- Choosing the right technique and avoiding anti-patterns
  - [Testing Custom Data](/sdk/custom-data-testing/) \- Testing utilities and examples

---

# Custom Data

Source: https://docs.canvasmedical.com/sdk/custom-data/

##  Overview 
The Canvas SDK provides two techniques for storing custom data in your plugins, allowing you to define fully structured data models with relationships among entities, or create flexible key-value stores:
  1. **[CustomModels](/sdk/custom-data-custom-models/)** \- Build your own data model or expand the Canvas data model by adding fully structured tables with typed fields, relationships, and indexes
  2. **[AttributeHubs](/sdk/custom-data-attribute-hubs/)** \- Store arbitrary key-value pairs and JSON data independently of the Canvas data model
Each technique serves different use cases and provides different levels of structure and type safety. Both techniques may be used together.
##  When to Use Each Technique 
###  CustomModels 
Use this when you need structured, typed data with relationships and normalized data. CustomModels can also extend existing SDK models (like Patient or Staff) with custom fields via `OneToOneField`, `ForeignKey`, and `ManyToManyField`.
**Best for:**
  - Structured data with a stable, known schema
  - Custom fields on existing SDK models (e.g., provider preferences, patient flags)
  - Relationships between entities (foreign keys, join tables)
  - Data requiring compound filtering, sorting, or aggregation
  - Data consumed by reports or analytics
**Example use cases:**
  - Provider specialties and certifications
  - Adding practice-specific fields to patients or staff
  - Linking `Staff` to `Note` creating a `supervising_provider` association
  - Custom workflows and forms
  - Integration-specific data structures
  - Practice-specific business operation concepts and logic
[Learn more about CustomModels →](/sdk/custom-data-custom-models/)
###  AttributeHubs 
AttributeHubs provide a key/value and document store free from the burden of defining any schema or linking to Canvas models. They are for storing irregular or unstructured information that doesn't have a natural home. Whereas CustomModels build upon the Canvas data model, AttributeHubs allow easy, standalone persistence of information. Use this when you need to store data that doesn't naturally belong to any existing or imagined model.
**Best for:**
  - Cross-cutting state that spans multiple models (sync cursors, external IDs)
  - One-off or small-collection configuration and state
  - Data with no natural schema (varying fields per record)
  - External system state tracking
**Example use cases:**
  - API synchronization state
  - External system identifiers
  - Plugin configuration and feature flags
[Learn more about AttributeHubs →](/sdk/custom-data-attribute-hubs/)
For help choosing between these techniques, see [Design Considerations](/sdk/custom-data-design-considerations/). For details on how multiple plugins can share a namespace using these keys, see the [Sharing Data](/sdk/custom-data-sharing-data/) guide. For managing API tokens and other sensitive configuration, see [Managing Secrets](/sdk/secrets/).
##  Caching 
If your use case represents transient data that should expire via TTL, use the [Caching API](/sdk/caching) instead of the Custom Data features.
##  Data Privacy and Plugin Isolation 
All custom data created by a plugin — whether using CustomModels or AttributeHubs — is scoped to a namespace. This isolation ensures that plugins cannot directly access or modify another plugin's data, maintaining security and data integrity across the system.
Plugins may share data in two ways:
  - By explicit co-location within a namespace, allowing direct database access
  - By publishing [Simple API](/sdk/handlers-simple-api-http) endpoints
[Learn more about data sharing](/sdk/custom-data-sharing-data)
###  Data Isolation 
**CustomModels** created by a plugin exist within namespaces. Tables and data are completely isolated from other namespaces.
    ```python
    # In a plugin named "my_plugin": Creates a table "specialty" in the "my_plugin" namespace
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import TextField
    class Specialty(CustomModel):
        name = TextField()
    ```
    ```python
    # In a plugin named "your_plugin": Creates a table "specialty" in the "your_plugin" namespace
    from canvas_sdk.v1.data.base import CustomModel
    from django.db.models import TextField
    class Specialty(CustomModel):
        name = TextField()
    # In "your_plugin": Cannot access the "my_plugin" Specialty model or data
    ```
**AttributeHubs** similarly store data within the plugin's namespace and are not accessible to plugins in other namespaces.
##  Testing Custom Data 
The Canvas SDK provides comprehensive testing utilities for all custom data approaches. See the [Testing Custom Data](/sdk/custom-data-testing/) guide for detailed examples and best practices.
##  Sharing Data 
Use APIs to make data available and accessible to and from other plugins and external services. See the [Sharing Data](/sdk/custom-data-sharing-data/) guide for detailed examples and best practices.
##  Read Replica Databases 
All the data managed by plugin is available via the database read replica. To access it, alter the PostgreSQL [search_path](https://www.postgresql.org/docs/18/ddl-schemas.html#DDL-SCHEMAS-PATH) to include the namespaces that you intend to query.
##  Limitations (for Safety) 
  - Values stored in `text` and `json` fields may not exceed 1mb as measured by character count. Going over raises `FieldValueTooLarge`.
  - Bulk operations (e.g., `bulk_create`) are limited to 10,000 records at a time. Going over raises `BulkOperationTooLarge`.
Both are subclasses of `ValueError`, so a single `except ValueError:` catches either.
##  See Also 
  - [CustomModels](/sdk/custom-data-custom-models/) \- Structured models with relationships among entities
  - [Extending SDK Models](/sdk/custom-data-extending-sdk-models/) \- Proxy models, `related_name` namespacing, and referencing SDK models
  - [AttributeHubs](/sdk/custom-data-attribute-hubs/) \- Standalone key-value storage
  - [Design Considerations](/sdk/custom-data-design-considerations/) \- Choosing the right technique and avoiding anti-patterns
  - [Transactions](/sdk/custom-data-transactions/) \- All-or-nothing writes with `transaction.atomic()`
  - [Testing Custom Data](/sdk/custom-data-testing/) \- Testing utilities and examples
  - [Sharing Data](/sdk/custom-data-sharing-data/) \- Sharing data with other plugins and external services
  - [Data Models](/sdk/data/) \- Core SDK data models
  - [Caching API](/sdk/caching) \- Auto-expiring transient data
  - [Simple API](/sdk/handlers-simple-api/) \- Simple API for sharing data between plugins
  - [Secrets](/sdk/secrets/) \- Managing API keys and sensitive configuration

---

# AllergyIntolerance

Source: https://docs.canvasmedical.com/sdk/data-allergy-intolerance/

##  Introduction 
The `AllergyIntolerance` model represents a known risk, specific to a patient, of a harmful or undesirable physiological response associated with exposure to a substance.
##  Basic usage 
To get an allergy intolerance by identifier, use the `get` method on the `AllergyIntolerance` model manager:
    ```python
    from canvas_sdk.v1.data.allergy_intolerance import AllergyIntolerance
    allergy = AllergyIntolerance.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the allergy intolerances for a patient can be accessed with the `allergy_intolerances` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    allergies = patient.allergy_intolerances.all()
    ```
If you have a patient ID, you can get the allergies for the patient with the `for_patient` method on the `AllergyIntolerance` model manager:
    ```python
    from canvas_sdk.v1.data.allergy_intolerance import AllergyIntolerance
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    allergies = AllergyIntolerance.objects.for_patient(patient_id)
    ```
##  Codings 
The codings for an allergy intolerance can be accessed with the `codings` attribute on an `AllergyIntolerance` object:
    ```python
    from canvas_sdk.v1.data.allergy_intolerance import AllergyIntolerance
    from logger import log
    allergy = AllergyIntolerance.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in allergy.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
##  Filtering 
Allergy intolerances can be filtered by any attribute that exists on the model.
Filtering for allergy intolerances is done with the `filter` method on the `AllergyIntolerance` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.allergy_intolerance import AllergyIntolerance
    allergies = AllergyIntolerance.objects.filter(status="active")
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The `find` method on the model manager is used to perform `ValueSet` filtering:
    ```python
    from canvas_sdk.v1.data.allergy_intolerance import AllergyIntolerance
    from canvas_sdk.value_set.v2022.allergy import EggSubstance
    allergies = AllergyIntolerance.objects.find(EggSubstance)
    ```
##  Attributes 
###  AllergyIntolerance 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note_id| Integer  
allergy_intolerance_type| String  
category| Integer  
status| String  
severity| String  
onset_date| Date  
onset_date_original_input| String  
last_occurrence| Date  
last_occurrence_original_input| String  
recorded_date| DateTime  
narrative| String  
codings| AllergyIntoleranceCoding[]  
remove_allergy_events| [RemoveAllergyEvent](/sdk/data-remove-allergy-event/#removeallergyevent)[]  
###  AllergyIntoleranceCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
allergy_intolerance| AllergyIntolerance  

---

# Application

Source: https://docs.canvasmedical.com/sdk/data-application/

##  Introduction 
The `Application` model represents a plugin Application in Canvas. Applications are used to integrate third-party tools and services into the Canvas platform, allowing users to access external resources and functionalities directly from within Canvas. Each application has a unique identifier, name and description.
##  Basic usage 
To get an application by identifier, use the `get` method on the `Application` model manager:
    ```python
    from canvas_sdk.v1.data import Application
    application = Application.objects.get(identifier="123")
    ```
##  Filtering 
Applications can be filtered by any attribute that exists on the model.
Filtering for applications is done with the `filter` method on the `Application` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data import Application
    applications = Application.objects.filter(name="application name")
    ```
##  Attributes 
###  Application 
Field Name| Type  
---|---  
identifier| str  
name| str  
description| str  
created| datetime  
modified| datetime

---

# Appointment

Source: https://docs.canvasmedical.com/sdk/data-appointment/

##  Introduction 
The `Appointment` model represents a single scheduled meeting from a patient, that may be in the future or past.
##  Basic usage 
To get an appointment by identifier, use the `get` method on the `Appointment` model manager:
    ```python
    from canvas_sdk.v1.data.appointment import Appointment
    appointment = Appointment.objects.get(id="f53626e4-0683-43ac-a1b7-c52815639ce2")
    ```
If you have a patient object, the appointments for a patient can be accessed with the `appointments` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    appointments = patient.appointments.all()
    ```
To get appointments part of a recurrence.
    ```python
    from canvas_sdk.v1.data.appointment import Appointment
    appointment = Appointment.objects.get(id="f53626e4-0683-43ac-a1b7-c52815639ce2")
    # parent appointment
    parent_appointment = appointment.parent_appointment
    # children appointments
    children = parent_appointment.children.all()
    ```
##  Getting the reason for visit 
The reason for visit is recorded on the appointment's note, not on the `Appointment` itself. Read the note's [`ReasonForVisit`](/sdk/data-reason-for-visit/) records through its `reasons_for_visit` attribute. The Reason for Visit command has no commit step, so read the records directly rather than filtering for committed ones:
    ```python
    from canvas_sdk.v1.data.appointment import Appointment
    appointment = Appointment.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    if appointment.note:
        reasons = appointment.note.reasons_for_visit.all()
    ```
##  Detecting rescheduled appointments 
What a reschedule looks like to a plugin depends on the operation used to move the appointment rather than on the surface the request came from. There are two shapes, and a plugin that needs to catch every reschedule has to handle both.
**Cancel and create** fires both [`APPOINTMENT_RESCHEDULED`](/sdk/events/#appointments) and `APPOINTMENT_CREATED`, each targeting the newly created appointment. The original appointment's status is set to cancelled, and the new appointment's `appointment_rescheduled_from` points back at it. This is what happens with:
  - The reschedule flow in the provider UI.
  - The reschedule flow in the patient portal.
  - The [Appointment effect](/sdk/effect-notes/#reschedule-appointment)'s `reschedule()`.
Listen for `APPOINTMENT_RESCHEDULED` rather than handling `APPOINTMENT_CREATED` and filtering on `appointment_rescheduled_from`. The purpose-built event already draws that distinction.
**Update in place** fires only [`APPOINTMENT_UPDATED`](/sdk/events/#appointments). A single appointment record is modified, nothing is cancelled, no new appointment appears, and `APPOINTMENT_RESCHEDULED` does not fire even though the appointment moved to a different time. This is what happens with:
  - The [Appointment effect](/sdk/effect-notes/#update-appointment)'s `update()` carrying a new `start_time`.
  - A FHIR API appointment update, which changes the appointment's attributes to comply with FHIR.
The SDK can produce either shape, so which one your plugin sees depends on what the calling code chose. A plugin that has to catch every move of an appointment needs to handle both `APPOINTMENT_RESCHEDULED` and `APPOINTMENT_UPDATED`.
##  Filtering 
Appointments can be filtered by any attribute that exists on the model.
Filtering for appointments is done with the `filter` method on the `Appointment` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.appointment import Appointment, AppointmentProgressStatus
    appointments = Appointment.objects.filter(status=AppointmentProgressStatus.CONFIRMED)
    ```
###  Filtering by External Identifiers 
To query Appointments by external identifiers, the `external_identifiers` relation can be used with double-underscores to identify values stored on the AppointmentExternalIdentifier model. For example:
    ```python
    from canvas_sdk.v1.data.appointment import Appointment
    appointment = Appointment.objects.filter(
        external_identifiers__system="COMPANY_IDENTIFIER",
        external_identifiers__value="ejNoTa5vKzoT9oSjg87MVB").first()
    ```
##  Attributes 
###  Appointment 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
appointment_rescheduled_from| Appointment  
parent_appointment| Appointment  
provider| Staff  
start_time| DateTime  
duration_minutes| Integer  
comment| String  
note_id| Integer  
note_type_id| Integer  
status| String  
meeting_link| URL  
telehealth_instructions_sent| Boolean  
location| PracticeLocation  
description| String  
external_identifiers| AppointmentExternalIdentifier[]  
metadata| AppointmentMetadata[]  
children| Appointment[]  
appointment_rescheduled_to| Appointment[]  
labels| [TaskLabel](/sdk/data-task/#tasklabel)[]  
###  AppointmentExternalIdentifier 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
use| String  
identifier_type| String  
system| String  
value| String  
issued_date| Date  
expiration_date| Date  
appointment| Appointment  
###  AppointmentLabel 
The join between an appointment and a [TaskLabel](/sdk/data-task/#tasklabel). Reach the labels on an appointment through its `labels` attribute rather than querying this model.
Field Name| Type  
---|---  
dbid| Integer  
appointment| Appointment  
task_label| [TaskLabel](/sdk/data-task/#tasklabel)  
###  AppointmentMetadata 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
appointment| Appointment  
key| String  
value| String  
    ```python
    from canvas_sdk.v1.data.appointment import Appointment
    from logger import log
    appointment_id = "f53626e4-0683-43ac-a1b7-c52815639ce2"
    appointment = Appointment.objects.get(id=appointment_id)
    appointment_metadata = appointment.metadata.all()
    for metadata in appointment_metadata:
       log.info(f"Appointment metadata: {metadata.key}, {metadata.value}")
    ```

---

# Assessment

Source: https://docs.canvasmedical.com/sdk/data-assessment/

##  Introduction 
The `Assessment` model represents a clinical assessment or evaluation of a patient's medical `Condition`.
##  Basic usage 
To get an assessment by identifier, use the `get` method on the `Assessment` model manager:
    ```python
    from canvas_sdk.v1.data.assessment import Assessment
    assessment = Assessment.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the assessments for a patient can be accessed with the `assessments` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    assessments = patient.assessments.all()
    ```
##  Filtering 
Assessments can be filtered by any attribute that exists on the model.
Filtering for assessments is done with the `filter` method on the `Assessment` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.assessment import Assessment, AssessmentStatus
    assessments = Assessment.objects.filter(patient__id="1eed3ea2a8d546a1b681a2a45de1d790", status=AssessmentStatus.STATUS_IMPROVING)
    ```
###  Committed assessments 
The `committed` method returns assessments that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.assessment import Assessment
    committed_assessments = Assessment.objects.committed()
    ```
##  Attributes 
###  Assessment 
Field Name| Type|   
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
originator| [CanvasUser](/sdk/data-canvasuser)|   
entered_in_error| [CanvasUser](/sdk/data-canvasuser)|   
committer| [CanvasUser](/sdk/data-canvasuser)|   
patient| [Patient](/sdk/data-patient/#patient)|   
note| [Note](/sdk/data-note/#note)|   
condition| [Condition](/sdk/data-condition/#condition)|   
interview| [Interview](/sdk/data-questionnaire/#interview)|   
status| AssessmentStatus|   
narrative| String|   
background| String|   
care_team| String|   
treatments_stated| [MedicationStatement](/sdk/data-medication-statement)[]|   
billinglineitem_set| [BillingLineItem](/sdk/data-billing-line-item)[]|   
referrals| [Referral](/sdk/data-referral)[]|   
###  Commands linked to an assessment 
Plan- and Procedures-section commands, and the order, medication, and educational material commands, can be linked to an assessment made in the same note. The command holds the link on its own `assessment` field, and each accessor below reads the link back from the assessment's side.
A link only joins a command and an assessment in the same note. When a command moves to another note without its assessment, or an assessment moves without the commands linked to it, Canvas clears those links. A command and its assessment that move together stay linked. [Carrying a command forward](/sdk/commands/#command-actions) into a new note copies its data but not its link, so the new command starts with no `assessment`.
Linking a prescription or an order also adds the assessed condition to the command's diagnosis codes. Each command's `assessment_id` parameter in the [commands module](/sdk/commands/) gives the details. Clearing the link leaves those codes in place.
On an instance in the [revamped note beta program](/product-updates/note-revamp/), a [printed note](/sdk/commands/#command-actions) in the revamped format lists each linked command indented under its assessment.
Field Name| Type  
---|---  
follow_ups| [FollowUp](/sdk/data-follow-up/#followup)[]  
goals| [Goal](/sdk/data-goal/#goal)[]  
immunizations| [Immunization](/sdk/data-immunization/#immunization)[]  
instructions| [Instruction](/sdk/data-instruction/#instruction)[]  
linked_change_medications| [ChangeMedication](/sdk/data-change-medication/#changemedication)[]  
linked_dme_orders| [DmeOrder](/sdk/data-dme/#dmeorder)[]  
linked_educational_materials| [EducationalMaterial](/sdk/data-educational-material/#educationalmaterial)[]  
linked_imaging_orders| [ImagingOrder](/sdk/data-imaging/#imagingorder)[]  
linked_lab_orders| [LabOrder](/sdk/data-labs/#laborder)[]  
linked_prescriptions| [Prescription](/sdk/data-prescription/#prescription)[]  
linked_referrals| [Referral](/sdk/data-referral/#referral)[]  
note_tasks| [NoteTask](/sdk/data-task/#notetask)[]  
plans| [Plan](/sdk/data-plan/#plan)[]  
procedures| [Procedure](/sdk/data-procedure/#procedure)[]  
stopped_medications| [StopMedicationEvent](/sdk/data-stop-medication-event/#stopmedicationevent)[]  
updategoals| [UpdateGoal](/sdk/data-goal/#updategoal)[]  
Use `linked_referrals` for referrals linked this way. The `referrals` accessor above reads a referral's separate `assessments` list instead.
A linked [Close Goal](/sdk/commands/#closegoal) command arrives on `updategoals` rather than through an accessor of its own, because [both the Update Goal and Close Goal commands record an `UpdateGoal`](/sdk/data-goal/#goal-updates-and-closures).
##  Enumeration types 
###  Assessment Status 
Value| Label  
---|---  
STATUS_IMPROVING| Improved  
STATUS_STABLE| Unchanged  
STATUS_DETERIORATING| Deteriorated  

---

# BannerAlert

Source: https://docs.canvasmedical.com/sdk/data-banner-alert/

##  Introduction 
The `BannerAlert` model represents alerts associated with [Patient](/sdk/data-patient/#patient) records. This page deals with data retrieval. To create or remove `BannerAlert` records, see [Banner Alert Effects](/sdk/effect-banner-alerts/).
##  Usage 
The `BannerAlert` model can be used to find all of the banner alert records linked to a patient. For example, to find all of the banner alerts for a patient, the `Patient.banner_alerts` method can be used:
    ```python
    >>> from canvas_sdk.v1.data.patient import Patient
    >>> patient_1 = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> patient_banner_alerts = patient_1.banner_alerts.all()
    >>> print([item.narrative for item in patient_banner_alerts])
    ['Patient spits when angry', 'Confirm contact info']
    ```
##  Filtering 
The `filter` method can be used to filter by desired attributes. The following examples show commonly used operations to filter banner alert data:
**Show a Patient's active BannerAlert records from the 'foo' plugin in order of descending creation date**
    ```python
    >>> from canvas_sdk.v1.data.patient import Patient
    >>> patient_1 = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> banner_alerts = patient_1.banner_alerts.filter(status='active', plugin_name='foo').order_by("created")
    >>> print([item.narrative for item in banner_alerts])
    ['foo', 'bar']
    ```
##  Attributes 
###  BannerAlert 
Field Name| Type  
---|---  
dbid| Integer  
id| UUID  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
plugin_name| String  
key| String  
narrative| String  
placement| BannerAlertPlacement[]  
intent| BannerAlertIntent  
href| String  
status| BannerAlertStatus  
##  Enumeration types 
###  BannerAlertStatus 
Value| Label  
---|---  
active| Active  
inactive| Inactive  
###  BannerAlertIntent 
Value| Label  
---|---  
info| Info  
warning| Warning  
alert| Alert  
###  BannerAlertPlacement 
Value| Label  
---|---  
chart| Chart  
timeline| Timeline  
appointment_card| Appointment Card  
scheduling_card| Scheduling Card  
profile| Profile

---

# BillingLineItem

Source: https://docs.canvasmedical.com/sdk/data-billing-line-item/

##  Introduction 
The `BillingLineItem` model represents billing line items linked to [Notes](/sdk/data-note) that can be found in the note footer. BillingLineItems are also linked to [Patient](/sdk/data-patient/#patient) instances.
##  Usage 
The `BillingLineItem` model can be used to find all of the billable codes linked to a patient note. For example, to find all of the current billing line items for a note, the `Note.billing_line_items` method can be used:
    ```python
    >>> from canvas_sdk.v1.data.note import Note
    >>> from canvas_sdk.v1.data.billing import BillingLineItemStatus
    >>> note_1 = Note.objects.get(id="a74592ae8a6c4d0ebe0799d3fb3713d1")
    >>> note_1_billing_line_items = note_1.billing_line_items.filter(status=BillingLineItemStatus.ACTIVE)
    >>> print([item.cpt for item in note_1_billing_line_items])
    ['99213', '90703']
    ```
Alternatively, you could find all the `BillingLineItem` instances for a single `Patient`:
    ```python
    >>> from canvas_sdk.v1.data.patient import Patient
    >>> patient_1 = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> patient_billing_line_items = patient_1.billing_line_items.all()
    >>> print([item.cpt for item in patient_billing_line_items])
    ['99213', '90703', '76942', '67505']
    ```
You can also access all `BillingLineItemModifier`s associated with a `BillingLineItem`:
    ```python
    >>> from canvas_sdk.v1.data.billing import BillingLineItem, BillingLineItemModifier
    >>> line_item = BillingLineItem.objects.get(id="b80b1cdc2e6a4aca90ccebc02e683f35")
    >>> line_item_modifiers = line_item.modifiers.all()
    >>> print([mod.code for mod in line_item_modifiers])
    ['25', '59']
    ```
##  Filtering 
The `filter` method can be used to filter by desired attributes. The following examples show commonly used operations to filter billing line item data:
**Show a Patient's active BillingLineItems that start with '99-' in order of descending charge amount**
    ```python
    >>> from canvas_sdk.v1.data.patient import Patient
    >>> from canvas_sdk.v1.data.billing import BillingLineItemStatus
    >>> patient_1 = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> office_visit_charges = patient_1.billing_line_items.filter(status=BillingLineItemStatus.ACTIVE, cpt__startswith='99').order_by("charge")
    >>> print([(item.cpt, item.charge,) for item in office_visit_charges])
    [('99215', 200.00), ('99215', 190.00), ('99214', 100.00), ('99213', 80.00)]
    ```
**Find All Removed BillingLineItems from a Note**
    ```python
    >>> import arrow
    >>> from canvas_sdk.v1.data.note import Note
    >>> from canvas_sdk.v1.data.billing import BillingLineItemStatus
    >>> note_1 = Note.objects.get(id="a74592ae8a6c4d0ebe0799d3fb3713d1")
    >>> note_1_removed_items = note_1.billing_line_items.filter(status=BillingLineItemStatus.REMOVED)
    >>> print([item.cpt for item in note_1_removed_items])
    ['11901', '00950']
    ```
For examples of how to use the BillingLineItem data class with the BillingLineItem effects, check out [this page](/sdk/effect-billing-line-items)
##  Attributes 
###  BillingLineItem 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
note| [Note](/sdk/data-note)  
patient| [Patient](/sdk/data-patient/#patient)  
cpt| String  
charge| Decimal  
description| String  
units| Integer  
command_type| String  
command_id| Integer  
status| BillingLineItemStatus  
assessments| [Assessment](/sdk/data-assessment)[]  
modifiers| BillingLineItemModifier[]  
claimlineitem_set| [ClaimLineItem](/sdk/data-claim/#claimlineitem)[]  
###  BillingLineItemModifier 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
line_item| BillingLineItem  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
##  Enumeration types 
###  BillingLineItemStatus 
Value| Label  
---|---  
ACTIVE| Active  
REMOVED| Removed

---

# BusinessLine

Source: https://docs.canvasmedical.com/sdk/data-business-line/

##  Introduction 
The `BusinessLine` model represents a group of [Patients](/sdk/data-patient/#patient) that share a common brand under an [Organization](/sdk/data-organization).
##  Usage 
The `BusinessLine` model can be used to find all of the patients for a given Business Line:
    ```python
    >>> from canvas_sdk.v1.data import BusinessLine
    >>> business_line = BusinessLine.objects.get(id="ff844d60Od18466698dc645PtYZ3019Tt")
    >>> business_line_patients = business_line.patients.all()
    >>> print([patient.first_name for patient in business_line_patients])
    ['George', 'Louise', 'Julia']
    ```
You can also access a patient's Business Line from the `Patient` model:
    ```python
    >>> from canvas_sdk.v1.data import Patient
    >>> patient_1 = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> patient_business_line = patient_1.business_line
    >>> print(patient_business_line.name)
    'New Patients that love cheese'
    ```
And you can also access all of the Business Lines under a given Organization:
    ```python
    >>> from canvas_sdk.v1.data import Organization
    >>> organization = Organization.objects.first()
    >>> organization_business_lines = organization.business_lines.all()
    >>> print([business_line.name for business_line in organization_business_lines])
    ['New Patients that love cheese', 'Spanish Speaking Patients', 'One Medical']
    ```
##  Accessing the logo 
The `logo_url` property returns a presigned S3 URL for the business line's logo image, or `None` when no logo is set. Use it to brand plugin output, such as a patient portal page or a generated document, with the logo configured in Canvas. The URL is valid for one hour, so generate it when you need it rather than storing it.
    ```python
    from canvas_sdk.v1.data import Patient
    patient = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    # Presigned S3 URL to the logo image, or None if no logo is set
    logo_url = patient.business_line.logo_url if patient.business_line else None
    ```
##  Filtering 
The `filter` method can be used to filter by desired attributes. The following examples show commonly used operations to filter Business Line data:
**Show an Organization's Business Lines that are active and in the 732 area code**
    ```python
    >>> from canvas_sdk.v1.data import BusinessLine, Organization
    >>> org = Organization.objects.first()
    >>> active_732_business_lines = BusinessLine.objects.filter(organization=org, active=True, area_code="732")
    >>> print([business_line.name for business_line in active_732_business_lines])
    ['Foo', 'Bar']
    ```
##  Attributes 
###  BusinessLine 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
name| String  
description| String  
area_code| String  
subdomain| String  
active| Boolean  
state| BusinessLineState  
organization| [Organization](/sdk/data-organization)  
logo| File (S3 key)  
logo_url| String (computed)  
patients| QuerySet[[Patient](/sdk/data-patient/#patient)]  
##  Enumeration types 
###  BusinessLineState 
Value| Label  
---|---  
success| Success  
pending| Pending  
error| Deleted

---

# Calendar

Source: https://docs.canvasmedical.com/sdk/data-calendar/

##  Introduction 
The `Calendar` model represents a Calendar in Canvas. Calendars are used to organize events for providers and can be either Clinic or Administrative type.
Busy time that native Google Calendar sync imports for a provider isn't stored as calendar events. To read it, use the [Google Calendar](/sdk/data-google-calendar/) data models.
##  Basic usage 
To get a calendar by identifier, use the `get` method on the `Calendar` model manager:
    ```python
    from canvas_sdk.v1.data.calendar import Calendar
    calendar = Calendar.objects.get(id="f53626e4-0683-43ac-a1b7-c52815639ce2")
    ```
##  Events 
The events associated with a calendar can be accessed with the `events` attribute on a `Calendar` object:
    ```python
    from canvas_sdk.v1.data.calendar import Calendar
    calendar = Calendar.objects.get(id="f53626e4-0683-43ac-a1b7-c52815639ce2")
    events = calendar.events.all()
    ```
To get a specific event by identifier:
    ```python
    from canvas_sdk.v1.data.calendar import Event
    event = Event.objects.get(id="a1b2c3d4-5678-90ab-cdef-1234567890ab")
    ```
##  Filtering 
Calendars and events can be filtered by any attribute that exists on the model.
Filtering is done with the `filter` method on the model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.calendar import Calendar
    # Filter calendars by title
    calendars = Calendar.objects.filter(title__icontains="Clinic")
    ```
###  By calendar name 
To filter calendars by a specific provider name, calendar type, and location, use the `for_calendar_name` method:
    ```python
    from canvas_sdk.v1.data.calendar import Calendar
    calendars = Calendar.objects.for_calendar_name(
        provider_name="Dr. Smith",
        calendar_type="Clinic",
        location="Main Office"
    )
    ```
##  Attributes 
###  Calendar 
Field Name| Type| Description  
---|---|---  
id| UUID| Unique identifier for the calendar  
dbid| Integer| Database identifier  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
title| String| The title of the calendar  
timezone| TimeZone| The timezone for the calendar (default: UTC)  
description| String| Optional description of the calendar's purpose  
events| Event[]| Events associated with this calendar  
###  Event 
Field Name| Type| Description  
---|---|---  
id| UUID| Unique identifier for the event  
dbid| Integer| Database identifier  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
title| String| The title of the event  
description| String| Description of the event  
calendar| Calendar| The calendar this event belongs to  
starts_at| DateTime| The start date and time of the event  
ends_at| DateTime| The end date and time of the event  
recurrence| String| Recurrence rule for recurring events  
recurrence_ends_at| DateTime| The date and time when the recurrence pattern ends  
recurring_parent_event| Event| The parent event  
exceptions| Event[]| Exception (override) events for this recurring parent event  
original_starts_at| DateTime| The original start time for recurring event exceptions  
is_all_day| Boolean| Whether this is an all-day event (default: false)  
is_cancelled| Boolean| Whether this event has been cancelled (default: false)  
allowed_note_types| NoteType[]| Note types that are allowed for this event  
##  Examples 
###  Working with calendar events 
    ```python
    from canvas_sdk.v1.data.calendar import Calendar
    from datetime import datetime
    from logger import log
    calendar = Calendar.objects.get(id="f53626e4-0683-43ac-a1b7-c52815639ce2")
    # Get all upcoming events
    upcoming_events = calendar.events.filter(
        starts_at__gte=datetime.now(),
        is_cancelled=False
    ).order_by('starts_at')
    for event in upcoming_events:
        log.info(f"Event: {event.title}")
        log.info(f"Starts at: {event.starts_at}")
        log.info(f"Ends at: {event.ends_at}")
        if event.recurrence:
            log.info(f"Recurrence: {event.recurrence}")
    ```

---

# CancelPrescriptionResponse

Source: https://docs.canvasmedical.com/sdk/data-cancel-prescription-response/

##  Introduction 
The `CancelPrescriptionResponse` model captures the response to a [CancelPrescription](/sdk/data-cancel-prescription) request. Each response is linked one-to-one to the request that produced it.
##  Basic usage 
To get a cancel prescription response by identifier, use the `get` method on the `CancelPrescriptionResponse` model manager:
    ```python
    from canvas_sdk.v1.data import CancelPrescriptionResponse
    response = CancelPrescriptionResponse.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the cancel prescription responses for a patient can be accessed with the `cancel_prescription_responses` attribute:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    responses = patient.cancel_prescription_responses.all()
    ```
Or, from a cancel prescription, reach its response with the `response` attribute:
    ```python
    from canvas_sdk.v1.data import CancelPrescription
    cancel = CancelPrescription.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    response = cancel.response
    ```
##  Attributes 
###  CancelPrescriptionResponse 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
request| [CancelPrescription](/sdk/data-cancel-prescription)  
message_id| String  
note| String  
reason_code| String  
response| String  

---

# CancelPrescription

Source: https://docs.canvasmedical.com/sdk/data-cancel-prescription/

##  Introduction 
The `CancelPrescription` model is the anchor for the CancelPrescription command — a request to cancel a patient's prescription, recorded on a Note.
##  Basic usage 
To get a cancel prescription by identifier, use the `get` method on the `CancelPrescription` model manager:
    ```python
    from canvas_sdk.v1.data import CancelPrescription
    cancel = CancelPrescription.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the cancel prescriptions for a patient can be accessed with the `cancel_prescriptions` attribute:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    cancels = patient.cancel_prescriptions.all()
    ```
Or, from a prescription, reach its cancellations with the same `cancel_prescriptions` attribute:
    ```python
    from canvas_sdk.v1.data import Prescription
    prescription = Prescription.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    cancels = prescription.cancel_prescriptions.all()
    ```
##  Committed records 
The `committed` method returns cancel prescriptions that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import CancelPrescription
    committed_cancels = CancelPrescription.objects.committed()
    ```
##  Attributes 
###  CancelPrescription 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
prescription| [Prescription](/sdk/data-prescription)  
message_id| String  
status| CancelPrescriptionStatus  
response| [CancelPrescriptionResponse](/sdk/data-cancel-prescription-response/#cancelprescriptionresponse)  
##  Enumeration types 
###  CancelPrescriptionStatus 
Name| Value  
---|---  
OPEN| open  
PENDING| pending  
ULTIMATELY_ACCEPTED| ultimately-accepted  

---

# CanvasUser

Source: https://docs.canvasmedical.com/sdk/data-canvasuser/

##  Introduction 
The `CanvasUser` model represents a Canvas User. This could be linked to a staff member or a patient. This model isn't meant to be referenced directly, but is sometimes used to attribute a record to user.
##  Basic usage 
To get a user by identifier, use the `get` method on the `CanvasUser` model manager:
    ```python
    from canvas_sdk.v1.data import CanvasUser
    user = CanvasUser.objects.get(dbid=123)
    ```
##  Filtering 
Users can be filtered by any attribute that exists on the model.
Filtering for users is done with the `filter` method on the `CanvasUser` model manager.
###  By attribute 
Specify attributes with `filter` to filter by those attributes:
    ```python
    from canvas_sdk.v1.data import CanvasUser
    users = CanvasUser.objects.filter(phone_number="1111111111", email="test@canvasmedical.com")
    ```
##  Attributes 
###  User 
Field Name| Type  
---|---  
dbid| Integer  
email| String  
phone_number| String  
is_staff| Boolean  
is_portal_registered| Boolean  
last_invite_date_time| DateTime  
person_subclass| [Staff](/sdk/data-staff/#staff) | [Patient](/sdk/data-patient/#patient)  
staff| [Staff](/sdk/data-staff/#staff)  
patient| [Patient](/sdk/data-patient/#patient)  
sent_messages| [Message](/sdk/data-message/#message)[]  
received_messages| [Message](/sdk/data-message/#message)[]  
commands_originated| [Command](/sdk/data-command/#command)[]  
commands_committed| [Command](/sdk/data-command/#command)[]  
commands_entered_in_error| [Command](/sdk/data-command/#command)[]  

---

# CareTeam

Source: https://docs.canvasmedical.com/sdk/data-care-team/

##  Introduction 
The `CareTeam` model represents a collection of [Staff](/sdk/data-staff/#staff) that are responsible for the care of a [Patient](/sdk/data-patient/#patient).
##  Usage 
There are 2 data models associated with Care Teams - `CareTeamMembership` and `CareTeamRole`. The `CareTeamRole` model stores all of the available roles that are available to be filled by staff members (i.e. _Physician_ , _Nurse Practitioner_ , etc.). For example, the following code will show the names of active roles that are available in a Canvas instance:
    ```python
    >>> from canvas_sdk.v1.data.care_team import CareTeamRole
    >>> active_care_team_roles = CareTeamRole.objects.filter(active=True)
    >>> role_names = [role.display for role in active_care_team_roles]
    >>> print(role_names)
    ['Primary care physician', 'Physician', 'Physician assistant', 'Nurse practitioner', 'Health coach', 'Care coordinator']
    ```
The `CareTeamMembership` model connects patients, staff members and their associated roles to make up the assembly of a patient's Care Team. To retrieve staff members and their respective roles on a patient's care team, the `care_team_memberships` attribute available on a [Patient](/sdk/data-patient/#patient) instance can be used:
    ```python
    >>> from canvas_sdk.v1.data.patient import Patient
    >>> patient_1 = Patient.objects.get(id="a74592ae8a6c4d0ebe0799d3fb3713d1")
    >>> patient_1_care_team = patient_1.care_team_memberships.all()
    >>> print([(ctm.role.display, ctm.staff,) for ctm in patient_1_care_team])
    [('Primary care physician', <Staff: Steven Magee>), ('Nurse practitioner', <Staff: Annalies Hines>), ('Physician assistant', <Staff: Erik McDonald>)]
    ```
###  External care team members 
A care team can also include external members — providers who are not [Staff](/sdk/data-staff#staff) on the Canvas instance. An external membership has no `staff`. Instead, its `organizational_entity` links to an [OrganizationalEntity](/sdk/data-organizational-entity/#organizationalentity) that describes the external provider. When that entity is a [ServiceProvider](/sdk/data-serviceprovider/#service-provider), the membership's `service_provider` property resolves directly to it, so you can read the provider's contact details — such as `business_fax` — without leaving the plugin.
    ```python
    >>> from canvas_sdk.v1.data.patient import Patient
    >>> patient_1 = Patient.objects.get(id="a74592ae8a6c4d0ebe0799d3fb3713d1")
    >>> external_member = patient_1.care_team_memberships.filter(staff__isnull=True).first()
    >>> external_member.service_provider.business_fax
    '18005551234'
    ```
The `service_provider` property returns `None` for internal (staff-backed) memberships, and for external members whose organizational entity is not a `Service Provider`.
##  Filtering 
The `filter` method can be used to filter by desired attributes. The following examples show commonly used operations to filter care team data:
**Find a patient's care team lead**
    ```python
    >>> from canvas_sdk.v1.data.patient import Patient
    >>> from canvas_sdk.v1.data.care_team import CareTeamMembershipStatus
    >>> patient_1 = Patient.objects.get(id="a74592ae8a6c4d0ebe0799d3fb3713d1")
    >>> patient_1_care_team_lead = patient_1.care_team_memberships.filter(lead=True, status=CareTeamMembershipStatus.ACTIVE).first()
    >>> assert patient_1_care_team_lead is not None
    >>> print((patient_1_care_team_lead.staff, patient_1_care_team_lead.role,))
    (<Staff: Steven Magee>, <CareTeamRole: Primary care physician>)
    ```
**Find all Patients that have a Certain Staff Member on their Care Team**
    ```python
    >>> from canvas_sdk.v1.data.staff import Staff
    >>> from canvas_sdk.v1.data.care_team import CareTeamMembershipStatus
    >>> staff_member = Staff.objects.get(id="3640cd20de8a470aa570a852859ac87e")
    >>> staff_care_teams = staff_member.care_team_memberships.filter(status=CareTeamMembershipStatus.ACTIVE)
    >>> print([(ctm.patient, ctm.lead,) for ctm in staff_care_teams])
    [(<Patient: Danny Boy>, True), (<Patient: Sally Mae>, False)]
    ```
##  Attributes 
###  CareTeamRole 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| BooleanField  
active| Boolean  
care_teams| [CareTeamMembership](/sdk/data-care-team/#careteammembership)[]  
###  CareTeamMembership 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
patient| [Patient](/sdk/data-patient/#patient)|   
staff| [Staff](/sdk/data-staff#staff)|   
role| CareTeamRole|   
organizational_entity| [OrganizationalEntity](/sdk/data-organizational-entity/#organizationalentity)|   
status| CareTeamMembershipStatus|   
lead| Boolean|   
role_code| String|   
role_system| String|   
role_display| String|   
service_provider| [ServiceProvider](/sdk/data-serviceprovider/#service-provider) | `None` (computed)| The external provider for this membership, resolved through its `organizational_entity`; `None` for internal members.  
For external (non-staff) members, `staff` is empty and `organizational_entity` links to the external provider.
##  Enumeration types 
###  CareTeamMembershipStatus 
Value| Label  
---|---  
proposed| Proposed  
active| Active  
suspended| Suspended  
inactive| Inactive  
entered-in-error| Entered in Error

---

# Change Medication

Source: https://docs.canvasmedical.com/sdk/data-change-medication/

##  Introduction 
The `ChangeMedication` model represents a record of a Change Medication command, used to update the directions (sig) of a medication already on a patient's medication list without issuing a new prescription.
##  Basic usage 
To get a change medication by identifier, use the `get` method on the `ChangeMedication` model manager:
    ```python
    from canvas_sdk.v1.data import ChangeMedication
    change_medication = ChangeMedication.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    ```
If you have a patient object, the change medications for a patient can be accessed with the `change_medications` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    change_medications = patient.change_medications.all()
    ```
You can also access the referenced medication with the `medication` attribute:
    ```python
    from canvas_sdk.v1.data import ChangeMedication
    change_medication = ChangeMedication.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    medication = change_medication.medication
    ```
Or for a given medication, you can access all change medication records:
    ```python
    from canvas_sdk.v1.data import Medication
    medication = Medication.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    change_medications = medication.change_medications.all()
    ```
##  Latest sig 
A change medication's sig is one of the sources a medication's [`latest_sig`](/sdk/data-medication/#latest-sig) draws on, alongside its active prescriptions and medication statements. To get the most recent sig for the medication, read `latest_sig` from the referenced medication:
    ```python
    from canvas_sdk.v1.data import ChangeMedication
    change_medication = ChangeMedication.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    sig = change_medication.medication.latest_sig
    ```
##  Committed records 
The `committed` method returns change medications that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import ChangeMedication
    committed_change_medications = ChangeMedication.objects.committed()
    ```
##  Attributes 
###  ChangeMedication 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
medication| [Medication](/sdk/data-medication)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
originator| [CanvasUser](/sdk/data-canvasuser)  
created| DateTime  
modified| DateTime  
sig_original_input| String  

---

# ChargeDescriptionMaster

Source: https://docs.canvasmedical.com/sdk/data-charge-description-master/

##  Introduction 
The `ChargeDescriptionMaster` model represents a billing charge in Canvas that can be added to the note footer.
##  Usage 
The `ChargeDescriptionMaster` model can be filtered by any of its attributes, including `cpt_code`, `name`, and `short_name`:
    ```python
    >>> from canvas_sdk.v1.data import ChargeDescriptionMaster
    >>> office_visit_charges = ChargeDescriptionMaster.objects.filter(cpt_code__startswith="99")
    >>> print([charge.short_name for charge in office_visit_charges])
    ["Office outpatient visit 40 minutes", "Office outpatient visit 25 minutes", "Office outpatient visit 10 minutes"]
    ```
You can also access `PayorSpecificCharge`s from the `ChargeDescriptionMaster` model:
    ```python
    >>> from canvas_sdk.v1.data import ChargeDescriptionMaster
    >>> office_visit_40min = ChargeDescriptionMaster.objects.filter(cpt_code="99215").first()
    >>> payor_specific_charges = office_visit_40min.transactor_charges.all()
    >>> print([charge.transactor.name for charge in payor_specific_charges])
    ["Aetna", "Medicare", "Blue Shield of CA"]
    ```
`
##  Attributes 
###  ChargeDescriptionMaster 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
cpt_code| String  
name| String  
short_name| String  
charge_amount| Decimal  
effective_date| Date  
end_date| Date  
code_system| CDMCodeSystem  
ndc_code| String  
transactor_charges| QuerySet[[PayorSpecificCharge](/sdk/data-payor-specific-charge/#payorspecificcharge)]  
vaccines| QuerySet[[Vaccine](/sdk/data-vaccine/#vaccine)]  
##  Enumeration types 
###  CDMCodeSystem 
Value| Label  
---|---  
INTERNAL| Internal  
CPT| CPT

---

# ChartSectionReview

Source: https://docs.canvasmedical.com/sdk/data-chart-section-review/

##  Introduction 
The `ChartSectionReview` model represents a reviewed chart section captured on a note, with its pre-rendered content. When a provider reviews a chart section during a visit, Canvas stores a snapshot of that section's content at the time of review.
##  Basic usage 
To get a chart section review by identifier, use the `get` method on the `ChartSectionReview` model manager:
    ```python
    from canvas_sdk.v1.data.chart_section_review import ChartSectionReview
    review = ChartSectionReview.objects.get(id="b5a0c1d2-e3f4-5678-9abc-def012345678")
    ```
If you have a patient object, the chart section reviews for a patient can be accessed with the `chart_section_reviews` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    reviews = patient.chart_section_reviews.all()
    ```
If you have a note object, the chart section reviews for that note can be accessed with the `chart_section_reviews` attribute on a `Note` object:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    reviews = note.chart_section_reviews.all()
    ```
##  Filtering 
Chart section reviews can be filtered by any attribute that exists on the model.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.chart_section_review import (
        ChartSectionReview,
        ChartSectionReviewSection,
    )
    # Get all reviews for the conditions section
    condition_reviews = ChartSectionReview.objects.filter(
        section=ChartSectionReviewSection.CONDITIONS
    )
    ```
###  By patient and section 
    ```python
    from canvas_sdk.v1.data.chart_section_review import (
        ChartSectionReview,
        ChartSectionReviewSection,
    )
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    medication_reviews = ChartSectionReview.objects.filter(
        patient=patient,
        section=ChartSectionReviewSection.MEDICATIONS
    )
    ```
###  Committed reviews 
The `committed` method returns chart section reviews that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.chart_section_review import ChartSectionReview
    committed_reviews = ChartSectionReview.objects.committed()
    ```
##  Working with entries 
`entries` is a list of integer `dbid` values identifying the records that were reviewed in the section. Which model those `dbid`s belong to depends on the review's `section`:
`section`| Model(s) referenced by `entries`  
---|---  
`conditions`| [Condition](/sdk/data-condition/) (non-surgical)  
`surgical_history`| [Condition](/sdk/data-condition/) (surgical)  
`medications`| [Medication](/sdk/data-medication/)  
`family_histories`| [FamilyHistory](/sdk/data-family-history/#familyhistory)  
`allergies`| [AllergyIntolerance](/sdk/data-allergy-intolerance/)  
`immunizations`| [Immunization](/sdk/data-immunization/) and [ImmunizationStatement](/sdk/data-immunization/)  
If you only need to **see what was reviewed** , prefer the `content` field: it holds the pre-rendered text of the reviewed records (one line per entry, captured at review time), so it needs no entry resolution and avoids the ambiguity described below.
To work with the **record objects themselves** , filter the corresponding model by `dbid__in=review.entries`. Always scope the query to `review.patient` as well: a `dbid` is unique only within its own table, so scoping by patient avoids matching an unrelated record that happens to share the same integer (this is also why the `immunizations` section, which draws from two models, is resolved against both).
    ```python
    from canvas_sdk.v1.data.allergy_intolerance import AllergyIntolerance
    from canvas_sdk.v1.data.chart_section_review import (
        ChartSectionReview,
        ChartSectionReviewSection,
    )
    from canvas_sdk.v1.data.condition import Condition
    from canvas_sdk.v1.data.family_history import FamilyHistory
    from canvas_sdk.v1.data.immunization import Immunization, ImmunizationStatement
    from canvas_sdk.v1.data.medication import Medication
    review = ChartSectionReview.objects.get(id="b5a0c1d2-e3f4-5678-9abc-def012345678")
    if review.section == ChartSectionReviewSection.CONDITIONS:
        records = Condition.objects.filter(
            patient=review.patient, dbid__in=review.entries, surgical=False
        )
    elif review.section == ChartSectionReviewSection.SURGICAL_HISTORY:
        records = Condition.objects.filter(
            patient=review.patient, dbid__in=review.entries, surgical=True
        )
    elif review.section == ChartSectionReviewSection.MEDICATIONS:
        records = Medication.objects.filter(patient=review.patient, dbid__in=review.entries)
    elif review.section == ChartSectionReviewSection.FAMILY_HISTORIES:
        records = FamilyHistory.objects.filter(patient=review.patient, dbid__in=review.entries)
    elif review.section == ChartSectionReviewSection.ALLERGIES:
        records = AllergyIntolerance.objects.filter(patient=review.patient, dbid__in=review.entries)
    elif review.section == ChartSectionReviewSection.IMMUNIZATIONS:
        # entries may reference either model, so resolve against both.
        records = [
            *Immunization.objects.filter(patient=review.patient, dbid__in=review.entries),
            *ImmunizationStatement.objects.filter(patient=review.patient, dbid__in=review.entries),
        ]
    ```
> **Note on the`immunizations` section:** `entries` stores bare `dbid` integers with no indication of which model each one came from. Because `Immunization` and `ImmunizationStatement` are separate tables with independent `dbid` sequences, the same integer can be a valid `dbid` in both. If a patient has an `Immunization` and an `ImmunizationStatement` that share a `dbid` and only one was reviewed, resolving against both models (as above) will return both records — there is no way to disambiguate them from `entries` alone. Treat the immunizations result as a best-effort superset, not an exact match. If you only need to know what was reviewed, use `content` instead: it captured the rendered text of the actual reviewed items at review time.
##  Attributes 
###  ChartSectionReview 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
section| ChartSectionReviewSection  
entries| Integer[] (`dbid`s of the reviewed records — see Working with entries)  
content| String (newline-separated bullet items)  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
##  Enumeration types 
###  ChartSectionReviewSection 
Value| Label  
---|---  
conditions| Conditions  
surgical_history| Surgical History  
medications| Medications  
family_histories| Family Histories  
allergies| Allergies  
immunizations| Immunizations

---

# Claim

Source: https://docs.canvasmedical.com/sdk/data-claim/

##  Introduction 
This module defines the data models used to manage healthcare claim workflows.
##  Basic usage 
To retrieve a claim by its identifier:
    ```python
    from canvas_sdk.v1.data.claim import Claim
    claim = Claim.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130003")
    ```
To access diagnosis codes for a claim:
    ```python
    from canvas_sdk.v1.data.claim import Claim
    claim = Claim.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130003")
    diagnosis_codes = claim.diagnosis_codes.all().order_by("rank")
    for diagnosis in diagnosis_codes:
        print(f"Rank {diagnosis.rank}: {diagnosis.code} - {diagnosis.display}")
    ```
To access banner alerts for a claim:
    ```python
    from canvas_sdk.v1.data.claim import Claim
    claim = Claim.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130003")
    active_alerts = claim.banner_alerts.filter(status="active")
    for alert in active_alerts:
        print(f"[{alert.intent}] {alert.narrative}")
    ```
##  When a claim is created 
A claim is created for an appointment or note only when the note's type is billable. A note type with `is_billable` set to `False`, such as the built-in Chart review type, produces a note and no claim, so check the flag rather than assuming every appointment produces a claim.
The flag lives on [NoteType](/sdk/data-note/#notetype), reached through the note's `note_type_version` attribute. To read the claim itself, call the note's `get_claim()` method, which returns the note's most recent claim, or `None` when it has none:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    expects_claim = note.note_type_version.is_billable
    claim = note.get_claim()
    ```
##  Claim balances and totals 
The money on a claim comes from two stored balance fields plus a set of computed properties layered over the claim's line items and postings.
`patient_balance` and `aggregate_coverage_balance` are stored on the claim and kept in sync by signals as coverage postings transfer money to the patient, as coverage is added or removed, and as the patient makes payments. Reading them needs no aggregation on your part, and they stay correct when coverage is added after a note is signed.
The rest are computed on access, each over a different slice of the claim:
Property| What it adds up  
---|---  
`total_charges`| `charge` across the claim's active line items, with copay and unlinked items excluded  
`total_paid`| `paid_amount` across every active posting on the claim, coverage and patient alike  
`total_payer_paid`| `paid_amount` across the active postings of the claim's active coverages  
`total_patient_paid`| `paid_amount` across the active postings on the claim's patient record  
`total_adjusted`| `contractual_adjusted_amount` plus `transferred_amount` across every active posting  
`balance`| `aggregate_coverage_balance` plus `patient_balance`, the coverage side and the patient side together  
A posting counts as active when it has not been entered in error. Because `total_paid` spans both sides of the claim, `total_payer_paid` and `total_patient_paid` are that figure split by who paid it.
###  Computing patient-allocated charges 
To find how much has been allocated to the patient on a claim, add what the patient still owes to what they have already paid:
    ```python
    from canvas_sdk.v1.data.claim import Claim
    claim = Claim.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130003")
    patient_allocated = claim.patient_balance + claim.total_patient_paid
    ```
This holds for self-pay and insured claims alike, including a self-pay claim carrying no postings at all.
##  Filtering 
    ```python
    from canvas_sdk.v1.data.claim import Claim
    # Active claims only
    active_claims = Claim.objects.active()
    ```
##  Attributes 
###  Claim 
Represents a complete healthcare claim. Claim belongs to a Note and has a one-to-one relationship with a ClaimPatient.
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
note| [Note](/sdk/data-note/)|   
installment_plan| InstallmentPlan|   
current_queue| ClaimQueue|   
current_coverage| ClaimCoverage|   
accept_assign| Boolean|   
auto_accident| Boolean|   
auto_accident_state| String|   
employment_related| Boolean|   
other_accident| Boolean|   
accident_code| String|   
illness_date| Date|   
remote_batch_id| String|   
remote_file_id| String|   
prior_auth| String|   
narrative| String|   
account_number| String|   
snoozed_until| Date|   
patient_balance| Decimal|   
aggregate_coverage_balance| Decimal|   
created| DateTime|   
modified| DateTime|   
diagnosis_codes| ClaimDiagnosisCode[]|   
comments| ClaimComment[]|   
line_items| ClaimLineItem[]|   
labels| [TaskLabel](/sdk/data-task/#tasklabel)[]|   
metadata| ClaimMetadata[]|   
banner_alerts| ClaimBannerAlert[]|   
provider| ClaimProvider|   
incident_to| Boolean|   
supervising_provider| ClaimSupervisingProvider|   
latest_invoice| [Invoice](/sdk/data-invoice/#invoice)|   
patient| ClaimPatient|   
coverages| ClaimCoverage[]|   
submissions| ClaimSubmission[]|   
postings| [BasePosting](/sdk/data-posting/#baseposting)[]|   
total_charges| Decimal (computed)| Total charges for active line items  
total_paid| Decimal (computed)| Sum of paid amounts from postings  
total_adjusted| Decimal (computed)| Sum of adjustments and transfers  
balance| Decimal (computed)| Remaining balance (coverage plus patient)  
total_patient_paid| Decimal (computed)| Amount paid by the patient  
total_payer_paid| Decimal (computed)| Amount paid by coverages  
**Helpful Methods** :
  - `get_coverage_by_payer_id(payer_id: str, subscriber_number: str | None = None)`: Finds the active coverage associated with a payer_id. Optionally checks if the subscriber_number matches, which will choose the correct coverage in the case where a patient has two coverages with the same payer_id.
###  ClaimSupervisingProvider 
An immutable snapshot of a claim's supervising provider (837P loop 2310D), captured at claim creation from the note's supervising provider and frozen thereafter, so later edits to the note or the underlying Staff record do not retroactively change a submitted claim.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
claim| Claim  
staff| [Staff](/sdk/data-staff/#staff)  
first_name| String  
last_name| String  
middle_name| String  
npi| String  
taxonomy| String  
tax_id| String  
tax_id_type| [TaxIDType](/sdk/data-enumeration-types/#taxidtype)  
created| DateTime  
modified| DateTime  
###  ClaimLineItem 
Represents individual billed procedures or services tied to a claim.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
billing_line_item| [BillingLineItem](/sdk/data-billing-line-item/)  
diagnosis_codes| ClaimLineItemDiagnosisCode[]  
modifiers| ClaimLineItemModifier[]  
claim| Claim  
status| ClaimLineItemStatus  
charge| Decimal  
from_date| String  
thru_date| String  
narrative| String  
ndc_code| String  
ndc_dosage| String  
ndc_measure| String  
place_of_service| [PracticeLocationPOS](/sdk/data-note/#practicelocationpos)  
proc_code| String  
display| String  
remote_chg_id| String  
units| Integer  
epsdt| String  
family_planning| FamilyPlanningOptions  
created| DateTime  
modified| DateTime  
newlineitempayments| QuerySet[[NewLineItemPayment](/sdk/data-posting/#newlineitempayment)]  
newlineitemadjustments| QuerySet[[NewLineItemAdjustment](/sdk/data-posting/#newlineitemadjustment)]  
lineitemtransfers| QuerySet[[LineItemTransfer](/sdk/data-posting/#lineitemtransfer)]  
###  ClaimLineItemDiagnosisCode 
Represents a diagnosis code for a given ClaimLineItem. There exists one ClaimLineItemDiagnosisCode for each ClaimDiagnosisCode, and the "linked" attribute indicates whether or not the diagnosis code is linked to the line item.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
line_item| ClaimLineItem  
claim_diagnosis_code| ClaimDiagnosisCode  
code| String  
poa| String  
linked| Boolean  
created| DateTime  
modified| DateTime  
###  ClaimLineItemModifier 
Represents a modifier code for a given ClaimLineItem.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
line_item| ClaimLineItem  
modifier| String  
created| DateTime  
modified| DateTime  
###  ClaimCoverage 
Links a claim to a specific insurance coverage.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
claim| Claim  
coverage| [Coverage](/sdk/data-coverage/)  
active| Boolean  
payer_name| String  
payer_id| String  
payer_typecode| String  
payer_order| ClaimPayerOrder  
payer_addr1| String  
payer_addr2| String  
payer_city| String  
payer_state| String  
payer_zip| String  
payer_plan_type| ClaimTypeCode  
coverage_type| [CoverageType](/sdk/data-coverage/#coveragetype)  
subscriber_employer| String  
subscriber_group| String  
subscriber_number| String  
subscriber_plan| String  
subscriber_dob| String  
subscriber_first_name| String  
subscriber_last_name| String  
subscriber_middle_name| String  
subscriber_phone| String  
subscriber_sex| [PersonSex](/sdk/data-patient/#sexatbirth)  
subscriber_addr1| String  
subscriber_addr2| String  
subscriber_city| String  
subscriber_state| String  
subscriber_zip| String  
subscriber_country| String  
patient_relationship_to_subscriber| [CoverageRelationshipCode](/sdk/data-coverage/#coveragerelationshipcode)  
pay_to_addr1| String  
pay_to_addr2| String  
pay_to_city| String  
pay_to_state| String  
pay_to_zip| String  
resubmission_code| String  
payer_icn| String  
created| DateTime  
modified| DateTime  
###  ClaimComment 
Represents a free-text comment made on a Claim.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
claim| Claim  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
comment| String  
###  ClaimBannerAlert 
Represents banner alerts associated with a claim. Banner alerts are displayed in the UI to surface important information about a claim. To create or remove `ClaimBannerAlert` records, see [Claim Effects](/sdk/effect-claims/#add-banner).
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
claim| Claim  
plugin_name| String  
key| String  
narrative| String  
intent| [BannerAlertIntent](/sdk/data-banner-alert/#banneralertintent)  
href| String  
status| [BannerAlertStatus](/sdk/data-banner-alert/#banneralertstatus)  
created| DateTime  
modified| DateTime  
###  ClaimDiagnosisCode 
Represents diagnosis codes associated with a claim, ordered by rank.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
claim| Claim  
line_item_diagnosis_codes| ClaimLineItemDiagnosisCode[]  
rank| Integer  
code| String  
display| String  
created| DateTime  
modified| DateTime  
###  ClaimQueue 
Defines the metadata for claim queues used in revenue workflows.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
queue_sort_ordering| Integer  
name| String  
display_name| String  
description| String  
show_in_revenue| Boolean  
visible_columns| Array[ClaimQueueColumns]  
created| DateTime  
modified| DateTime  
###  ClaimPatient 
Captures patient-level data related to a specific claim.
Field Name| Type  
---|---  
dbid| Integer  
claim| Claim  
photo| String  
dob| String  
first_name| String  
last_name| String  
middle_name| String  
phone| String  
sex| [PersonSex](/sdk/data-patient/#sexatbirth)  
ssn| String  
addr1| String  
addr2| String  
city| String  
state| String  
zip| String  
country| String  
created| DateTime  
modified| DateTime  
###  ClaimLabel 
Represents labels assigned to the claim.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
claim| Claim  
label| [TaskLabel](/sdk/data-task/#tasklabel)  
###  ClaimMetadata 
Represents key-value metadata associated with a claim. Each claim-key pair is unique.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
claim| Claim  
key| String  
value| String  
created| DateTime  
modified| DateTime  
###  ClaimProvider 
Captures provider-level data related to a specific claim.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
claim| Claim  
clia_number| String  
billing_provider_name| String  
billing_provider_phone| String  
billing_provider_addr1| String  
billing_provider_addr2| String  
billing_provider_city| String  
billing_provider_state| String  
billing_provider_zip| String  
billing_provider_id| String  
billing_provider_npi| String  
billing_provider_tax_id| String  
billing_provider_tax_id_type| String  
billing_provider_taxonomy| String  
provider_id| String  
provider_first_name| String  
provider_last_name| String  
provider_middle_name| String  
provider_npi| String  
provider_tax_id| String  
provider_tax_id_type| String  
provider_taxonomy| String  
provider_ptan_identifier| String  
provider_addr1| String  
provider_addr2| String  
provider_city| String  
provider_state| String  
provider_zip| String  
referring_provider_id| String  
referring_provider_first_name| String  
referring_provider_last_name| String  
referring_provider_middle_name| String  
referring_provider_npi| String  
referring_provider_ptan_identifier| String  
ordering_provider_first_name| String  
ordering_provider_last_name| String  
ordering_provider_middle_name| String  
ordering_provider_npi| String  
facility_id| String  
facility_name| String  
facility_npi| String  
facility_addr1| String  
facility_addr2| String  
facility_city| String  
facility_state| String  
facility_zip| String  
hosp_from_date| String  
hosp_to_date| String  
created| DateTime  
modified| DateTime  
###  ClaimSubmission 
Captures clearinghouse submission details about a claim.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
claim| Claim  
coverage| ClaimCoverage  
clearinghouse_claim_id| String  
claim_index| Integer  
###  InstallmentPlan 
Represents a payment plan between a patient and provider.
Field Name| Type  
---|---  
dbid| Integer  
creator| [CanvasUser](/sdk/data-canvasuser/)  
patient| [Patient](/sdk/data-patient/)  
total_amount| Decimal  
status| InstallmentPlanStatus  
expected_payoff_date| Date  
created| DateTime  
modified| DateTime  
claims| Claim[]  
##  Enumeration types 
###  ClaimLineItemStatus 
Value| Label  
---|---  
active| Active  
removed| Removed  
###  LineItemCodes 
Value  
---  
COPAY  
UNLINKED  
###  FamilyPlanningOptions 
Value| Label  
---|---  
Y| Yes  
N| No  
###  ClaimLineItemStatus 
Value| Label  
---|---  
active| Active  
removed| Removed  
###  LineItemCodes 
Value  
---  
COPAY  
UNLINKED  
###  FamilyPlanningOptions 
Value| Label  
---|---  
Y| Yes  
N| No  
###  ClaimPayerOrder 
Value| Label  
---|---  
Primary| Primary  
Secondary| Secondary  
Tertiary| Tertiary  
Quaternary| Quaternary  
Quinary| Quinary  
###  ClaimTypeCode 
Code| Description  
---|---  
12| Working Aged (Age 65 or older)  
13| End-Stage Renal Disease  
14| No-fault  
15| Workers Compensation  
41| Black Lung  
42| Veterans Administration  
43| Disabled (Under Age 65)  
47| Other Liability Insurance is primary  
""| No Typecode necessary  
###  ClaimQueueColumns 
Value| Label  
---|---  
NoteType| Note type  
ClaimID| Claim ID  
DateOfService| Date of service  
Patient| Patient  
ActiveInsurance| Active insurance  
InsuranceBalance| Insurance balance  
PatientBalance| Patient balance  
DaysInQueue| Days in queue  
Provider| Provider  
Guarantor| Guarantor  
LatestRemit| Latest remit  
LastInvoiced| Last invoiced  
SnoozedUntil| Snoozed until  
Labels| Labels  
###  ClaimQueues 
Value| Label  
---|---  
1| Appointment  
2| NeedsClinicianReview  
3| NeedsCodingReview  
4| QueuedForSubmission  
5| FiledAwaitingResponse  
6| RejectedNeedsReview  
7| AdjudicatedOpenBalance  
8| PatientBalance  
9| ZeroBalance  
10| Trash  
###  InstallmentPlanStatus 
Value| Label  
---|---  
active| Active  
completed| Completed  
cancelled| Cancelled

---

# Clipboard

Source: https://docs.canvasmedical.com/sdk/data-clipboard/

##  Introduction 
The `Clipboard` model is the record of a Clipboard command. It holds free-text content staged on a patient's note, such as a pasted transcript or summary. A plugin queries it to read that content along with the patient and note the text belongs to.
Clipboards are included regardless of command state (staged or committed); use `committed()` to filter to only committed commands. A plugin does not write clipboard content through this model. That content is recorded through the Clipboard command.
##  Basic usage 
To get a clipboard by identifier, use the `get` method on the model manager:
    ```python
    from canvas_sdk.v1.data import Clipboard
    clipboard = Clipboard.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
The staged content is on the `text` attribute:
    ```python
    from canvas_sdk.v1.data import Clipboard
    clipboard = Clipboard.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    text = clipboard.text
    ```
`get`, `filter`, and `committed` are available on the manager.
##  Accessing clipboards from a patient or note 
The clipboards for a patient or note are reachable through the `clipboards` reverse accessor, which is named the same on `Patient` and on `Note`:
    ```python
    from canvas_sdk.v1.data import Note, Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    patient_clipboards = patient.clipboards.all()
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    note_clipboards = note.clipboards.all()
    ```
##  Committed clipboards 
The `committed` method returns records whose underlying command has been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import Clipboard
    committed_clipboards = Clipboard.objects.committed()
    ```
##  Filtering 
Clipboards can be filtered by any attribute on the model with the `filter` method:
    ```python
    from canvas_sdk.v1.data import Clipboard
    clipboards = Clipboard.objects.filter(note__id="2c91b0d8-7b9d-4ef1-89e2-1f9a3a8a2b14")
    ```
##  Attributes 
###  Clipboard 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
text| String  

---

# Coding Gap Events

Source: https://docs.canvasmedical.com/sdk/data-coding-gap-event/

##  Introduction 
The `CreateCodingGapEvent`, `ValidateCodingGapEvent`, `AssessCodingGapEvent`, and `DeferCodingGapEvent` models are records of the actions taken on a coding gap: create, validate, assess, and defer. Each model is the anchor for the corresponding coding gap command.
A coding gap itself is represented by a [DetectedIssue](/sdk/data-detected-issue/) together with its `DetectedIssueEvidence`. These four models record only the actions taken on the coding gap. A coding gap event's `detected_issue` foreign key is nullable, so expect events without an associated `DetectedIssue`.
These are audit records of create, validate, assess, and defer actions — useful for reporting, deduplication logic, and risk adjustment and HCC (Hierarchical Condition Category) coding gap analytics. A plugin does not perform these actions through these models. Each is performed instead through its own command — the Create Coding Gap, Validate Coding Gap, Assess Coding Gap, and Defer Coding Gap commands respectively.
##  Basic usage 
To get a coding gap event by identifier, use the `get` method on the model manager. Each of the four models is imported from `canvas_sdk.v1.data`:
    ```python
    from canvas_sdk.v1.data import CreateCodingGapEvent
    create_event = CreateCodingGapEvent.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    ```
All four models expose the same manager, so `get`, `filter`, and `committed` are available on each.
##  Accessing events from a patient or note 
The coding gap events for a patient or note are reachable through reverse accessors. For each model, the accessor name is the same on `Patient` and on `Note`:
Model| Patient & Note reverse accessor| DetectedIssue reverse accessor  
---|---|---  
CreateCodingGapEvent| `created_detected_issues`| `created_coding_gap_events`  
ValidateCodingGapEvent| `assessed_detected_issues`| `validated_coding_gap_events`  
AssessCodingGapEvent| `assessed_coding_gaps`| `assessed_coding_gap_events`  
DeferCodingGapEvent| `deferred_detected_issues`| `deferred_coding_gap_events`  
For a patient, use the accessor on the `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    create_events = patient.created_detected_issues.all()
    ```
The same records are reachable from the note they were recorded on, with the matching accessor on the `Note` object:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    defer_events = note.deferred_detected_issues.all()
    ```
##  Accessing events from a detected issue 
For a given coding gap, each model's events are reachable from the [DetectedIssue](/sdk/data-detected-issue/) through its own reverse accessor:
Model| DetectedIssue reverse accessor  
---|---  
CreateCodingGapEvent| `created_coding_gap_events`  
ValidateCodingGapEvent| `validated_coding_gap_events`  
AssessCodingGapEvent| `assessed_coding_gap_events`  
DeferCodingGapEvent| `deferred_coding_gap_events`  
    ```python
    from canvas_sdk.v1.data.detected_issue import DetectedIssue
    detected_issue = DetectedIssue.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    create_events = detected_issue.created_coding_gap_events.all()
    ```
##  Assessed coding gaps on a condition 
`AssessCodingGapEvent` records the conditions a coding gap was assessed against through its `conditions` many-to-many relationship:
    ```python
    from canvas_sdk.v1.data import AssessCodingGapEvent
    assess_event = AssessCodingGapEvent.objects.get(id="0b2f2f8c-3c2c-4d9e-9a1a-2b6a4c7d8e90")
    conditions = assess_event.conditions.all()
    ```
For a given condition, the assess events it was included in are reachable with the `assessed_coding_gaps` accessor on a `Condition` object:
    ```python
    from canvas_sdk.v1.data import Condition
    condition = Condition.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    assess_events = condition.assessed_coding_gaps.all()
    ```
##  Committed records 
The `committed` method returns records that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import CreateCodingGapEvent
    committed_create_events = CreateCodingGapEvent.objects.committed()
    ```
The `committed` method is available on all four managers.
##  Attributes 
###  CreateCodingGapEvent 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
detected_issue| [DetectedIssue](/sdk/data-detected-issue/#detectedissue)  
###  ValidateCodingGapEvent 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
detected_issue| [DetectedIssue](/sdk/data-detected-issue/#detectedissue)  
###  AssessCodingGapEvent 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
detected_issue| [DetectedIssue](/sdk/data-detected-issue/#detectedissue)  
conditions| [Condition](/sdk/data-condition)[]  
###  DeferCodingGapEvent 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
detected_issue| [DetectedIssue](/sdk/data-detected-issue/#detectedissue)  

---

# CommandTypeSetting

Source: https://docs.canvasmedical.com/sdk/data-command-type-setting/

##  Introduction 
The `CommandTypeSetting` model has one row for each command type available on the instance, with whether it is turned on. An administrator turns command types on and off in Canvas. Use it to leave out commands a provider cannot add, for example to skip suggesting a follow-up when the follow-up command is turned off.
A command type that isn't available on the instance has no row. Treat a missing row the same as a command type that is turned off.
##  Basic usage 
To check whether one command type is turned on, filter on its schema key and `active`:
    ```python
    from canvas_sdk.v1.data import CommandTypeSetting
    follow_up_on = CommandTypeSetting.objects.filter(schema_key="followUp", active=True).exists()
    if follow_up_on:
        ...
    ```
The check returns `False` both when the command type is turned off and when it has no row. A `get` call for a schema key with no row raises `CommandTypeSetting.DoesNotExist`.
##  Filtering 
Command type settings can be filtered by any attribute that exists on the model.
###  Active command types 
To get the schema keys of every command type turned on for the instance, in one query:
    ```python
    from canvas_sdk.v1.data import CommandTypeSetting
    active = set(
        CommandTypeSetting.objects.filter(active=True).values_list("schema_key", flat=True)
    )
    ```
##  Attributes 
###  CommandTypeSetting 
Field Name| Type  
---|---  
dbid| Integer  
schema_key| String  
active| Boolean  
  - **dbid** : The internal database primary key.
  - **schema_key** : The command type's schema key, the same value as [`Command.schema_key`](/sdk/data-command/#command) (e.g., `followUp`, `refer`, `prescribe`).
  - **active** : Whether the command type is turned on for the instance.

---

# Command

Source: https://docs.canvasmedical.com/sdk/data-command/

##  Introduction 
The `Command` model represents a [command](/sdk/commands/) in a note.
Private Notes commands (`schema_key` of `privateNotes`) are not available through this model. Only the provider who writes a private note can see it, so `Command.objects` and `note.commands` never return these commands, even when you filter by their `schema_key` or `id`.
##  Basic usage 
To get a command by identifier, use the `get` method on the `Command` model manager:
    ```python
    from canvas_sdk.v1.data.command import Command
    command = Command.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
##  Filtering 
Commands can be filtered by any attribute that exists on the model.
Filtering for commands is done with the `filter` method on the `Command` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.command import Command
    commands = Command.objects.filter(state="committed")
    ```
##  Command types and data 
When events are fired as part of [Command Lifecycle Events](/sdk/events/#command-lifecycle-events), the `self.target` value that is available within a plugin will contain the `id` value of the command. For example:
    ```python
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from logger import log
    class MyHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.REASON_FOR_VISIT_COMMAND__POST_UPDATE),
        ]
        def compute(self) -> list[Effect]:
            log.info(self.target) # logs the Command id
    ```
Using this value, the `Command` model can be queried to fetch additional data about the command. Two main fields to pay attention to here are the `schema_key` and `data` fields. The `schema_key` field contains the type of the command, while the `data` field contains a JSON object with command data as key/value pairs:
    ```python
    import json
    from canvas_sdk.effects import Effect
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.command import Command
    from logger import log
    class MyHandler(BaseHandler):
        def compute(self) -> list[Effect]:
            command_instance = Command.objects.get(id=self.target)
            log.info(command_instance.schema_key)
            log.info(json.dumps(command_instance.data, indent=2))
    ```
For example, for a _Reason For Visit_ command, the preceding code would log the following lines:
    ```sh
    reasonForVisit
    {
      "coding": {
        "text": "Accident-prone",
        "extra": null,
        "value": "165002",
        "disabled": false,
        "annotations": null,
        "description": null
      },
      "comment": "Patient would like to discuss condition."
    }
    ```
The following table shows the different command `schema_key` values with links to their respective [Command Modules](/sdk/commands). The attributes shown in each corresponding entry contain the structure that will appear in the `data` JSON field of each `Command`.
Schema Key| Command Data  
---|---  
addCondition| [AddCondition](/sdk/commands/#addcondition)  
adjustPrescription| [AdjustPrescription](/sdk/commands/#adjustprescription)  
allergy| [Allergy](/sdk/commands/#allergy)  
assess| [Assess](/sdk/commands/#assess)  
changeMedication| [ChangeMedication](/sdk/commands/#changemedication)  
closeGoal| [CloseGoal](/sdk/commands/#closegoal)  
diagnose| [Diagnose](/sdk/commands/#diagnose)  
familyHistory| [FamilyHistory](/sdk/commands/#familyhistory)  
followUp| [FollowUp](/sdk/commands/#followup)  
goal| [Goal](/sdk/commands/#goal)  
hpi| [HistoryOfPresentIllness](/sdk/commands/#historyofpresentillness)  
imagingOrder| [ImagingOrder](/sdk/commands/#imagingorder)  
instruct| [Instruct](/sdk/commands/#instruct)  
labOrder| [LabOrder](/sdk/commands/#laborder)  
medicalHistory| [MedicalHistory](/sdk/commands/#medicalhistory)  
medicationStatement| [MedicationStatement](/sdk/commands/#medicationstatement)  
orderDme| [OrderDme](/sdk/commands/#orderdme)  
perform| [Perform](/sdk/commands/#perform)  
plan| [Plan](/sdk/commands/#plan)  
pocLabTest| [POCLabTest](/sdk/commands/#poclabtest)  
prescribe| [Prescribe](/sdk/commands/#prescribe)  
questionnaire| [Questionnaire](/sdk/commands/#questionnaire)  
reasonForVisit| [ReasonForVisit](/sdk/commands/#reasonforvisit)  
refer| [Refer](/sdk/commands/#refer)  
refill| [Refill](/sdk/commands/#refill)  
removeAllergy| [RemoveAllergy](/sdk/commands/#removeallergy)  
removePastMedicalHistory| [RemovePastMedicalHistory](/sdk/commands/#remove-past-medical-history)  
resolveCondition| [ResolveCondition](/sdk/commands/#resolve-condition)  
stopMedication| [StopMedication](/sdk/commands/#stopmedication)  
surgicalHistory| [SurgicalHistory](/sdk/commands/#surgicalhistory)  
task| [Task](/sdk/commands/#task)  
updateDiagnosis| [UpdateDiagnosis](/sdk/commands/#updatediagnosis)  
updateGoal| [UpdateGoal](/sdk/commands/#updategoal)  
vitals| [Vitals](/sdk/commands/#vitals)  
**PLEASE NOTE** the Commands Module is under development and Canvas is working to migrate all commands to be available. This means that some commands are not able to emit events available in plugins, and historical commands created prior to their Commands Module availability may not be able to be queried using the data module. [This product updates table](/product-updates/commands-module/) shows the commands and their release statuses. If a command in a chart is not available by querying the `Command` data model, the data is still available to be queried using corresponding data models (i.e. [Questionnaire](/sdk/data-questionnaire/), [ImagingOrder](/sdk/data-imaging/), etc.).
##  The anchor object 
Most commands write a record of their own when they are entered: a Diagnose command creates a `Condition`, a Prescribe command creates a `Prescription`, and so on. That record is the command's anchor object, and `anchor_object` returns it as an instance of the matching data model:
    ```python
    from canvas_sdk.v1.data.command import Command
    command = Command.objects.get(id="c1b5a4d2-7e3f-4a8b-9c6d-2f1e0a9b8c7d")
    anchor = command.anchor_object
    ```
`anchor_object_type` and `anchor_object_dbid` identify the record, and `anchor_object` looks it up for you. It returns `None` when the command has no anchor recorded.
`schema_key`| `anchor_object` returns  
---|---  
`addCondition`| [Condition](/sdk/data-condition/#condition)  
`adjustDiagnosis`| [Assessment](/sdk/data-assessment/#assessment)  
`adjustPrescription`| [Prescription](/sdk/data-prescription/#prescription)  
`adjustProtocol`| [ProtocolOverride](/sdk/data-protocol-override/#protocoloverride)  
`allergy`| [AllergyIntolerance](/sdk/data-allergy-intolerance/#allergyintolerance)  
`approveChange`| [PrescriptionChangeResponse](/sdk/data-prescription-change-response/#prescriptionchangeresponse)  
`approveRefill`| [Prescription](/sdk/data-prescription/#prescription)  
`assess`| [Assessment](/sdk/data-assessment/#assessment)  
`assessCodingGap`| [AssessCodingGapEvent](/sdk/data-coding-gap-event/#assesscodinggapevent)  
`cancelPrescription`| [CancelPrescription](/sdk/data-cancel-prescription/#cancelprescription)  
`changeMedication`| [ChangeMedication](/sdk/data-change-medication/#changemedication)  
`chartSectionReview`| [ChartSectionReview](/sdk/data-chart-section-review/#chartsectionreview)  
`clipboard`| [Clipboard](/sdk/data-clipboard/#clipboard)  
`closeGoal`| [UpdateGoal](/sdk/data-goal/#updategoal)  
`createCodingGap`| [CreateCodingGapEvent](/sdk/data-coding-gap-event/#createcodinggapevent)  
`deferCodingGap`| [DeferCodingGapEvent](/sdk/data-coding-gap-event/#defercodinggapevent)  
`denyChange`| [PrescriptionChangeResponse](/sdk/data-prescription-change-response/#prescriptionchangeresponse)  
`denyRefill`| [Prescription](/sdk/data-prescription/#prescription)  
`device`| [Device](/sdk/data-device/#device)  
`diagnose`| [Condition](/sdk/data-condition/#condition)  
`educationalMaterial`| [EducationalMaterial](/sdk/data-educational-material/#educationalmaterial)  
`exam`| [Interview](/sdk/data-questionnaire/#interview)  
`familyHistory`| [FamilyHistory](/sdk/data-family-history/#familyhistory)  
`followUp`| [FollowUp](/sdk/data-follow-up/#followup)  
`goal`| [Goal](/sdk/data-goal/#goal)  
`hpi`| [HistoryOfPresentIllness](/sdk/data-history-present-illness/#historyofpresentillness)  
`imagingOrder`| [ImagingOrder](/sdk/data-imaging/#imagingorder)  
`imagingReview`| [ImagingReview](/sdk/data-imaging/#imagingreview)  
`immunizationStatement`| [ImmunizationStatement](/sdk/data-immunization/#immunizationstatement)  
`immunize`| [Immunization](/sdk/data-immunization/#immunization)  
`instruct`| [Instruction](/sdk/data-instruction/#instruction)  
`labOrder`| [LabOrder](/sdk/data-labs/#laborder)  
`labReview`| [LabReview](/sdk/data-labs/#labreview)  
`medicalHistory`| [Condition](/sdk/data-condition/#condition)  
`medicationStatement`| [MedicationStatement](/sdk/data-medication-statement/#medicationstatement)  
`orderDme`| [DmeOrder](/sdk/data-dme/#dmeorder)  
`perform`| [Procedure](/sdk/data-procedure/#procedure)  
`plan`| [Plan](/sdk/data-plan/#plan)  
`pocLabTest`| [LabReport](/sdk/data-labs/#labreport)  
`prescribe`| [Prescription](/sdk/data-prescription/#prescription)  
`questionnaire`| [Interview](/sdk/data-questionnaire/#interview)  
`reasonForVisit`| [ReasonForVisit](/sdk/data-reason-for-visit/#reasonforvisit)  
`refer`| [Referral](/sdk/data-referral/#referral)  
`reference`| [Reference](/sdk/data-reference/#reference)  
`referralReview`| [ReferralReview](/sdk/data-referral/#referralreview)  
`refill`| [Prescription](/sdk/data-prescription/#prescription)  
`removeAllergy`| [RemoveAllergyEvent](/sdk/data-remove-allergy-event/#removeallergyevent)  
`removePastMedicalHistory`| [RemovePastMedicalHistoryEvent](/sdk/data-remove-past-medical-history-event/#removepastmedicalhistoryevent)  
`resolveCondition`| [ResolveConditionEvent](/sdk/data-resolve-condition-event/#resolveconditionevent)  
`ros`| [Interview](/sdk/data-questionnaire/#interview)  
`snoozeProtocol`| [ProtocolOverride](/sdk/data-protocol-override/#protocoloverride)  
`stopMedication`| [StopMedicationEvent](/sdk/data-stop-medication-event/#stopmedicationevent)  
`structuredAssessment`| [Interview](/sdk/data-questionnaire/#interview)  
`surgicalHistory`| [Condition](/sdk/data-condition/#condition)  
`task`| [NoteTask](/sdk/data-task/#notetask)  
`updateDiagnosis`| [Condition](/sdk/data-condition/#condition)  
`updateGoal`| [UpdateGoal](/sdk/data-goal/#updategoal)  
`validateCodingGap`| [ValidateCodingGapEvent](/sdk/data-coding-gap-event/#validatecodinggapevent)  
`visualExamFinding`| [VisualExamFinding](/sdk/data-visual-exam-finding/#visualexamfinding)  
`vitals`| [VitalSignReading](/sdk/data-vital-sign-reading/#vitalsignreading)  
Custom commands| [CustomCommand](/sdk/data-custom-command/#customcommand)  
> **Warning:** `anchor_object` does not yet support the `uncategorizedDocumentReview` command, and reading it raises `LookupError`. Support is coming in an upcoming release. Until then, look the record up directly as shown below.
The `uncategorizedDocumentReview` anchor is available as [UncategorizedClinicalDocumentReview](/sdk/data-uncategorized-clinical-document/#uncategorizedclinicaldocumentreview); `anchor_object` cannot find it because the model goes by a different name. Look it up from `anchor_object_dbid` instead:
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocumentReview
    from canvas_sdk.v1.data.command import Command
    command = Command.objects.get(id="c1b5a4d2-7e3f-4a8b-9c6d-2f1e0a9b8c7d")
    review = UncategorizedClinicalDocumentReview.objects.get(dbid=command.anchor_object_dbid)
    ```
If a command's anchor record has been deleted, `anchor_object` raises the data model's `DoesNotExist` rather than returning `None`.
##  Attributes 
###  Command 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
state| String  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
schema_key| String  
data| JSON  
origination_source| String  
custom_html| String (optional)  
anchor_object_type| String  
anchor_object_dbid| Integer  
anchor_object| Model (optional)  
metadata| QuerySet[[CommandMetadata](/sdk/data-command/#commandmetadata)]  
The `custom_html` field stores HTML content that is rendered alongside the command in the note. This field is optional and defaults to `None`. Use the [`set_custom_html`](/sdk/commands/#set_custom_html) method to set or clear this field on a staged command.
###  CommandMetadata 
`CommandMetadata` stores custom key-value pairs associated with a command. Metadata can be upserted using the `upsert_metadata` method on any command effect class — see [CommandMetadata Effect](/sdk/effect-command-metadata/) for full details.
    ```python
    from canvas_sdk.v1.data.command import CommandMetadata
    # Get all metadata for a command
    metadata_entries = CommandMetadata.objects.filter(command__id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    # Get a specific metadata value
    entry = CommandMetadata.objects.get(command__id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35", key="my_plugin:priority")
    print(entry.value)
    ```
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
command| [Command](/sdk/data-command/#command)  
key| String  
value| String  

---

# CompoundMedication

Source: https://docs.canvasmedical.com/sdk/data-compound-medication/

##  Introduction 
The `CompoundMedication` model represents a compound medication formulation that can be prescribed to patients. Compound medications are customized medications mixed or prepared by a compounding pharmacy according to a prescription.
##  Basic usage 
To get a compound medication by identifier, use the `get` method on the `CompoundMedication` model manager:
    ```python
    from canvas_sdk.v1.data.compound_medication import CompoundMedication
    compound_medication = CompoundMedication.objects.get(id="123")
    ```
##  Filtering 
Compound medications can be filtered by any attribute that exists on the model.
Filtering for compound medications is done with the `filter` method on the `CompoundMedication` model manager.
###  By attribute 
Specify attributes with `filter` to filter by those attributes:
    ```python
    from canvas_sdk.v1.data.compound_medication import CompoundMedication
    # Get all active compound medications
    active_medications = CompoundMedication.objects.filter(active=True)
    # Get compound medications by formulation
    compound_medications = CompoundMedication.objects.filter(formulation="Testosterone 200mg/mL in Grapeseed Oil")
    # Get all Schedule II controlled substances
    schedule_ii_medications = CompoundMedication.objects.filter(controlled_substance="II")
    # Get compound medications by potency unit
    tablet_medications = CompoundMedication.objects.filter(potency_unit_code="C48542")
    ```
###  Multiple filters 
You can combine multiple filters:
    ```python
    from canvas_sdk.v1.data.compound_medication import CompoundMedication
    # Get active compound medications that are controlled substances
    controlled_active = CompoundMedication.objects.filter(
      active=True,
      controlled_substance__in=["II", "III", "IV", "V"]
    )
    ```
##  Attributes 
###  CompoundMedication 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
id| UUID  
active| Boolean  
formulation| String  
potency_unit_code| PotencyUnit  
controlled_substance| ControlledSubstanceSchedule  
controlled_substance_ndc| String  
compound_medication| QuerySet[[Prescription](/sdk/data-prescription/#prescription)]  
##  Enumeration types 
###  PotencyUnit 
Value| Label  
---|---  
C62412| Applicator  
C54564| Blister  
C64696| Caplet  
C48480| Capsule  
C64933| Each  
C53499| Film  
C48155| Gram  
C69124| Gum  
C48499| Implant  
C62276| Insert  
C48504| Kit  
C120263| Lancet  
C48506| Lozenge  
C28254| Milliliter  
C48521| Packet  
C65032| Pad  
C48524| Patch  
C120216| Pen Needle  
C62609| Ring  
C53502| Sponge  
C53503| Stick  
C48538| Strip  
C48539| Suppository  
C53504| Swab  
C48542| Tablet  
C48548| Troche  
C38046| Unspecified  
C48552| Wafer  
###  ControlledSubstanceSchedule 
Key| Value| Label  
---|---|---  
SCHEDULE_NOT_SCHEDULED| N| None  
SCHEDULE_II| II| Schedule II  
SCHEDULE_III| III| Schedule III  
SCHEDULE_IV| IV| Schedule IV  
SCHEDULE_V| V| Schedule V  
##  Notes 
  - The `formulation` field has a maximum length of 105 characters (as defined by Surescripts).

---

# Condition

Source: https://docs.canvasmedical.com/sdk/data-condition/

##  Introduction 
The `Condition` model represents a clinical condition, problem, diagnosis, or other event, situation, issue, or clinical concept that has risen to a level of concern.
##  Basic usage 
To get a condition by identifier, use the `get` method on the `Condition` model manager:
    ```python
    from canvas_sdk.v1.data.condition import Condition
    condition = Condition.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the conditions for a patient can be accessed with the `conditions` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    conditions = patient.conditions.all()
    ```
If you have a patient ID, you can get the conditions for the patient with the `for_patient` method on the `Condition` model manager:
    ```python
    from canvas_sdk.v1.data.condition import Condition
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    condition = Condition.objects.for_patient(patient_id)
    ```
##  Codings 
The codings for a condition can be accessed with the `codings` attribute on an `Condition` object:
    ```python
    from canvas_sdk.v1.data.condition import Condition
    from logger import log
    condition = Condition.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in condition.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
##  Filtering 
Conditions can be filtered by any attribute that exists on the model.
Filtering for conditions is done with the `filter` method on the `Condition` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.condition import Condition
    conditions = Condition.objects.filter(onset_date__gte="2024-10-15")
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The `find` method on the model manager is used to perform `ValueSet` filtering:
    ```python
    from canvas_sdk.v1.data.condition import Condition
    from canvas_sdk.value_set.v2022.condition import Diabetes
    conditions = Condition.objects.find(Diabetes)
    ```
##  Attributes 
###  Condition 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
onset_date| Date  
resolution_date| Date  
clinical_status| ClinicalStatus  
codings| ConditionCoding[]  
lab_order_reason_conditions| [LabOrderReasonConditionCoding](/sdk/data-labs/#laborderreasoncondition)[]  
notes| String  
surgical| Boolean  
assessed_coding_gaps| [AssessCodingGapEvent](/sdk/data-coding-gap-event/#assesscodinggapevent)[]  
assessments| [Assessment](/sdk/data-assessment/#assessment)[]  
resolutions| [ResolveConditionEvent](/sdk/data-resolve-condition-event/#resolveconditionevent)[]  
past_medical_history_removals| [RemovePastMedicalHistoryEvent](/sdk/data-remove-past-medical-history-event/#removepastmedicalhistoryevent)[]  
###  ConditionCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
condition| Condition  
##  Enumeration types 
###  ClinicalStatus 
Value| Label  
---|---  
active| active  
relapse| relapse  
remission| remission  
resolved| resolved  
investigative| investigative  

---

# ContentType

Source: https://docs.canvasmedical.com/sdk/data-content-type/

##  Introduction 
The `ContentType` model exposes Django content types. Use it to resolve the content type id for a given model, which is required when working with generic relations (such as [document references](/sdk/data-document-reference)) and when generating permalinks.
A content type is identified by two **stable** values — `app_label` and `model` — that are the same on every Canvas instance. Its `dbid` (the content type id) is a per-database auto-increment that **is not stable across environments**. Always resolve the `dbid` at runtime from the `app_label` and `model`; never hardcode a content type id, or it will point at the wrong model in another environment.
##  Basic usage 
To get a content type by its database id, use the `get` method on the `ContentType` model manager:
    ```python
    from canvas_sdk.v1.data import ContentType
    content_type = ContentType.objects.get(dbid=42)
    ```
##  Resolving a content type at runtime 
Because the `dbid` differs per environment, look the content type up by its stable `app_label` and `model`, then read `dbid` from the result:
    ```python
    from canvas_sdk.v1.data import ContentType
    content_type = ContentType.objects.filter(app_label="api", model="note").first()
    if content_type:
        # Resolved for this environment — safe to use for a generic relation or permalink.
        content_type_id = content_type.dbid
    ```
##  Filtering 
Content types can be filtered by any attribute that exists on the model.
Filtering for content types is done with the `filter` method on the `ContentType` model manager.
###  By model 
To find the content type for a specific model, filter by `app_label` and `model`:
    ```python
    from canvas_sdk.v1.data import ContentType
    content_type = ContentType.objects.filter(app_label="api", model="note").first()
    if content_type:
        print(f"Content type id: {content_type.dbid}")
    ```
##  app_label and model for data module models 
Use these stable values to resolve a content type with `ContentType.objects.filter(app_label=..., model=...)`. The `model` value is the lowercased Django model name, and most data module models live under the `api` app. This list is not exhaustive — any model not shown here can be resolved the same way once you know its `app_label` and `model`.
###  `api` app 
SDK data model| app_label| model  
---|---|---  
[AllergyIntolerance](/sdk/data-allergy-intolerance/)| `api`| `allergyintolerance`  
[Appointment](/sdk/data-appointment/)| `api`| `appointment`  
[Assessment](/sdk/data-assessment/)| `api`| `assessment`  
[BannerAlert](/sdk/data-banner-alert/)| `api`| `banneralert`  
[ChartSectionReview](/sdk/data-chart-section-review/)| `api`| `chartsectionreview`  
[Condition](/sdk/data-condition/)| `api`| `condition`  
[Coverage](/sdk/data-coverage/)| `api`| `coverage`  
[DetectedIssue](/sdk/data-detected-issue/)| `api`| `detectedissue`  
[Device](/sdk/data-device/)| `api`| `device`  
[DiagnosticReport](/sdk/data-labs/#diagnosticreport)| `api`| `diagnosticreport`  
[DocumentReference](/sdk/data-document-reference/)| `api`| `documentreference`  
[Encounter](/sdk/data-encounter/)| `api`| `encounter`  
[Facility](/sdk/data-facility/)| `api`| `facility`  
[Goal](/sdk/data-goal/)| `api`| `goal`  
[ImagingOrder](/sdk/data-imaging/)| `api`| `imagingorder`  
[ImagingReport](/sdk/data-imaging/)| `api`| `imagingreport`  
[ImagingReview](/sdk/data-imaging/)| `api`| `imagingreview`  
[Immunization](/sdk/data-immunization/)| `api`| `immunization`  
[Instruction](/sdk/data-instruction/)| `api`| `instruction`  
[Interview](/sdk/data-questionnaire/)| `api`| `interview`  
[LabOrder](/sdk/data-labs/)| `api`| `laborder`  
[LabReport](/sdk/data-labs/)| `api`| `labreport`  
[LabValue](/sdk/data-labs/)| `api`| `labvalue`  
[Letter](/sdk/data-letter/)| `api`| `letter`  
[Medication](/sdk/data-medication/)| `api`| `medication`  
[MedicationStatement](/sdk/data-medication-statement/)| `api`| `medicationstatement`  
[Message](/sdk/data-message/)| `api`| `message`  
[Note](/sdk/data-note/)| `api`| `note`  
[Observation](/sdk/data-observation/)| `api`| `observation`  
[Organization](/sdk/data-organization/)| `api`| `organization`  
[OrganizationalEntity](/sdk/data-organizational-entity/)| `api`| `organizationalentity`  
[Patient](/sdk/data-patient/)| `api`| `patient`  
[PatientConsent](/sdk/data-patient-consent/)| `api`| `patientconsent`  
[PatientGroup](/sdk/data-patient-group/)| `api`| `patientgroup`  
[PracticeLocation](/sdk/data-practicelocation/)| `api`| `practicelocation`  
[Prescription](/sdk/data-prescription/)| `api`| `prescription`  
[Questionnaire](/sdk/data-questionnaire/)| `api`| `questionnaire`  
[ReasonForVisit](/sdk/data-reason-for-visit/)| `api`| `reasonforvisit`  
[Referral](/sdk/data-referral/)| `api`| `referral`  
[Staff](/sdk/data-staff/)| `api`| `staff`  
[StopMedicationEvent](/sdk/data-stop-medication-event/)| `api`| `stopmedicationevent`  
[Task](/sdk/data-task/)| `api`| `task`  
[Team](/sdk/data-team/)| `api`| `team`  
[UncategorizedClinicalDocument](/sdk/data-uncategorized-clinical-document/)| `api`| `uncategorizedclinicaldocument`  
[VisualExamFinding](/sdk/data-visual-exam-finding/)| `api`| `visualexamfinding`  
###  Other apps 
Some models live in a different Django app, so their `app_label` is not `api`:
SDK data model| app_label| model  
---|---|---  
[Command](/sdk/data-command/)| `commands`| `command`  
[Application](/sdk/data-application/)| `plugin_io`| `application`  
[PluginCommand](/sdk/data-plugin-command/)| `plugin_io`| `plugincommand`  
[Calendar](/sdk/data-calendar/)| `calendars`| `calendar`  
[ExternalEvent](/sdk/data-external-event/)| `data_integration`| `externalevent`  
[ServiceProvider](/sdk/data-serviceprovider/)| `data_integration`| `serviceprovider`  
[ChargeDescriptionMaster](/sdk/data-charge-description-master/)| `quality_and_revenue`| `chargedescriptionmaster`  
[Claim](/sdk/data-claim/)| `quality_and_revenue`| `claim`  
[PayorSpecificCharge](/sdk/data-payor-specific-charge/)| `quality_and_revenue`| `payorspecificcharge`  
##  Attributes 
###  ContentType 
Field Name| Type  
---|---  
dbid| Integer  
app_label| String  
model| String  
  - **dbid** : The internal database primary key, which is the content type id used for generic relations and permalinks. This value is environment-specific — resolve it at runtime rather than hardcoding it.
  - **app_label** : The label of the application the model belongs to (e.g., `api`).
  - **model** : The lowercased name of the model (e.g., `note`).

---

# Coverage

Source: https://docs.canvasmedical.com/sdk/data-coverage/

##  Introduction 
The `Coverage` model represents insurance coverage linked to [Patients](/sdk/data-patient/#patient). Coverages are linked to [Patient](/sdk/data-patient/#patient) instances, as well as `Transactor` instances, which represent the issuer for the corresponding coverage. `Coverage`s also have an associated `EligibilitySummary`, which provides the most up-to-date copay and coinsurance values.
To create or change coverages from a plugin, use the [Coverage effect](/sdk/effect-coverage/).
Coverages can also be linked to a [`Snapshot`](/sdk/data-snapshot/#snapshot), which provides access to insurance card images. Card images are captured via the Canvas iOS application, uploaded through the coverages modal, or attached by a plugin with the [Coverage effect](/sdk/effect-coverage/#card-images).
##  Usage 
The `Coverage` model can be used to find all of the coverages defined in a Canvas instance, whether overall or for a particular patient. For example, to find all of the current coverages for a patient, the `Patient.coverages` method can be used:
    ```python
    >>> import arrow
    >>> from canvas_sdk.v1.data.patient import Patient
    >>> patient_1 = Patient.objects.get(id="a74592ae8a6c4d0ebe0799d3fb3713d1")
    >>> patient_1_current_coverages = patient_1.coverages.filter(coverage_end_date__gt=arrow.now().date().isoformat())
    >>> print([coverage.issuer.name for coverage in patient_1_current_coverages])
    ['AVALON HEALTHCARE SOLUTIONS CAPITAL BLUE CROSS']
    ```
Alternatively, to find all of the `Coverage` instances issed by a particular issuer/transactor, the `Transactor` model can be queried:
    ```python
    >>> from canvas_sdk.v1.data.coverage import Coverage, Transactor
    >>> transactor_1 = Transactor.objects.get(payer_id="AVA03")
    >>> transactor_coverages = Coverage.objects.filter(issuer=transactor_1)
    >>> print(transactor_coverages)
    <QuerySet [<Coverage: id=89793979-dbff-4a53-b928-75db973c2bdc>, <Coverage: id=423c0f77-8083-4cc1-8e29-2c7d348281e4>]>
    >>>
    ```
Find the latest eligibility summary for a patient:
    ```python
        from canvas_sdk.v1.data.coverage import Coverage, EligibilitySummary
        coverage = Coverage.objects.get(id="a74592ae-8a6c-4d0e-be07-99d3fb3713d1")
        elig_summary_from_model = EligibilitySummary.objects.filter(coverage=coverage).first()
        elig_summary_from_cvg = coverage.eligibility_summary
        if elig_summary_from_model:
            print(elig_summary_from_model.copay_cents, elig_summary_from_model.coinsurance) # 1000 5
        if elig_summary_from_cvg:
            print(elig_summary_from_cvg.copay_cents, elig_summary_from_cvg.coinsurance) # 1000 5
    ```
Access insurance card images through the coverage's snapshot:
    ```python
    from canvas_sdk.v1.data.coverage import Coverage
    coverage = Coverage.objects.get(id="a74592ae-8a6c-4d0e-be07-99d3fb3713d1")
    if coverage.snapshot:
        for image in coverage.snapshot.images.all():
            print(image.image_url)  # Presigned S3 URL for the insurance card image
    ```
##  Eligibility status 
`Coverage.eligibility_status` returns the [`EligibilityResponseStatus`](/sdk/data-eligibility-response/#eligibilityresponsestatus) of the coverage's most recent [`EligibilityResponse`](/sdk/data-eligibility-response/#eligibilityresponse). It returns `UNKNOWN` when the coverage has never been checked (it has no eligibility responses):
    ```python
    from canvas_sdk.v1.data.coverage import Coverage
    from canvas_sdk.v1.data.eligibility_response import EligibilityResponseStatus
    coverage = Coverage.objects.get(id="a74592ae-8a6c-4d0e-be07-99d3fb3713d1")
    if coverage.eligibility_status == EligibilityResponseStatus.ACTIVE:
        print("Coverage is active")
    ```
`Coverage.eligibility_status` returns `NOT_APPLICABLE` for a self-pay coverage, meaning one whose issuer has a `payer_id` of `PATIENT`. It resolves this case before consulting the stored eligibility responses, so a stale `FAILED` response left on a self-pay coverage is never surfaced.
That is also what `Transactor.supports_eligibility_check` reports: it is `False` for the self-pay payer, whose `payer_id` is `PATIENT`, and `True` for every other issuer.
Because it is computed on each access rather than stored, `eligibility_status` cannot be used in `filter()`. Filter on the coverage's [eligibility responses](/sdk/data-eligibility-response/#eligibilityresponse) instead, or read the property once you have the coverage in hand.
A single [`EligibilityResponse.status`](/sdk/data-eligibility-response/#eligibilityresponse), by contrast, never resolves to `UNKNOWN` — that value belongs to the coverage, which has no response to defer to. To react to eligibility changes rather than poll for them, subscribe to the [eligibility response events](/sdk/events/#eligibility-responses). Those fire only when a response is saved, so a coverage that has never been checked emits no event at all: a plugin that has to catch never-verified coverages should read `eligibility_status` rather than rely on the events alone.
##  Filtering 
The `filter` method can be used to filter by desired attributes. The following examples show commonly used operations to filter coverage data:
**Show a Patient's Coverages in order of Rank (Primary, Secondary, etc.)**
    ```python
    >>> from canvas_sdk.v1.data.patient import Patient
    >>> patient_1 = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> patient_coverages = patient_1.coverages.all().order_by("coverage_rank")
    >>> print([(coverage.issuer.name, coverage.coverage_rank,) for coverage in patient_coverages])
    [('AVALON HEALTHCARE SOLUTIONS CAPITAL BLUE CROSS', 1), ('Blue Cross Blue Shield of Arizona Advantage', 2)]
    ```
**Find All Expired Coverages**
    ```python
    >>> import arrow
    >>> from canvas_sdk.v1.data.coverage import Coverage
    >>> expired_coverages = Coverage.objects.filter(coverage_end_date__lt=arrow.now().date().isoformat())
    >>> print([f"{coverage.issuer.name} expired {coverage.coverage_end_date.isoformat()}" for coverage in expired_coverages])
    ['Blue Cross Blue Shield of Arizona Advantage expired 2025-01-10']
    ```
##  Attributes 
###  Coverage 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
guarantor| [Patient](/sdk/data-patient/#patient)  
subscriber| [Patient](/sdk/data-patient/#patient)  
subscriber_identifier| String  
patient_relationship_to_subscriber| CoverageRelationshipCode  
issuer| Transactor  
id_number| String  
plan| String  
sub_plan| String  
group| String  
sub_group| String  
employer| String  
coverage_start_date| Date  
coverage_end_date| Date  
coverage_rank| CoverageRank  
state| CoverageState  
plan_type| CoverageType  
coverage_type| TransactorCoverageType  
issuer_address| TransactorAddress  
issuer_phone| TransactorPhone  
comments| Text  
stack| CoverageStack  
snapshot| [Snapshot](/sdk/data-snapshot/#snapshot)  
eligibility_summary| EligibilitySummary  
eligibility_status| [EligibilityResponseStatus](/sdk/data-eligibility-response/#eligibilityresponsestatus) (computed)  
claim_coverages| [ClaimCoverage](/sdk/data-claim/#claimcoverage)[]  
requests| [EligibilityRequest](/sdk/data-eligibility-response/#eligibilityrequest)[]  
eligibility_responses| [EligibilityResponse](/sdk/data-eligibility-response/#eligibilityresponse)[]  
###  Transactor 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
payer_id| String  
name| String  
type| String  
transactor_type| TransactorType  
clearinghouse_payer| Boolean  
institutional| Boolean  
institutional_enrollment_req| Boolean  
professional| Boolean  
professional_enrollment_req| Boolean  
era| Boolean  
era_enrollment_req| Boolean  
eligibility| Boolean  
eligibility_enrollment_req| Boolean  
workers_comp| Boolean  
secondary_support| Boolean  
claim_fee| Boolean  
remit_fee| Boolean  
state| String  
description| String  
active| Boolean  
use_provider_for_eligibility| Boolean  
supports_eligibility_check| Boolean (computed)  
use_for_submission| Transactor  
used_for_submission_by| Transactor[]  
coverage_types| TransactorCoverageType[]  
vaccines| [Vaccine](/sdk/data-vaccine/#vaccine)[]  
addresses| TransactorAddress[]  
coverages| Coverage[]  
phones| TransactorPhone[]  
specific_charges| [PayorSpecificCharge](/sdk/data-payor-specific-charge/#payorspecificcharge)[]  
remits| [BaseRemittanceAdvice](/sdk/data-posting/#baseremittanceadvice)[]  
###  TransactorAddress 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
line1| String  
line2| String  
city| String  
district| String  
state_code| String  
postal_code| String  
use| [AddressUse](/sdk/data-enumeration-types/#addressuse)  
type| [AddressType](/sdk/data-enumeration-types/#addresstype)  
longitude| Float  
latitude| Float  
start| Date  
end| Date  
country| String  
state| [AddressState](/sdk/data-enumeration-types/#addressstate)  
transactor| Transactor  
coverages| [Coverage](/sdk/data-coverage/#coverage)[]  
###  TransactorPhone 
Field Name| Type  
---|---  
id| UUIDField  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
value| String  
use| [ContactPointUse](/sdk/data-enumeration-types/#contactpointuse)  
use_notes| String  
rank| Integer  
state| [ContactPointState](/sdk/data-enumeration-types/#contactpointstate)  
transactor| Transactor  
coverages| [Coverage](/sdk/data-coverage/#coverage)[]  
###  EligibilitySummary 
Field Name| Type  
---|---  
id| UUIDField  
dbid| Integer  
created| DateTime  
modified| DateTime  
coverage| [Coverage](/sdk/data-coverage/#coverage)  
copay_cents| Integer  
coinsurance| Integer  
##  Enumeration types 
###  CoverageRank 
Value| Name| Label  
---|---|---  
1| PRIMARY| Primary  
2| SECONDARY| Secondary  
3| TERTIARY| Tertiary  
4| QUATERNARY| Quaternary  
5| QUINARY| Quinary  
###  CoverageStack 
Value| Label  
---|---  
IN_USE| In use  
OTHER| Other  
REMOVED| Removed  
###  CoverageState 
Value| Label  
---|---  
active| Active  
deleted| Deleted  
###  CoverageType 
Value| Label  
---|---  
commercial| Commercial  
workerscomp| Workers Comp  
bcbs| Blue Cross Blue Shield  
champus| Tricare/Champus  
medicaid| Medicaid  
medicare| Medicare  
other| Other  
tpa| Third Party Administrator  
motorvehicle| Motor Vehicle  
lien| Attorney/Lien  
pip| Personal Injury  
###  CoverageRelationshipCode 
Value| Label  
---|---  
18| Self  
01| Spouse  
19| Natural Child, insured has financial responsibility  
43| Natural Child, insured does not have financial responsibility  
17| Step Child  
10| Foster Child  
15| Ward of the Court  
20| Employee  
21| Unknown  
22| Handicapped Dependent  
39| Organ donor  
40| Cadaver donor  
05| Grandchild  
07| Niece/Nephew  
41| Injured Plaintiff  
23| Sponsored Dependent  
24| Minor Dependent of a Minor Dependent  
32| Mother  
33| Father  
04| Grandparent  
53| Life Partner  
29| Significant Other  
G8| Other  
###  TransactorCoverageType 
Value| Label  
---|---  
ANNU| annuity policy  
AUTOPOL| automobile  
CHAR| charity program  
COL| collision coverage policy  
CRIME| crime victim program  
DENTAL| dental care policy  
DENTPRG| dental program  
DIS| disability insurance policy  
DISEASE| disease specific policy  
DRUGPOL| drug policy  
EAP| employee assistance program  
EWB| employee welfare benefit plan policy  
ENDRENAL| end renal program  
EHCPOL| extended healthcare  
FLEXP| flexible benefit plan policy  
GOVEMP| government employee health program  
HIP| health insurance plan policy  
HMO| health maintenance organization policy  
HSAPOL| health spending account  
HIRISK| high risk pool program  
HIVAIDS| HIV-AIDS program  
IND| indigenous peoples health program  
LIFE| life insurance policy  
LTC| long term care policy  
MCPOL| managed care policy  
MANDPOL| mandatory health program  
MENTPOL| mental health policy  
MENTPRG| mental health program  
MILITARY| military health program  
pay| Pay  
POS| point of service policy  
PPO| preferred provider organization policy  
PNC| property and casualty insurance policy  
DISEASEPRG| public health program  
PUBLICPOL| public healthcare  
REI| reinsurance policy  
RETIRE| retiree health program  
SAFNET| safety net clinic program  
SOCIAL| social service program  
SUBSIDIZ| subsidized health program  
SUBSIDMC| subsidized managed care program  
SUBSUPP| subsidized supplemental health program  
SUBPOL| substance use policy  
SUBPRG| substance use program  
SURPL| surplus line insurance policy  
TLIFE| term life insurance policy  
UMBRL| umbrella liability insurance policy  
UNINSMOT| uninsured motorist policy  
ULIFE| universal life insurance policy  
VET| veteran health program  
VISPOL| vision care policy  
CANPRG| women's cancer detection program  
WCBPOL| worker's compensation  
###  TransactorType 
Value| Label  
---|---  
commercial| Commercial  
workerscomp| Workers Comp  
champus| Tricare/Champus  
medicaid| Medicaid  
medicare| Medicare  
medicare_advantage| Medicare Advantage  
CHIP| CHIP  
automobile| Automobile  
employer| Employer  
direct_care| Direct Care  
bcbs| Blue Cross Blue Shield

---

# CustomCommand

Source: https://docs.canvasmedical.com/sdk/data-custom-command/

##  Introduction 
The `CustomCommand` model is the anchor for a [custom command](/sdk/commands-custom-command/): the plugin-defined, read-only HTML content a plugin inserts into a note. Use this data model to read back the custom commands recorded on a chart. To insert one, use the [Custom Command](/sdk/commands-custom-command/) command class instead.
##  Basic usage 
To get a custom command by identifier, use the `get` method on the `CustomCommand` model manager:
    ```python
    from canvas_sdk.v1.data import CustomCommand
    custom_command = CustomCommand.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the custom commands for a patient can be accessed with the `custom_commands` attribute:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    custom_commands = patient.custom_commands.all()
    ```
The custom commands recorded on a note are reachable the same way, through the note's `custom_commands` attribute:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    custom_commands = note.custom_commands.all()
    ```
##  Committed records 
The `committed` method returns custom commands that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import CustomCommand
    committed_commands = CustomCommand.objects.committed()
    ```
##  Resolving the plugin registration 
The `plugin_command` property returns the [`PluginCommand`](/sdk/data-plugin-command/) registration the command was created from, resolved through the anchoring command's `schema_key`. It is `None` when the anchor has no command, or when its `schema_key` is not a registered plugin command:
    ```python
    custom_command = CustomCommand.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    plugin_command = custom_command.plugin_command
    if plugin_command:
        print(plugin_command.label)
    ```
##  Reading the command data 
The `data` property returns the anchoring [`Command`](/sdk/data-command/)'s `data`, a dictionary of the command's stored field values. It is `None` when there is no anchoring command:
    ```python
    custom_command = CustomCommand.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    data = custom_command.data
    ```
##  Attributes 
###  CustomCommand 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
plugin_command| [PluginCommand](/sdk/data-plugin-command/)  
data| JSON  

---

# DetectedIssue

Source: https://docs.canvasmedical.com/sdk/data-detected-issue/

##  Introduction 
The `DetectedIssue` model represents an actual or potential clinical issue with or between one or more active or proposed clinical actions for a patient.
##  Basic usage 
To get a detected issue by identifier, use the `get` method on the `DetectedIssue` model manager:
    ```python
    from canvas_sdk.v1.data.detected_issue import DetectedIssue
    detected_issue = DetectedIssue.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the detected issues for a patient can be accessed with the `detected_issues` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    detected_issues = patient.detected_issues.all()
    ```
##  Evidence 
The codings for the evidence of a detected issue can be accessed with the `evidence` attribute on a `DetectedIssue` object:
    ```python
    from canvas_sdk.v1.data.detected_issue import DetectedIssue
    from logger import log
    detected_issue = DetectedIssue.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in detected_issue.evidence.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
##  Filtering 
Detected issues can be filtered by any attribute that exists on the model.
Filtering for detected issues is done with the `filter` method on the `DetectedIssue` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.detected_issue import DetectedIssue
    detected_issues = DetectedIssue.objects.filter(status="active")
    ```
###  Committed detected issues 
The `committed` method returns detected issues that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.detected_issue import DetectedIssue
    committed_detected_issues = DetectedIssue.objects.committed()
    ```
##  Attributes 
###  DetectedIssue 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
identified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
code| String  
status| DetectedIssueStatus  
severity| DetectedIssueSeverity  
reference| String  
issue_identifier| String  
issue_identifier_system| String  
detail| String  
evidence| DetectedIssueEvidence[]  
assessed_coding_gap_events| [AssessCodingGapEvent](/sdk/data-coding-gap-event/#assesscodinggapevent)[]  
created_coding_gap_events| [CreateCodingGapEvent](/sdk/data-coding-gap-event/#createcodinggapevent)[]  
deferred_coding_gap_events| [DeferCodingGapEvent](/sdk/data-coding-gap-event/#defercodinggapevent)[]  
validated_coding_gap_events| [ValidateCodingGapEvent](/sdk/data-coding-gap-event/#validatecodinggapevent)[]  
###  DetectedIssueEvidence 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
detected_issue| [DetectedIssue](/sdk/data-detected-issue/#detectedissue)  
###  DetectedIssueStatus 
Available on the model as `DetectedIssue.Status`, so a comparison reads `detected_issue.status == DetectedIssue.Status.FINAL`.
Enum| Value| Label  
---|---|---  
REGISTERED| registered| Registered  
PRELIMINARY| preliminary| Preliminary  
CANCELLED| cancelled| Cancelled  
AMENDED| amended| Amended  
FINAL| final| Final  
CORRECTED| corrected| Corrected  
ENTERED_IN_ERROR| entered-in-error| Entered in Error  
###  DetectedIssueSeverity 
Available on the model as `DetectedIssue.Severity`. A detected issue that carries no severity holds an empty string rather than `None`.
Enum| Value| Label  
---|---|---  
HIGH| high| High  
MODERATE| moderate| Moderate  
LOW| low| Low  

---

# Device

Source: https://docs.canvasmedical.com/sdk/data-device/

##  Introduction 
The `Device` model represents a type of a manufactured item that is used in the provision of healthcare without being substantially changed through that activity. The device may be a medical or non-medical device.
##  Basic usage 
To get a device by identifier, use the `get` method on the `Device` model manager:
    ```python
    from canvas_sdk.v1.data.device import Device
    device = Device.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the devices for a patient can be accessed with the `devices` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    devices = patient.devices.all()
    ```
##  Filtering 
Devices can be filtered by any attribute that exists on the model.
Filtering for devices is done with the `filter` method on the `Device` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.device import Device
    devices = Device.objects.filter(manufacturer="ACME Biomedical", lot_number="M320")
    ```
###  Committed devices 
The `committed` method returns devices that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.device import Device
    committed_devices = Device.objects.committed()
    ```
##  Attributes 
###  Device 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note_id| Integer  
labeled_contains_NRL| Boolean  
assigning_authority| String  
scoping_entity| String  
udi| String  
di| String  
issuing_agency| String  
lot_number| String  
brand_name| String  
mri_safety_status| String  
version_model_number| String  
company_name| String  
gmdnPTName| String  
status| String  
expiration_date| Date  
expiration_date_original| String  
serial_number| String  
manufacturing_date_original| String  
manufacturing_date| Date  
manufacturer| String  
procedure_id| Integer  

---

# DiagnosticView

Source: https://docs.canvasmedical.com/sdk/data-diagnostic-view/

##  Introduction 
The `DiagnosticView` model represents a saved combination of lab tests and questionnaire codes configured on your instance. A diagnostic view has no patient of its own — it is a reusable definition. When a diagnostic view is embedded in a note with the [Reference](/sdk/commands/#reference) command, Canvas renders that patient's results for the view's codes as a timeseries.
Diagnostic views are configured by an administrator, so the set available to a plugin is whatever your instance has defined.
##  Basic usage 
To get a diagnostic view by identifier, use the `get` method on the `DiagnosticView` model manager:
    ```python
    from canvas_sdk.v1.data import DiagnosticView
    view = DiagnosticView.objects.get(id="dca3a3c5-0a8e-4f7b-9c6a-1b9bf3a6e5e0")
    ```
To list every diagnostic view on the instance:
    ```python
    from canvas_sdk.v1.data import DiagnosticView
    views = DiagnosticView.objects.all()
    ```
##  Filtering 
Diagnostic views can be filtered by any attribute that exists on the model.
###  By name 
Names are set by whoever configured the view, so match on the exact name you expect and handle the case where it is absent:
    ```python
    from canvas_sdk.v1.data import DiagnosticView
    a1c_view = DiagnosticView.objects.filter(name="Hemoglobin A1c").first()
    ```
###  By search tag 
`tags` is a single free-text string of search terms, not a list, so use a substring match:
    ```python
    from canvas_sdk.v1.data import DiagnosticView
    diabetes_views = DiagnosticView.objects.filter(tags__icontains="diabetes")
    ```
##  Embedding a view in a note 
Pass the view's `id` to the [Reference](/sdk/commands/#reference) command:
    ```python
    from canvas_sdk.commands import ReferenceCommand
    from canvas_sdk.v1.data import DiagnosticView
    def compute():
        a1c_view = DiagnosticView.objects.filter(name="Hemoglobin A1c").first()
        if not a1c_view:
            return []
        reference = ReferenceCommand(
            note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
            diagnostic_view_id=a1c_view.id,
        )
        return [reference.originate(commit=True)]
    ```
##  Attributes 
###  DiagnosticView 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
name| String (up to 100 characters)  
tags| String (up to 500 characters; free-text search terms)  
originator| [CanvasUser](/sdk/data-canvasuser)

---

# DME

Source: https://docs.canvasmedical.com/sdk/data-dme/

##  Introduction 
The DME data models let a plugin read the durable medical equipment (DME) that providers order with the [OrderDme](/sdk/commands/#orderdme) command:
  - `DmeProduct` is an item on your instance's DME formulary. Its `id` is the value `OrderDmeCommand` takes as `dme_product_id`, so a plugin can find a product by its code or name instead of hard-coding the ID.
  - `DmeOrder` is the record a signed Order DME command creates. It keeps the ordered item, indications, quantity, supplier, and ordering provider, along with the patient's height and weight when the order was signed.
Both models are read-only. Admins manage the formulary in the Django Admin UI under **DME Products**.
##  Basic usage 
###  Find a formulary product 
Filter `DmeProduct` by code, and include `active=True`, because the Order DME command only accepts active products:
    ```python
    from canvas_sdk.v1.data import DmeProduct
    wheelchair = DmeProduct.objects.filter(code="K0001", active=True).first()
    ```
A product can have no code, and two products can share one, so check that the lookup found a product before you use it. To match on the product name instead, use `name__icontains`.
###  Order a formulary product 
Pass the product's `id` as `dme_product_id`:
    ```python
    from canvas_sdk.commands import OrderDmeCommand
    from canvas_sdk.v1.data import DmeProduct
    wheelchair = DmeProduct.objects.filter(code="K0001", active=True).first()
    if wheelchair:
        order = OrderDmeCommand(
            note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
            dme_product_id=str(wheelchair.id),
            diagnosis_codes=["R262"],
            quantity=1,
            ordering_provider_key="b8a7c6d5-4e3f-4a2b-9c1d-0e8f7a6b5c4d",
        )
    ```
###  Read signed orders 
To get an order by identifier, use the `get` method on the `DmeOrder` model manager:
    ```python
    from canvas_sdk.v1.data import DmeOrder
    order = DmeOrder.objects.get(id="3c9e2f4a-6b1d-4e8a-9f7c-5d2b0a1e8c63")
    ```
If you have a patient object, the patient's orders are available from the `dme_orders` attribute:
    ```python
    from canvas_sdk.v1.data import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    orders = patient.dme_orders.all()
    ```
A `DmeOrder` is the [anchor object](/sdk/data-command/#the-anchor-object) of its `orderDme` command, so you can also reach it from the command:
    ```python
    from canvas_sdk.v1.data import Command
    command = Command.objects.get(id="c1b5a4d2-7e3f-4a8b-9c6d-2f1e0a9b8c7d")
    order = command.anchor_object
    ```
An order linked to an [assessment](/sdk/data-assessment/#commands-linked-to-an-assessment) in the same note keeps that assessment on its `assessment` field. Read the orders linked to an assessment from the assessment's side with `linked_dme_orders`:
    ```python
    from canvas_sdk.v1.data import Assessment
    assessment = Assessment.objects.get(id="9a4c2e7b-1f3d-4b6a-8e5c-0d2f7a9b1c34")
    linked_orders = assessment.linked_dme_orders.all()
    ```
##  Filtering 
DME products and orders can be filtered by any attribute that exists on the model.
###  Products by code system 
`code_system` is a `DmeProductCodeSystem` value: `HCPCS` for Healthcare Common Procedure Coding System (HCPCS) codes, or `INTERNAL` for codes your organization assigns:
    ```python
    from canvas_sdk.v1.data import DmeProduct, DmeProductCodeSystem
    hcpcs_products = DmeProduct.objects.filter(code_system=DmeProductCodeSystem.HCPCS, active=True)
    ```
###  Committed orders 
The `committed` method returns orders that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import DmeOrder
    committed_orders = DmeOrder.objects.committed()
    ```
##  What a signed order records 
Canvas copies the item into the order when the command is signed, so later formulary changes don't change an existing order:
  - For a formulary product, `product` links to the `DmeProduct`, and `item_name`, `item_code`, and `item_code_system` hold the product's values at signing.
  - For an off-formulary item, `product` is `None`, `item_name` holds the `free_text_item` text, and `item_code` and `item_code_system` are empty strings.
`indications` is a list of the diagnoses the order was placed for, each a dictionary with `code` and `display` keys.
`patient_height` and `patient_weight` hold the patient's latest committed height and weight as display text with units, such as `"70 in"` and `"10 lbs, 8 oz"`. Each is an empty string when the patient had no reading at signing.
##  Attributes 
###  DmeProduct 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
name| String  
code| String  
code_system| DmeProductCodeSystem  
active| Boolean  
orders| DmeOrder[]  
###  DmeOrder 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
deleted| Boolean  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
product| DmeProduct  
item_name| String  
item_code| String  
item_code_system| String  
indications| JSON  
quantity| Integer  
length_of_need| String  
supplier| [ServiceProvider](/sdk/data-serviceprovider/)  
ordering_provider| [Staff](/sdk/data-staff/#staff)  
patient_height| String  
patient_weight| String  
###  DmeProductCodeSystem 
Value| Label  
---|---  
HCPCS| HCPCS  
INTERNAL| Internal  

---

# DocumentReference

Source: https://docs.canvasmedical.com/sdk/data-document-reference/

The `DocumentReference` model represents references to documents stored in Canvas, such as uploaded PDFs, scanned files, and other clinical documents. Each document reference can link to a file stored in S3 and provides secure access via presigned URLs.
##  Basic Usage 
    ```python
    from canvas_sdk.v1.data import DocumentReference
    # Get a specific document reference
    doc_ref = DocumentReference.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    # Get all document references
    all_docs = DocumentReference.objects.all()
    ```
##  Filtering 
###  By patient 
    ```python
    from canvas_sdk.v1.data import DocumentReference
    patient_docs = DocumentReference.objects.for_patient("b80b1cdc2e6a4aca90ccebc02e683f35")
    ```
###  By status 
    ```python
    from canvas_sdk.v1.data import DocumentReference, DocumentReferenceStatus
    current_docs = DocumentReference.objects.filter(status=DocumentReferenceStatus.CURRENT)
    ```
###  By category or type 
    ```python
    from canvas_sdk.v1.data import DocumentReference
    docs = DocumentReference.objects.filter(category__code="clinical-note")
    ```
##  Accessing Document Files 
The `document_url` property returns a presigned S3 URL for securely accessing the document file. If no S3 file is present, it falls back to the `document_absolute_url` field.
    ```python
    from canvas_sdk.v1.data import DocumentReference
    doc_ref = DocumentReference.objects.exclude(document="").first()
    # Returns a presigned S3 URL (valid for 1 hour)
    url = doc_ref.document_url
    ```
##  Attributes 
###  DocumentReference 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
document| String|   
document_absolute_url| String|   
document_content_type| String|   
business_identifier| String|   
originator| [CanvasUser](/sdk/data-canvasuser)|   
subject| [CanvasUser](/sdk/data-canvasuser)|   
type| DocumentReferenceCoding|   
category| DocumentReferenceCategory|   
status| DocumentReferenceStatus|   
date| Date|   
encounter| [Encounter](/sdk/data-encounter)|   
team| [Team](/sdk/data-team/#team)|   
related_object_document_title| String|   
related_object_document_comment| String|   
content_type| [ContentType](/sdk/data-content-type/) (the related object's type)|   
object_id| Integer (the related object's `dbid`)|   
related_object| Model (computed)| The SDK object the document is attached to, or `None`  
document_url| String (computed)| Presigned S3 URL or absolute URL  
###  DocumentReferenceCoding 
A coding entry representing the type of a document reference.
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
###  DocumentReferenceCategory 
A coding entry representing the category of a document reference.
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
###  DocumentReferenceStatus 
An enum representing the status of a document reference.
Member| Value| Description  
---|---|---  
`CURRENT`| `current`| Current  
`SUPERSEDED`| `superseded`| Superseded  
`ENTERED_IN_ERROR`| `entered-in-error`| Entered in Error  
##  The related object 
Most document references point back at the record they were generated from — a lab report, a letter, a locked-note PDF, a patient statement, and so on. `content_type` and `object_id` form that generic link: `content_type` identifies the linked model by its stable `app_label` and lowercased `model` name, and `object_id` is that record's `dbid`.
The `related_object` property resolves the link for you, returning the corresponding SDK data model instance:
    ```python
    from canvas_sdk.v1.data import DocumentReference
    doc_ref = DocumentReference.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    # The SDK object this document is attached to (a LabReport, Letter, ImagingReport, ...), or None.
    source = doc_ref.related_object
    ```
`related_object` returns `None` when the document has no related object (`content_type` or `object_id` is unset) or when the linked content type has no SDK data model equivalent. The content types it resolves today:
`app_label` / `model`| SDK data model  
---|---  
`api` / `labreport`| [LabReport](/sdk/data-labs/#labreport)  
`api` / `imagingreport`| [ImagingReport](/sdk/data-imaging/#imagingreport)  
`api` / `letter`| [Letter](/sdk/data-letter/#letter)  
`api` / `notestatechangeevent`| [NoteStateChangeEvent](/sdk/data-note/#notestatechangeevent)  
`api` / `uncategorizedclinicaldocument`| [UncategorizedClinicalDocument](/sdk/data-uncategorized-clinical-document/#uncategorizedclinicaldocument)  
`api` / `referralreport`| [ReferralReport](/sdk/data-referral/#referralreport)  
`api` / `educationalmaterial`| [EducationalMaterial](/sdk/data-educational-material/#educationalmaterial)  
`api` / `patientadministrativedocument`| [PatientAdministrativeDocument](/sdk/data-patient-administrative-document/#patientadministrativedocument)  
`quality_and_revenue` / `invoicefull`| [Invoice](/sdk/data-invoice/#invoice)  
To go the other way — find every document reference for a given source type — resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` (never hardcode the per-environment `dbid`) and filter on it:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference
    content_type = ContentType.objects.filter(
        app_label="api", model="patientadministrativedocument"
    ).first()
    references = DocumentReference.objects.filter(content_type=content_type)
    ```

---

# Document Review Delegation

Source: https://docs.canvasmedical.com/sdk/data-document-review-delegation/

##  Introduction 
The `DocumentReviewDelegation` model records a hand-off of a document review from one staff member to another staff member or team. When a reviewer delegates an uncategorized clinical document, Canvas stores who delegated it, who received it, the original owner, whether the recipient may apply the owner's signature, and any instructions.
Delegations are an append-only log: a document has at most one **active** delegation at a time (`is_active`). Delegation is A↔B only — an owner delegates a document out, and the recipient may only route it back — so `on_behalf_of` always identifies the original owner and, when `signature_consent` is set, the staff member whose signature the recipient may apply while annotating the document.
##  Basic usage 
To get a delegation by identifier, use the `get` method on the `DocumentReviewDelegation` model manager:
    ```python
    from canvas_sdk.v1.data import DocumentReviewDelegation
    delegation = DocumentReviewDelegation.objects.get(id="b5a0c1d2-e3f4-5678-9abc-def012345678")
    ```
If you have an [UncategorizedClinicalDocument](/sdk/data-uncategorized-clinical-document/), its delegations are available through the `delegations` and `active_delegation` accessors:
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocument
    document = UncategorizedClinicalDocument.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    # The full delegation history, oldest first.
    history = document.delegations
    # The current active delegation, or None when the document is with its owner.
    current = document.active_delegation
    if current and current.signature_consent:
        signer = current.on_behalf_of  # whose signature the recipient may apply
    ```
##  Filtering 
Delegations can be filtered by any attribute that exists on the model.
###  Active delegations 
    ```python
    from canvas_sdk.v1.data import DocumentReviewDelegation
    active = DocumentReviewDelegation.objects.filter(is_active=True)
    ```
###  Delegations that granted signature consent 
    ```python
    from canvas_sdk.v1.data import DocumentReviewDelegation
    with_consent = DocumentReviewDelegation.objects.filter(is_active=True, signature_consent=True)
    ```
##  Route-back 
Use the `is_route_back` property to tell whether an active delegation returned the document to its owner (as opposed to delegating it away):
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocument
    document = UncategorizedClinicalDocument.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    delegation = document.active_delegation
    if delegation and delegation.is_route_back:
        ...  # the document is back with its owner
    ```
##  Attributes 
###  DocumentReviewDelegation 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
content_type| [ContentType](/sdk/data-content-type/) (the delegated document's type)  
object_id| Integer (the delegated document's `dbid`)  
delegated_by| [Staff](/sdk/data-staff/#staff) (who handed the document off)  
delegated_to_staff| [Staff](/sdk/data-staff/#staff) (recipient, if delegated to a person)  
delegated_to_team| [Team](/sdk/data-team/#team) (recipient, if delegated to a team)  
on_behalf_of| [Staff](/sdk/data-staff/#staff) (the original owner)  
signature_consent| Boolean (may the recipient apply the owner's signature)  
comment| String (instructions for the recipient)  
is_active| Boolean (the current delegation for the document)  
##  The delegated document 
`content_type` and `object_id` form a generic link to the document whose review was delegated: `content_type` identifies the linked model, and `object_id` is that record's `dbid`. Review delegation is currently supported only for [UncategorizedClinicalDocument](/sdk/data-uncategorized-clinical-document/) records, so `content_type` always resolves to that model and `object_id` is the document's `dbid`. The generic relation leaves room for additional document types in the future.
The most direct way to work with a document's delegations is from the document itself, through its `delegations` and `active_delegation` accessors:
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocument
    document = UncategorizedClinicalDocument.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    current = document.active_delegation   # the active DocumentReviewDelegation, or None
    history = document.delegations         # every delegation hop recorded for the document
    ```
To go the other way — from a delegation to the document it points at — read `content_type` to learn which model `object_id` refers to, then resolve it. A [ContentType](/sdk/data-content-type/) is identified by its stable `app_label` and `model` (the lowercased model name), so branch on those rather than on the per-environment `dbid`. This keeps working if more document types become delegatable later:
    ```python
    from canvas_sdk.v1.data import DocumentReviewDelegation, UncategorizedClinicalDocument
    delegation = DocumentReviewDelegation.objects.get(id="b3e6f74c-2a1b-4c8d-9f2e-31842ae7d3b9")
    content_type = delegation.content_type
    # Today content_type is always api / uncategorizedclinicaldocument; object_id is its dbid.
    if content_type.app_label == "api" and content_type.model == "uncategorizedclinicaldocument":
        document = UncategorizedClinicalDocument.objects.get(dbid=delegation.object_id)
    ```
You can also use `content_type` to find every delegation for a given document type. Resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` — never hardcode the `dbid`, which differs per environment:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReviewDelegation
    document_ct = ContentType.objects.filter(app_label="api", model="uncategorizedclinicaldocument").first()
    delegations = DocumentReviewDelegation.objects.filter(content_type=document_ct)
    ```
Exactly one of `delegated_to_staff` / `delegated_to_team` is set on a delegation.

---

# EducationalMaterial

Source: https://docs.canvasmedical.com/sdk/data-educational-material/

##  Introduction 
The `EducationalMaterial` model represents patient educational material recorded on a note through the Educational Material command — the selected article, its title and abstract, and the languages it is available in.
Records are returned regardless of command state, so staged commands are included; use `committed()` to limit results to committed commands.
##  Basic Usage 
`EducationalMaterial` records can be retrieved by their UUID `id`, their integer `dbid`, or through a patient.
    ```python
    from canvas_sdk.v1.data import EducationalMaterial
    # Get all educational material records
    materials = EducationalMaterial.objects.all()
    # Get a specific record by its UUID id
    material = EducationalMaterial.objects.get(id="c9a7b1e2-d4f3-4e6a-8b5c-0d1e2f3a4b5c")
    ```
If you have a `Patient` object, its educational material records can be accessed with the `education_material` reverse relation:
    ```python
    from canvas_sdk.v1.data import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    materials = patient.education_material.all()
    ```
##  Filtering 
###  By attribute 
    ```python
    from canvas_sdk.v1.data import EducationalMaterial
    materials = EducationalMaterial.objects.filter(selected_language="en-us")
    ```
###  Committed records 
The `committed` method returns records that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import EducationalMaterial
    committed = EducationalMaterial.objects.committed()
    ```
##  Accessing the article PDF 
`EducationalMaterial` holds the article's metadata — its title, abstract, and languages — not the article file itself. When the command is committed, Canvas renders the article to a PDF and attaches it to a [DocumentReference](/sdk/data-document-reference/) with the LOINC type `34895-3` (Education note).
To read a patient's education note PDFs, filter `DocumentReference` by that type and use its `document_url`:
    ```python
    from canvas_sdk.v1.data import DocumentReference
    education_notes = DocumentReference.objects.for_patient(
        "1eed3ea2a8d546a1b681a2a45de1d790"
    ).filter(type__code="34895-3")
    for note in education_notes:
        url = note.document_url
    ```
To resolve the PDF for one specific record, filter on the document's [related object](/sdk/data-document-reference/#the-related-object) instead. Resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` — never hardcode the per-environment `dbid` — and match `object_id` against the material's `dbid`:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference, EducationalMaterial
    material = EducationalMaterial.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    content_type = ContentType.objects.filter(
        app_label="api", model="educationalmaterial"
    ).first()
    document = DocumentReference.objects.filter(
        content_type=content_type, object_id=material.dbid
    ).first()
    url = document.document_url if document else None
    ```
> **Info:** `object_id` holds the related record's integer `dbid`, not its UUID `id`, so filter on `material.dbid`.
##  Attributes 
###  EducationalMaterial 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
article_id| String  
selected_language| EducationalMaterialLanguage  
title| String  
languages| String[]  
abstract| String  
`selected_language` defaults to `en-us`.
`languages` holds the locale codes the article is available in, drawn from the same set of codes as EducationalMaterialLanguage. It is stored as a plain array of strings rather than an enum, so compare against the code values (`"es-us"`) rather than expecting enum members.
##  Enumeration types 
###  EducationalMaterialLanguage 
Value| Label  
---|---  
en-us| English  
es-us| Spanish  
en-ca| English CA  
fr-ca| French CA  
fr-fr| French FR  
da-dk| Danish DK  
ar-eg| Arabic Egypt  
ar-us| Arabic  
bn-us| Bengali  
bs-ba| Bosnian  
bs-us| Bosnian  
fa-ir| Farsi Iran  
fa-us| Farsi  
hr-hr| Croatian  
ht-us| Haitian  
ko-us| Korean  
ru-ru| Russian  
ru-us| Russian  
sr-us| Serbian  
so-so| Somalia  
so-us| Somalia  
tl-us| Tagalog  
vi-vn| Vietnamese  
vi-us| Vietnamese  
zh-cn| Chinese  
zh-us| Chinese

---

# EligibilityResponse

Source: https://docs.canvasmedical.com/sdk/data-eligibility-response/

##  Introduction 
The `EligibilityResponse` model represents a coverage eligibility (271) response returned by a payer for a patient's `Coverage`, along with the originating `EligibilityRequest` (270). An `EligibilityResponse` also derives a check `status` (Active, Inactive, or Failed) from the payer's response.
##  Basic usage 
To get an eligibility response by identifier, use the `get` method on the `EligibilityResponse` model manager:
    ```python
    from canvas_sdk.v1.data.eligibility_response import EligibilityResponse
    response = EligibilityResponse.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
Eligibility requests and responses are linked to a `Coverage`. From a coverage object, use the `requests` and `eligibility_responses` attributes:
    ```python
    from canvas_sdk.v1.data.coverage import Coverage
    coverage = Coverage.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    requests = coverage.requests.all()
    responses = coverage.eligibility_responses.all()
    ```
##  Eligibility status 
`EligibilityResponse.status` returns an `EligibilityResponseStatus` derived from the payer's response — `FAILED` when the check errored, `INACTIVE` when the payer reports an inactive benefit section, otherwise `ACTIVE`:
    ```python
    from canvas_sdk.v1.data.coverage import Coverage
    from canvas_sdk.v1.data.eligibility_response import EligibilityResponseStatus
    coverage = Coverage.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    response = coverage.eligibility_responses.order_by("created").last()
    is_active = response is not None and response.status == EligibilityResponseStatus.ACTIVE
    ```
A coverage with no eligibility responses (an empty `coverage.eligibility_responses` queryset) has not been verified.
`NOT_APPLICABLE`, like `UNKNOWN`, is a value returned by [`Coverage.eligibility_status`](/sdk/data-coverage/#eligibility-status), never by an individual `EligibilityResponse.status`. A single response only ever resolves to `FAILED`, `INACTIVE`, or `ACTIVE`.
##  Attributes 
###  EligibilityRequest 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
coverage| [Coverage](/sdk/data-coverage)  
trading_partner_id| String  
member| JSON  
provider| JSON  
payload| String  
control_number| String  
###  EligibilityResponse 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
eligibility_request| EligibilityRequest  
coverage| [Coverage](/sdk/data-coverage)  
client_id| String  
correlation_id| String  
deductible| JSON  
out_of_pocket| JSON  
coverage_info| JSON  
payer| JSON  
provider| JSON  
service_type_codes| List[String]  
service_types| List[String]  
subscriber| JSON  
trading_partner_id| String  
valid_request| Boolean  
errors| List[String]  
eligid| String  
x12_response| String  
parsed_x12_response| JSON  
status| EligibilityResponseStatus (computed)  
eligibility_or_benefit_information| List (computed)  
`status` and `eligibility_or_benefit_information` are computed from `errors` and `parsed_x12_response` rather than stored, so neither can be used in `filter()`. To select responses by outcome, filter on the columns they derive from — a failed check is one with a non-empty `errors`:
    ```python
    from canvas_sdk.v1.data.eligibility_response import EligibilityResponse
    failed = EligibilityResponse.objects.exclude(errors=None).exclude(errors=[])
    ```
##  Enumeration types 
###  EligibilityResponseStatus 
Name| Value  
---|---  
ACTIVE| Active  
INACTIVE| Inactive  
FAILED| Failed  
UNKNOWN| Unknown  
NOT_APPLICABLE| NotApplicable  

---

# Encounter

Source: https://docs.canvasmedical.com/sdk/data-encounter/

##  Introduction 
The `Encounter` model represents a patient encounter connected to a Note in Canvas.
##  Basic usage 
To get an encounter by identifier, use the `get` method on the `Encounter` model manager:
    ```python
    from canvas_sdk.v1.data import Encounter
    encounter = Encounter.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
To get an encounter from a note, use the `encounter` attribute on the `Note` object:
    ```python
    from canvas_sdk.v1.data import Note
    note = Note.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    encounter = note.encounter
    ```
Keep in mind that not all notes have an associated encounter, so sometimes `note.encounter` will be `None`.
Similary, you can get a note from an `Encounter` object by using the `note` attribute:
    ```python
    from canvas_sdk.v1.data import Encounter
    encounter = Encounter.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    note = encounter.note
    ```
All encounters will have an associated note, which means `encounter.note` will never be `None`.
##  Filtering 
Encounters can be filtered by any attribute that exists on the model.
Filtering for encounters is done with the `filter` method on the `Encounter` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.encounter import Encounter, EncounterState
    encounters = Encounter.objects.filter(state=EncounterState.CONCLUDED)
    ```
##  Attributes 
###  Encounter 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
note| [Note](/sdk/data-note/)  
state| EncounterState  
medium| EncounterMedium  
start_time| DateTime  
end_time| DateTime  
document_references| QuerySet[[DocumentReference](/sdk/data-document-reference/#documentreference)]  
##  Enumeration types 
###  EncounterState 
Name| Value  
---|---  
STARTED| STA  
PLANNED| PLA  
CONCLUDED| CON  
CANCELLED| CAN  
###  EncounterMedium 
Name| Value  
---|---  
VOICE| voice  
VIDEO| video  
OFFICE| office  
HOME| home  
OFFSITE| offsite  
LAB| lab  

---

# Common Enumeration Type

Source: https://docs.canvasmedical.com/sdk/data-enumeration-types/

##  Introduction 
This page shows common enumeration types that are used in multiple models.
##  Enumeration types 
###  AddressState 
Value| Label  
---|---  
active| Active  
deleted| Deleted  
###  AddressType 
Value| Label  
---|---  
postal| Postal  
physical| Physical  
both| Both  
###  AddressUse 
Value| Label  
---|---  
home| Home  
work| Work  
temp| Temp  
old| Old  
###  AddressUseWithBilling 
Value| Label  
---|---  
home| Home  
work| Work  
temp| Temp  
old| Old  
billing| Billing  
###  ColorEnum 
Value| Label  
---|---  
red| Red  
orange| Orange  
yellow| Yellow  
olive| Olive  
green| Green  
teal| Teal  
blue| Blue  
violet| Violet  
purple| Purple  
pink| Pink  
brown| Brown  
grey| Grey  
black| Black  
###  ContactPointState 
Value| Label  
---|---  
active| Active  
deleted| Deleted  
###  ContactPointSystem 
Value| Label  
---|---  
phone| phone  
fax| fax  
email| email  
pager| pager  
other| other  
###  ContactPointUse 
Value| Label  
---|---  
home| Home  
work| Work  
temp| Temp  
old| Old  
other| Other  
mobile| Mobile  
automation| Automation  
###  DocumentReviewMode 
Value| Label  
---|---  
RR| Review required  
AR| Already reviewed offline  
RN| Review not required  
###  OrderStatus 
Value| Description  
---|---  
proposed| Proposed  
draft| Draft  
planned| Planned  
requested| Requested  
received| Received  
accepted| Accepted  
in-progress| In-progress  
review| Review  
completed| Completed  
cancelled| Cancelled  
suspended| Suspended  
rejected| Rejected  
failed| Failed  
EIE| Entered in Error  
###  Origin 
Value| Label  
---|---  
REF_CMD| Referral command  
CMP_IMG_ORD| Completing image orders  
IMG_REP_REV| Imaging report review  
LAB_RES_REV| Lab results review  
CON_REP_REV| Consult report review  
UNC_DOC_REP_REV| Uncategorized document report review  
ASN_NOT_PHN_REV| Assigned note/phone call for review  
POP_HLT_OUT| Population health outreach  
CMP_LAB_ORD| Completing lab orders  
CHT_PDF| Chart PDF  
EXP_CLM_SNO| Expired claim snoozed  
FLG_PST_REV| Flagged posting review  
BAT_PTN_STA| Batch patient statements  
INC_COV| Incomplete Coverage  
###  PersonSex 
Value| Label  
---|---  
F| female  
M| male  
O| other  
UNK| unknown  
###  ReviewPatientCommunicationMethod 
Value| Description  
---|---  
DM| delegate call, can leave message  
DA| delegate call, need patient to answer  
DL| delegate letter  
DC| do not communicate  
AM| already left message  
AR| already reviewed with patient  
###  ReviewStatus 
Value| Label  
---|---  
reviewing| reviewing  
reviewed| reviewed  
###  TaxIDType 
Value| Label  
---|---  
E| EIN text  
S| SSN

---

# ExternalEvent

Source: https://docs.canvasmedical.com/sdk/data-external-event/

##  Introduction 
The `ExternalEvent` and `ExternalVisit` models represent clinical events from external data sources such as ADT (Admission, Discharge, Transfer) feeds. These models enable tracking of patient encounters that occur outside of Canvas, such as hospital admissions, emergency room visits, or transfers between facilities.
An `ExternalVisit` groups related events for a single patient visit, while `ExternalEvent` represents individual events within that visit (e.g., admission, discharge, transfer).
##  Basic usage 
To get an external event by identifier, use the `get` method on the `ExternalEvent` model manager:
    ```python
    from canvas_sdk.v1.data.external_event import ExternalEvent
    event = ExternalEvent.objects.get(id="b4f8c3a1-2d5e-4f6a-8b9c-1a2b3c4d5e6f")
    ```
To get an external visit:
    ```python
    from canvas_sdk.v1.data.external_event import ExternalVisit
    visit = ExternalVisit.objects.get(id="a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d")
    ```
###  Accessing related models 
If you have an external event, you can access the associated visit and patient:
    ```python
    from canvas_sdk.v1.data.external_event import ExternalEvent
    event = ExternalEvent.objects.get(id="b4f8c3a1-2d5e-4f6a-8b9c-1a2b3c4d5e6f")
    # Access the parent visit
    visit = event.external_visit
    # Access the patient
    patient = event.patient
    ```
If you have an external visit, you can access all events within that visit:
    ```python
    from canvas_sdk.v1.data.external_event import ExternalVisit
    visit = ExternalVisit.objects.get(id="a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d")
    # Get all events in this visit
    events = visit.visit_events.all()
    ```
If you have a patient object, you can access their external events and visits:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    # Get all external events for this patient
    events = patient.patient_events.all()
    # Get all external visits for this patient
    visits = patient.patient_visits.all()
    ```
##  Filtering 
External events and visits can be filtered by any attribute that exists on the model.
###  By patient 
    ```python
    from canvas_sdk.v1.data.external_event import ExternalEvent, ExternalVisit
    # Get all events for a specific patient
    events = ExternalEvent.objects.filter(patient__id="1eed3ea2a8d546a1b681a2a45de1d790")
    # Get all visits for a specific patient
    visits = ExternalVisit.objects.filter(patient__id="1eed3ea2a8d546a1b681a2a45de1d790")
    ```
###  By event type 
    ```python
    from canvas_sdk.v1.data.external_event import ExternalEvent
    # Get all admission events
    admissions = ExternalEvent.objects.filter(event_type="ADT^A01")
    # Get all discharge events
    discharges = ExternalEvent.objects.filter(event_type="ADT^A03")
    ```
###  By cancelled status 
    ```python
    from canvas_sdk.v1.data.external_event import ExternalEvent
    # Get all non-cancelled events
    active_events = ExternalEvent.objects.filter(event_cancelation_datetime__isnull=True)
    # Get all cancelled events
    cancelled_events = ExternalEvent.objects.filter(event_cancelation_datetime__isnull=False)
    ```
###  By visit identifier 
    ```python
    from canvas_sdk.v1.data.external_event import ExternalVisit
    visit = ExternalVisit.objects.get(visit_identifier="VISIT-12345")
    ```
###  By facility 
    ```python
    from canvas_sdk.v1.data.external_event import ExternalVisit
    visits = ExternalVisit.objects.filter(facility_name="General Hospital")
    ```
##  Attributes 
###  ExternalEvent 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
external_visit| ExternalVisit|   
patient| [Patient](/sdk/data-patient/#patient)|   
message_control_id| String|   
message_datetime| DateTime|   
event_type| String|   
event_datetime| DateTime|   
event_cancelation_datetime| DateTime|   
raw_message| String|   
cancelled| Boolean (computed)| `True` when the event has an `event_cancelation_datetime`  
###  ExternalVisit 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
visit_identifier| String  
information_source| String  
facility_name| String  
visit_events| QuerySet[ExternalEvent]  
##  Common Event Types 
External events typically use HL7 ADT event types:
Event Type| Description  
---|---  
ADT^A01| Admit/Visit Notification  
ADT^A02| Transfer a Patient  
ADT^A03| Discharge/End Visit  
ADT^A04| Register a Patient  
ADT^A08| Update Patient Information  
ADT^A11| Cancel Admit/Visit Notification  
ADT^A12| Cancel Transfer  
ADT^A13| Cancel Discharge/End Visit  
    ```python
    from canvas_sdk.v1.data.external_event import ExternalEvent
    from logger import log
    # Get recent events for a patient and log their types
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    events = ExternalEvent.objects.filter(patient__id=patient_id).order_by("-event_datetime")[:10]
    for event in events:
        status = "CANCELLED" if event.cancelled else "ACTIVE"
        log.info(f"Event: {event.event_type} at {event.event_datetime} [{status}]")
    ```

---

# Facility

Source: https://docs.canvasmedical.com/sdk/data-facility/

##  Introduction 
The `Facility` object represents a healthcare facility associated with patients within Canvas. Facilities can include hospitals, clinics, or other healthcare institutions where patients receive care. This object contains essential information about the facility, such as its address, contact details, and operational status.
##  Basic Usage 
To get a facility by identifier, use the `get` method on the `Facility` model manager:
    ```python
    from canvas_sdk.v1.data.facility import Facility
    facility = Facility.objects.get(id="34b50dfa-1b3e-4dc2-a11d-41b3115c29f3")
    ```
##  Filtering 
Facilities can be filtered by any attribute that exists on the model.
Filtering for facilities is done with the `filter` method on the `Facility` model manager.
##  Attributes 
Specify attributes with `filter` to filter by those attributes:
    ```python
    from canvas_sdk.v1.data.facility import Facility
    facilities = Facility.objects.filter(name="General Hospital", city="Metropolis")
    ```
###  Facility 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
line1| String  
line2| String  
city| String  
district| String  
state_code| String  
postal_code| String  
name| String  
npi_number| String  
phone_number| String  
fax_number| String  
active| Boolean  
patient_facilities| QuerySet[[PatientFacilityAddress](/sdk/data-patient/#patientfacilityaddress)]

---

# FamilyHistory

Source: https://docs.canvasmedical.com/sdk/data-family-history/

##  Introduction 
The `FamilyHistory` model represents a patient's family medical history — the condition(s) recorded for one of the patient's relatives, captured by the `family_history` command. The relative is identified by a SNOMED code and term, and the condition(s) are stored as `FamilyHistoryCoding` records reachable through the `coding` accessor.
##  Basic usage 
To get a family history record by identifier, use the `get` method on the `FamilyHistory` model manager:
    ```python
    from canvas_sdk.v1.data.family_history import FamilyHistory
    family_history = FamilyHistory.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, a patient's family history can be accessed with the `family_histories` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    family_histories = patient.family_histories.all()
    ```
If you have a patient ID, you can get the family history for the patient with the `for_patient` method on the `FamilyHistory` model manager:
    ```python
    from canvas_sdk.v1.data.family_history import FamilyHistory
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    family_histories = FamilyHistory.objects.for_patient(patient_id)
    ```
##  Codings 
The relative's condition coding records can be accessed with the `coding` attribute on a `FamilyHistory` object. `FamilyHistory` exposes this relation as the singular `coding`, unlike the plural `codings` on Condition, Procedure, and Immunization:
    ```python
    from canvas_sdk.v1.data.family_history import FamilyHistory
    from logger import log
    family_history = FamilyHistory.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in family_history.coding.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
##  Filtering 
Family history records can be filtered by any attribute that exists on the model.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.family_history import FamilyHistory
    family_histories = FamilyHistory.objects.filter(relation_snomed_term="Mother")
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The `find` method on the model manager is used to perform `ValueSet` filtering, matching against the relative's condition coding records — the `coding` accessor — not the `relation_snomed_code`/`relation_snomed_term` fields:
    ```python
    from canvas_sdk.v1.data.family_history import FamilyHistory
    from canvas_sdk.value_set.v2022.condition import Diabetes
    family_histories = FamilyHistory.objects.find(Diabetes)
    ```
###  By coding 
To filter on coding records directly instead of a value set, filter across the relation to match the relative's condition coding records:
    ```python
    from canvas_sdk.v1.data.family_history import FamilyHistory
    family_histories = FamilyHistory.objects.filter(
        coding__code__in=["44054006", "46635009"],
    ).distinct()
    ```
##  Attributes 
###  FamilyHistory 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
deleted| Boolean  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
relation_snomed_code| Integer  
relation_snomed_term| String  
narrative| String  
coding| FamilyHistoryCoding[]  
###  FamilyHistoryCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
family_history| FamilyHistory  

---

# Fax

Source: https://docs.canvasmedical.com/sdk/data-fax/

##  Introduction 
Canvas creates a `Fax` record for every fax it sends or receives. `direction` tells the two apart.
  - **Sent faxes:** when a user faxes a note, referral, imaging order, lab order, letter, or integration task, Canvas also records an action event on that document. Plugins can read them to see whether a fax was delivered, who sent it, and which number it went to.
  - **Received faxes:** each one has a `Fax` record with the sender's number, the page count, and whether it was received successfully.
Each document type has its own action event model:
Document| Action event| Reverse accessor on the document  
---|---|---  
[Note](/sdk/data-note/)| NoteActionEvent| `action_events`  
[Referral](/sdk/data-referral/#referral)| ReferralActionEvent| `action_events`  
[ImagingOrder](/sdk/data-imaging/#imagingorder)| ImagingOrderActionEvent| `action_events`  
[LabOrder](/sdk/data-labs/#laborder)| LabOrderActionEvent| `action_events`  
[IntegrationTask](/sdk/data-integration-task/#integrationtask)| IntegrationTaskActionEvent| `action_events`  
[Letter](/sdk/data-letter/)| [LetterActionEvent](/sdk/data-letter-action-event/)| `letter_action_events`  
All six have the same action event fields and differ only in the document they point to.
##  Delivery status 
Canvas submits a fax to the faxing service, and the service later reports whether it reached the recipient. `delivered_by_fax` on the action event holds that outcome:
`delivered_by_fax`| Meaning  
---|---  
`None`| Submitted. The faxing service hasn't reported the outcome yet.  
`True`| Delivered to the recipient.  
`False`| Not delivered. `fax_result_msg` holds the reason the faxing service reported.  
A submission the faxing service rejects doesn't create an action event. So `received_by_fax` is `True` on every action event for a fax sent today, and `success` is `True` on every outbound `Fax`. Neither one tells you whether the fax was delivered.
##  Basic usage 
###  Faxes of a document 
Use the document's `action_events` accessor:
    ```python
    from canvas_sdk.v1.data import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    faxes = note.action_events.filter(event_type="FAXED").select_related("fax")
    ```
###  Failed faxes, with the sender and the number 
`originator` is the [CanvasUser](/sdk/data-canvasuser/) who sent the fax, and `fax.to_fax_number` is the number it was sent to:
    ```python
    from canvas_sdk.v1.data import ReferralActionEvent
    failed = ReferralActionEvent.objects.filter(delivered_by_fax=False).select_related(
        "referral", "originator", "fax"
    )
    for event in failed:
        sender = event.originator
        failed_number = event.fax.to_fax_number if event.fax else None
    ```
###  Faxes sent by a plugin 
A fax sent with the [Fax Note effect](/sdk/effect-notes/#fax-note) is recorded as a `NoteActionEvent` on that note, with the Canvas Bot user as its `originator`. The [fax effects](/sdk/effect-fax/) for referrals, imaging orders, lab orders and letters record theirs the same way, on that document's action event model. Canvas Bot's staff id is `5eede137ecfe4124b8b773040e33be14` on every instance. To read the outcome, look the event up by the note, the number it was sent to, and that originator, so faxes staff sent to the same number are left out. Numbers are stored in E.164 format:
    ```python
    from canvas_sdk.v1.data import NoteActionEvent
    CANVAS_BOT_STAFF_ID = "5eede137ecfe4124b8b773040e33be14"
    latest = (
        NoteActionEvent.objects.filter(
            note__id="89992c23-c298-4118-864a-26cb3e1ae822",
            fax__to_fax_number="+15555550100",
            originator__staff__id=CANVAS_BOT_STAFF_ID,
        )
        .order_by("-created")
        .first()
    )
    ```
Every plugin's faxes are attributed to Canvas Bot, so this can't tell your plugin's faxes from another plugin's. If more than one plugin faxes the same note to the same number, compare `created` with when your plugin returned the effect.
###  Reacting when a fax fails 
Each faxed document type has [plugin events](/sdk/events/#faxed-documents) that target its action event. The `_CREATED` event fires when the fax is submitted, and the `_UPDATED` event fires when the faxing service reports the outcome:
Document| Fax submitted| Outcome reported| Target  
---|---|---|---  
Note| `NOTE_ACTION_EVENT_CREATED`| `NOTE_ACTION_EVENT_UPDATED`| NoteActionEvent  
Referral| `REFERRAL_ACTION_EVENT_CREATED`| `REFERRAL_ACTION_EVENT_UPDATED`| ReferralActionEvent  
Imaging order| `IMAGING_ORDER_ACTION_EVENT_CREATED`| `IMAGING_ORDER_ACTION_EVENT_UPDATED`| ImagingOrderActionEvent  
Lab order| `LAB_ORDER_ACTION_EVENT_CREATED`| `LAB_ORDER_ACTION_EVENT_UPDATED`| LabOrderActionEvent  
Data integration task| `INTEGRATION_TASK_ACTION_EVENT_CREATED`| `INTEGRATION_TASK_ACTION_EVENT_UPDATED`| IntegrationTaskActionEvent  
Letter| `LETTER_ACTION_EVENT_CREATED`| `LETTER_ACTION_EVENT_UPDATED`| [LetterActionEvent](/sdk/data-letter-action-event/)  
`LETTER_ACTION_EVENT_CREATED` also fires when a letter is printed. Check that the action event's `event_type` is `FAXED` before you treat it as a fax.
A later report that changes the outcome or its message fires `_UPDATED` again, so retry each action event at most once. This handler reacts to a failed note fax; the same pattern works for any row above with its own event and model:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data import NoteActionEvent
    class NoteFaxFailed(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_ACTION_EVENT_UPDATED)
        def compute(self):
            action_event = NoteActionEvent.objects.select_related("note", "fax").get(
                id=self.event.target.id
            )
            if action_event.delivered_by_fax is not False:
                return []
            failed_number = action_event.fax.to_fax_number if action_event.fax else None
            # Retry or alert, at most once per action event.
            return []
    ```
###  From a fax 
A `Fax` reaches its action events through `noteactionevents`, `referralactionevents`, `imagingorderactionevents`, `laborderactionevents`, `letteractionevents`, and `integrationtaskactionevents`:
    ```python
    from canvas_sdk.v1.data import Fax
    fax = Fax.objects.get(id="d2a6c1f4-7b3e-4c1a-9f5e-0a8b7c6d5e4f")
    note_events = fax.noteactionevents.all()
    ```
###  Faxes Canvas receives 
Filter on `direction` to read received faxes. `success` is `False` when the faxing service reported a problem receiving the fax, such as a call that dropped partway through. Canvas still creates an integration task with the pages that arrived, so the document may be incomplete.
    ```python
    from canvas_sdk.v1.data import Fax, FaxDirection
    received = Fax.objects.filter(direction=FaxDirection.INBOUND).order_by("-date_utc")
    failed = received.filter(success=False)
    ```
On a received fax, `to_fax_number` is the Canvas line that received it. Depending on the faxing service that delivered the fax, Canvas stores that number with or without the leading `+`, such as `+15555550100` or `15555550100`. To find every fax one line received, match both forms:
    ```python
    from canvas_sdk.v1.data import Fax, FaxDirection
    line = "15555550100"
    received_on_line = Fax.objects.filter(
        direction=FaxDirection.INBOUND,
        to_fax_number__in=[line, f"+{line}"],
    )
    ```
##  Attributes 
###  Fax 
Field Name| Type| Notes  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
fax_id| String| The faxing service's id for the fax  
to_fax_number| String| The number the fax was sent to, for example `+15555550100`. For a received fax, the Canvas number that received it, which can be stored without the `+`  
from_fax_number| String| The number the fax was sent from. For a received fax, the sender's number  
date_utc| DateTime| When the faxing service accepted a sent fax, or finished receiving a received fax  
fax_pages| Integer| The number of pages  
direction| FaxDirection| Whether Canvas sent or received the fax  
success| Boolean| For a sent fax, whether the faxing service accepted it. See Delivery status. For a received fax, whether it was received successfully  
noteactionevents| QuerySet[NoteActionEvent]| The note faxes sent as this fax  
referralactionevents| QuerySet[ReferralActionEvent]| The referral faxes sent as this fax  
imagingorderactionevents| QuerySet[ImagingOrderActionEvent]| The imaging order faxes sent as this fax  
laborderactionevents| QuerySet[LabOrderActionEvent]| The lab order faxes sent as this fax  
letteractionevents| QuerySet[[LetterActionEvent](/sdk/data-letter-action-event/)]| The letter faxes sent as this fax  
integrationtaskactionevents| QuerySet[IntegrationTaskActionEvent]| The integration task faxes sent as this fax  
fax_statuses| QuerySet[FaxStatusModel]| The status recorded when this fax was received  
###  FaxStatusModel 
Canvas records a status when it receives a fax: `Received`, or `Error` if the faxing service reported a problem receiving it. It's reachable through the fax's `fax_statuses` accessor and matches the fax's `success` value. Faxes sent from Canvas don't get one. Use `success` on the fax instead, which every received fax has.
Field Name| Type| Notes  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime| When the status was recorded  
modified| DateTime|   
fax| Fax| The fax the status belongs to  
status| FaxStatus|   
###  Action event fields 
These fields are on all six action event models.
Field Name| Type| Notes  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
event_type| EventType|   
send_fax_id| String| The faxing service's id for the fax  
received_by_fax| Boolean| Whether the faxing service accepted the fax  
delivered_by_fax| Boolean| The delivery outcome. See Delivery status.  
fax_result_msg| String| The reason the faxing service gave for a failed delivery  
originator| [CanvasUser](/sdk/data-canvasuser/)| The user who sent the fax  
fax| Fax| The fax record, including the number it was sent to  
###  NoteActionEvent 
The action event fields, plus:
Field Name| Type  
---|---  
note| [Note](/sdk/data-note/)  
###  ReferralActionEvent 
The action event fields, plus:
Field Name| Type  
---|---  
referral| [Referral](/sdk/data-referral/#referral)  
###  ImagingOrderActionEvent 
The action event fields, plus:
Field Name| Type  
---|---  
imaging_order| [ImagingOrder](/sdk/data-imaging/#imagingorder)  
###  LabOrderActionEvent 
The action event fields, plus:
Field Name| Type  
---|---  
lab_order| [LabOrder](/sdk/data-labs/#laborder)  
###  IntegrationTaskActionEvent 
The action event fields, plus:
Field Name| Type  
---|---  
integration_task| [IntegrationTask](/sdk/data-integration-task/#integrationtask)  
##  Enumeration types 
###  FaxDirection 
Value| Label  
---|---  
O| Outbound  
I| Inbound  
###  FaxStatus 
Value| Label  
---|---  
P| Processing  
S| Sent  
R| Received  
E| Error  
###  Event Type 
Value| Label  
---|---  
PRINTED| Printed  
FAXED| Faxed

---

# FollowUp

Source: https://docs.canvasmedical.com/sdk/data-follow-up/

##  Introduction 
The `FollowUp` model is the anchor for the [Follow Up](/sdk/commands/#followup) command — a requested follow-up (recall) recorded on a Note for a Patient.
##  Basic usage 
To get a follow up by identifier, use the `get` method on the `FollowUp` model manager:
    ```python
    from canvas_sdk.v1.data.follow_up import FollowUp
    follow_up = FollowUp.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient or note object, the follow ups can be accessed with the `follow_ups` attribute:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.v1.data.note import Note
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    follow_ups = patient.follow_ups.all()
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    follow_ups = note.follow_ups.all()
    ```
##  Committed follow ups 
The `committed` method returns follow ups that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.follow_up import FollowUp
    committed_follow_ups = FollowUp.objects.committed()
    ```
##  Attributes 
###  FollowUp 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
appointment_note| [Note](/sdk/data-note)  
requested_appointment_date| Date  
requested_appointment_date_original_input| String  
reason_for_visit| String  
reason_for_visit_coding| String  
note_to_patient| String  
internal_comment| String  
requested_appointment_type| EncounterMedium  
requested_note_type| [NoteType](/sdk/data-note)  
##  Enumeration types 
###  EncounterMedium 
Name| Value  
---|---  
VOICE| voice  
VIDEO| video  
OFFICE| office  
HOME| home  
OFFSITE| offsite  
LAB| lab  

---

# Goal

Source: https://docs.canvasmedical.com/sdk/data-goal/

##  Introduction 
The `Goal` model represents a patient Goal in Canvas, which is always associated with a Note and a Patient.
This page also documents UpdateGoal, the record of a goal's updates and closures, created by committing an [UpdateGoal command](/sdk/commands/#updategoal) or [CloseGoal command](/sdk/commands/#closegoal).
##  Basic usage 
To get a goal by identifier, use the `get` method on the `Goal` model manager:
    ```python
    from canvas_sdk.v1.data.goal import Goal
    goal = Goal.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, or note object, the goals for a patient or note can be accessed with the `goals` attribute on a `Patient` or `Note` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.v1.data.note import Note
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    goals = patient.goals.all()
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    goals = note.goals.all()
    ```
`UpdateGoal` records can be queried the same way, and each one links back to the goal it updates with the `goal` attribute:
    ```python
    from canvas_sdk.v1.data.goal import UpdateGoal
    update = UpdateGoal.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    goal = update.goal
    committed_updates = UpdateGoal.objects.committed()
    ```
##  Filtering 
Goals can be filtered by any attribute that exists on the model.
Filtering for goals is done with the `filter` method on the `Goal` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.goal import Goal, GoalAchievementStatus
    goals = Goal.objects.filter(achievement_status=GoalAchievementStatus.IN_PROGRESS)
    ```
###  Committed goals 
The `committed` method returns goals that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.goal import Goal
    committed_goals = Goal.objects.committed()
    ```
##  Goal updates and closures 
Each change to a goal — via the [UpdateGoal](/sdk/commands/#updategoal) or [CloseGoal](/sdk/commands/#closegoal) command — is recorded as an `UpdateGoal`. Update actions revise the goal while leaving it active; close actions also move it to a closed `lifecycle_status` (e.g. `completed`, `cancelled`, `rejected`). A goal's updates are reachable through its `updates` accessor:
    ```python
    from canvas_sdk.v1.data.goal import Goal
    goal = Goal.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    # Every update or close recorded against this goal.
    updates = goal.updates.all()
    # The most recent committed update — the goal's current state — or None.
    latest = goal.updates.committed().order_by("dbid").last()
    ```
`UpdateGoal` carries the same status, priority, and progress fields as `Goal` (without `goal_statement` / `start_date`), plus a `goal` foreign key back to the goal it updates. Like `Goal`, its manager supports `committed()` to filter to committed, non-entered-in-error records.
##  Attributes 
###  Goal 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
lifecycle_status| GoalLifecycleStatus  
achievement_status| GoalAchievementStatus  
priority| GoalPriority  
due_date| Date  
start_date| Date  
progress| String  
goal_statement| String  
updates| QuerySet[UpdateGoal]  
###  UpdateGoal 
An update or close action recorded against a Goal, reachable from a goal via `goal.updates`. Written by the [UpdateGoal](/sdk/commands/#updategoal) and [CloseGoal](/sdk/commands/#closegoal) commands.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
goal| Goal  
lifecycle_status| GoalLifecycleStatus  
achievement_status| GoalAchievementStatus  
priority| GoalPriority  
due_date| Date  
progress| String  
##  Enumeration types 
###  GoalLifecycleStatus 
Name| Value  
---|---  
PROPOSED| proposed  
PLANNED| planned  
ACCEPTED| accepted  
ACTIVE| active  
ON_HOLD| on-hold  
COMPLETED| completed  
CANCELLED| cancelled  
REJECTED| rejected  
###  GoalAchievementStatus 
Name| Value  
---|---  
IN_PROGRESS| in-progress  
IMPROVING| improving  
WORSENING| worsening  
NO_CHANGE| no-change  
ACHIEVED| achieved  
SUSTAINING| sustaining  
NOT_ACHIEVED| not-achieved  
NO_PROGRESS| no-progress  
NOT_ATTAINABLE| not-attainable  
###  GoalPriority 
Name| Value  
---|---  
HIGH| high-priority  
MEDIUM| medium-priority  
LOW| low-priority  

---

# Google Calendar

Source: https://docs.canvasmedical.com/sdk/data-google-calendar/

##  Introduction 
When a provider connects their Google account through native Google Calendar sync, Canvas imports the busy time from their selected Google calendars. Canvas stores that busy time in its own records rather than as [appointments](/sdk/data-appointment/) or [calendar events](/sdk/data-calendar/), so a scheduling or booking plugin that works out availability only from `Appointment` and `Event` misses it.
The Google Calendar data models give plugins read-only access to that busy time and to the state of each provider's connection:
  - `GoogleCalendarBusyBlock` is a period of busy time imported from Google for a provider.
  - `GoogleCalendarConnection` is a provider's connection to their Google account.
  - `GoogleCalendar` is a calendar on that connection.
Busy blocks carry only the time a provider is busy. They don't include the title or content of the Google event. These models have a `dbid` but no `id`.
##  Busy blocks 
A provider's busy blocks are available through the `google_calendar_busy_blocks` attribute on a [Staff](/sdk/data-staff/) object. When busy time is released, its busy block stays in the table with `active` set to `False`, so filter on `active=True` to get current busy time:
    ```python
    from canvas_sdk.v1.data.staff import Staff
    provider = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    busy_blocks = provider.google_calendar_busy_blocks.filter(active=True)
    ```
A busy block records its start and its length in minutes, not an end time. A Google event that spans several days arrives as one busy block for each day.
Releasing a busy block also updates its `modified` time. A plugin that keeps its own copy of busy time can query for blocks modified since its last check and remove those where `active` is `False`. If released busy time returns to Google, Canvas creates a new busy block rather than reactivating the released one.
###  Find a provider's busy time for a day 
This example lists a provider's current busy intervals that start on a given day, ordered by start time:
    ```python
    import datetime
    from canvas_sdk.v1.data.google_calendar import GoogleCalendarBusyBlock
    from logger import log
    day_start = datetime.datetime(2026, 10, 20, tzinfo=datetime.UTC)
    day_end = day_start + datetime.timedelta(days=1)
    busy_blocks = GoogleCalendarBusyBlock.objects.filter(
        provider__id="4150cd20de8a470aa570a852859ac87e",
        active=True,
        start_time__gte=day_start,
        start_time__lt=day_end,
    ).order_by("start_time")
    for block in busy_blocks:
        block_end = block.start_time + datetime.timedelta(minutes=block.duration_minutes)
        log.info(f"Busy from {block.start_time} to {block_end} at {block.location.full_name}")
    ```
##  Connections and calendars 
A provider's Google connection is available through the `google_calendar_connection` attribute on a `Staff` object. A provider who hasn't connected a Google account has no connection, so filter on the `staff` field to get `None` back instead of an exception:
    ```python
    from canvas_sdk.v1.data.google_calendar import GoogleCalendarConnection
    from canvas_sdk.v1.data.staff import Staff
    provider = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    connection = GoogleCalendarConnection.objects.filter(staff=provider).first()
    ```
When `needs_reconnect` is `True`, the provider needs to reconnect their Google account in Canvas.
The calendars on a connection are available through its `calendars` attribute. Only selected calendars feed busy blocks. The calendar with `is_app_created` set to `True` is the one Canvas writes appointments to:
    ```python
    from canvas_sdk.v1.data.google_calendar import GoogleCalendarConnection
    connection = GoogleCalendarConnection.objects.filter(
        staff__id="4150cd20de8a470aa570a852859ac87e"
    ).first()
    if connection is not None:
        busy_time_calendars = connection.calendars.filter(selected=True)
        canvas_calendar = connection.calendars.filter(is_app_created=True).first()
    ```
##  Attributes 
###  GoogleCalendarBusyBlock 
Field Name| Type| Description  
---|---|---  
dbid| Integer| Database identifier  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
provider| [Staff](/sdk/data-staff/#staff)| The provider who is busy  
location| [PracticeLocation](/sdk/data-practicelocation/)| The practice location the busy block applies to  
start_time| DateTime| When the busy time starts  
duration_minutes| Integer| How long the busy time lasts, in minutes  
active| Boolean| Whether the block is current busy time; `False` once the time is released  
###  GoogleCalendarConnection 
Field Name| Type| Description  
---|---|---  
dbid| Integer| Database identifier  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
staff| [Staff](/sdk/data-staff/#staff)| The provider who owns the connection  
google_account_email| String| The email address of the connected Google account  
needs_reconnect| Boolean| Whether the provider must reconnect their Google account  
calendars| GoogleCalendar[]| The Google calendars on this connection  
###  GoogleCalendar 
Field Name| Type| Description  
---|---|---  
dbid| Integer| Database identifier  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
connection| GoogleCalendarConnection| The connection the calendar belongs to  
summary| String| The calendar's name in Google  
selected| Boolean| Whether the calendar's events feed busy blocks  
is_app_created| Boolean| Whether this is the calendar Canvas writes appointments to  

---

# Group

Source: https://docs.canvasmedical.com/sdk/data-group/

##  Introduction 
The `Group` model gives you the stable external identifier Canvas uses to expose a [Team](/sdk/data-team/#team) or a [PatientGroup](/sdk/data-patient-group/#patientgroup) as a single FHIR resource, so you can move between an SDK record and its FHIR representation without tracking a separate identifier yourself.
A `Group` is a stable external identifier that Canvas attaches through a generic relation — the [`content_type`](/sdk/data-content-type/#contenttype) and `object_id` fields, the same pattern [OrganizationalEntity](/sdk/data-organizational-entity/#organizationalentity) uses — to either a `Team` or a `PatientGroup`, the record this reference calls the Group's content object. This identifier is exactly what the FHIR [Group endpoint](/api/group/) exposes as its `id`. A `Team` surfaces as a FHIR Group of type `practitioner`, and a `PatientGroup` surfaces as a FHIR Group of type `person`.
Reach for `Group` when you hold a FHIR Group `id` — the stable external identifier — and need to resolve which SDK record it names, a `Team` or a `PatientGroup`. When you already have a `Team` in hand, its [`group_id`](/sdk/data-team/#reconciling-with-fhir) is the shorter path, because it exposes the FHIR Group id directly.
`Group` exposes the linked record through typed property accessors. Create the underlying FHIR Group through the [FHIR API](/api/group/). To add or deactivate members of an existing patient group, use the [patient group effects](/sdk/effect-patient-group/).
##  Basic usage 
To follow a `Group` to the record it points at, retrieve the `Group` by `id` and read whichever typed property is set:
    ```python
    from canvas_sdk.v1.data import Group
    group = Group.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    if group.team is not None:
        linked = group.team
    elif group.patient_group is not None:
        linked = group.patient_group
    else:
        linked = None
    ```
For a `Group` whose content object is a `Team`, `team` returns the linked [Team](/sdk/data-team/#team) and `patient_group` is `None`. For a `Group` whose content object is a `PatientGroup`, `patient_group` returns the linked [PatientGroup](/sdk/data-patient-group/#patientgroup) and `team` is `None`. When a `Group` is not backed by either type, both properties return `None`, so read whichever property is set rather than assuming one always resolves.
##  Attributes 
###  Group 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
content_type| [ContentType](/sdk/data-content-type/#contenttype)|   
object_id| Integer|   
team| [Team](/sdk/data-team/#team) | `None` (computed)| The `Team` this group points at, or `None` when its content object is not a `Team`.  
patient_group| [PatientGroup](/sdk/data-patient-group/#patientgroup) | `None` (computed)| The `PatientGroup` this group points at, or `None` when its content object is not a `PatientGroup`.  
The `object_id` field holds the target record's `dbid` — its internal integer identifier — rather than its `id` UUID.
Only two kinds of record get a `Group`, so `content_type.model` is always one of these two values. Read it to tell which one a `Group` points at, or read `team` or `patient_group` in the table below, which do the same check for you.
`content_type.model`| Content object  
---|---  
`team`| [Team](/sdk/data-team/#team)  
`patientgroup`| [PatientGroup](/sdk/data-patient-group/#patientgroup)

---

# HistoryOfPresentIllness

Source: https://docs.canvasmedical.com/sdk/data-history-present-illness/

##  Introduction 
The `HistoryOfPresentIllness` model represents a History of Present Illness (HPI) recorded on a Note, and is always associated with a Note and a Patient. It is the data model behind the `hpi` command.
##  Basic usage 
To get an HPI by identifier, use the `get` method on the `HistoryOfPresentIllness` model manager:
    ```python
    from canvas_sdk.v1.data.history_present_illness import HistoryOfPresentIllness
    hpi = HistoryOfPresentIllness.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, or note object, the histories of present illness for a patient or note can be accessed with the `histories_of_present_illness` attribute on a `Patient` or `Note` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.v1.data.note import Note
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    histories = patient.histories_of_present_illness.all()
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    histories = note.histories_of_present_illness.all()
    ```
##  Reading the narrative 
The HPI text is stored as a structured document in `narrative_json`. The `narrative` property renders it as plain text, so that is the field to read:
    ```python
    from canvas_sdk.v1.data.history_present_illness import HistoryOfPresentIllness
    hpi = HistoryOfPresentIllness.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    text = hpi.narrative
    ```
##  Filtering 
Histories of present illness can be filtered by any column on the model. Note that `narrative` is a Python property rather than a column, so it cannot be used in `filter()` — filter on `narrative_json` instead.
###  Committed histories of present illness 
The `committed` method returns records that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.history_present_illness import HistoryOfPresentIllness
    committed_histories = HistoryOfPresentIllness.objects.committed()
    ```
##  Attributes 
###  HistoryOfPresentIllness 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
narrative_json| JSON  
narrative| String (computed)  

---

# Imaging Report Template

Source: https://docs.canvasmedical.com/sdk/data-imaging-report-template/

##  Introduction 
The `ImagingReportTemplate`, `ImagingReportTemplateField`, and `ImagingReportTemplateFieldOption` models represent the templates used for imaging reports. Templates define the structure of an imaging report, including what fields need to be filled in and what options are available for each field.
##  Basic Usage 
To retrieve an `ImagingReportTemplate` by identifier, use the `get` method on the model manager:
    ```python
    from canvas_sdk.v1.data.imaging import ImagingReportTemplate
    template = ImagingReportTemplate.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    ```
To access the fields defined in a template:
    ```python
    from canvas_sdk.v1.data.imaging import ImagingReportTemplate
    template = ImagingReportTemplate.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    fields = template.fields.all()
    ```
##  Filtering 
Templates can be filtered by any attribute on the models.
###  By active status 
    ```python
    from canvas_sdk.v1.data.imaging import ImagingReportTemplate
    active_templates = ImagingReportTemplate.objects.active()
    ```
###  By type 
    ```python
    from canvas_sdk.v1.data.imaging import ImagingReportTemplate
    # Get custom (user-created) templates
    custom = ImagingReportTemplate.objects.custom()
    # Get built-in (system) templates
    builtin = ImagingReportTemplate.objects.builtin()
    ```
###  By search 
    ```python
    from canvas_sdk.v1.data.imaging import ImagingReportTemplate
    results = ImagingReportTemplate.objects.search("chest x-ray")
    ```
##  Attributes 
###  ImagingReportTemplate 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
name| String  
long_name| String  
code| String  
code_system| String  
search_keywords| String  
active| Boolean  
custom| Boolean  
rank| Integer  
fields| ImagingReportTemplateField[]  
###  ImagingReportTemplateField 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
report_template| ImagingReportTemplate  
sequence| Integer  
code| String  
code_system| String  
label| String  
units| String  
type| String  
required| Boolean  
options| ImagingReportTemplateFieldOption[]  
###  ImagingReportTemplateFieldOption 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
field| ImagingReportTemplateField  
label| String  
key| String  

---

# Imaging

Source: https://docs.canvasmedical.com/sdk/data-imaging/

##  Introduction 
The `ImagingOrder`, `ImagingReview`, `ImagingReport`, and `ImagingReportCoding` models represent imaging results.
##  Basic Usage 
To retrieve an `ImagingOrder`, `ImagingReview`, or `ImagingReport` by identifier, use the `get` method on the model manager:
    ```python
    from canvas_sdk.v1.data.imaging import ImagingOrder, ImagingReview, ImagingReport
    imaging_order = ImagingOrder.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    imaging_review = ImagingReview.objects.get(id="c02c6b02-2581-46bf-819c-b5aacad2134c")
    imaging_report = ImagingReport.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    ```
If you have a patient object, the orders, reviews, and reports can be accessed with the `imaging_orders`, `imaging_reviews`, and `imaging_results` attributes, respectively on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    orders = patient.imaging_orders.all()
    reviews = patient.imaging_reviews.all()
    reports = patient.imaging_results.all()
    ```
##  Filtering 
Imaging orders, reviews, and reports can be filtered by any attribute that exists on the models.
Filtering is done with the `filter` method on the `ImagingOrder`, `ImagingReview`, and `ImagingReport` model managers.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.imaging import ImagingOrder, ImagingReview, ImagingReport
    orders = ImagingOrder.objects.filter(status="completed")
    reviews = ImagingReview.objects.filter(is_released_to_patient=False)
    reports = ImagingReport.objects.filter(requires_signature=True)
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
`ImagingReport` supports `ValueSet` filtering through the `find` method on its model manager:
    ```python
    from canvas_sdk.v1.data.imaging import ImagingReport
    from canvas_sdk.value_set.v2022.diagnostic_study import Mammography
    reports = ImagingReport.objects.find(Mammography)
    ```
`find` joins through the report's `codings` reverse relation and matches on `(system, code)` pairs from the value set, so a coding must match both the code system and the code to be included.
###  Committed records 
The `committed` method returns `ImagingOrder` and `ImagingReview` records that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.imaging import ImagingOrder, ImagingReview
    committed_orders = ImagingOrder.objects.committed()
    committed_reviews = ImagingReview.objects.committed()
    ```
##  Related Tasks 
To retrieve an Imaging Order's related tasks, use the `get_task_objects` method on the ImagingOrder object.
    ```python
    from canvas_sdk.v1.data.imaging import ImagingOrder
    imaging_order = ImagingOrder.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    tasks = imaging_order.get_task_objects().all()
    ```
The `task_list` computed property returns the same related tasks as a `list[Task]`:
    ```python
    from canvas_sdk.v1.data.imaging import ImagingOrder
    imaging_order = ImagingOrder.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    tasks = imaging_order.task_list
    ```
##  Accessing the report file 
The `document_url` property on `ImagingReport` returns a presigned S3 URL for securely accessing the report's file. The URL is valid for one hour and is regenerated on each access, so don't persist or cache it. If the report has no associated file, `document_url` returns `None`.
    ```python
    from canvas_sdk.v1.data.imaging import ImagingReport
    imaging_report = ImagingReport.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    # Presigned S3 URL to the report file, or None if the report has no file
    url = imaging_report.document_url
    ```
##  Accessing the imaging order PDF 
The `document_url` property on `ImagingOrder` returns a presigned S3 URL for the order's PDF, or `None` when the order has none. Canvas saves the PDF the first time the order is faxed. Printing the order doesn't save it, so an order that has never been faxed has no file. The URL is valid for one hour, so generate it when you need it rather than storing it.
    ```python
    from canvas_sdk.v1.data.imaging import ImagingOrder
    imaging_order = ImagingOrder.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    # Presigned S3 URL to the order PDF, or None if no PDF has been saved
    url = imaging_order.document_url
    ```
##  Review assignment 
An imaging report is assigned for review to staff members or to a team. `reviewers` holds the assigned staff members, and `team` holds the assigned team, or `None` when no team is assigned.
    ```python
    from canvas_sdk.v1.data import ImagingReport, Staff
    imaging_report = ImagingReport.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    # The staff members and the team the imaging report is assigned to
    reviewers = imaging_report.reviewers.all()
    team = imaging_report.team
    # Every imaging report assigned to this staff member
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    assigned = ImagingReport.objects.filter(reviewers__id=staff.id)
    ```
##  The document reference 
A report that has a file also has a [DocumentReference](/sdk/data-document-reference/#the-related-object) pointing back at it — the record that carries the report's document coding, category, and status, and that represents it in the FHIR API. `document_url` above is the direct route to the file itself; reach for the document reference when you want that surrounding metadata.
Resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` — never hardcode the per-environment `dbid` — and match `object_id` against the report's `dbid`:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference, ImagingReport
    imaging_report = ImagingReport.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    content_type = ContentType.objects.filter(app_label="api", model="imagingreport").first()
    document = DocumentReference.objects.filter(
        content_type=content_type, object_id=imaging_report.dbid
    ).first()
    ```
> **Info:** `object_id` holds the related record's integer `dbid`, not its UUID `id`. A report with no file has no document reference, so handle `None`.
##  Attributes 
###  ImagingOrder 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
imaging| String  
imaging_center| [ServiceProvider](/sdk/data-serviceprovider/#service-provider)  
note_to_radiologist| String  
internal_comment| String  
status| [OrderStatus](/sdk/data-enumeration-types/#orderstatus)  
date_time_ordered| DateTime  
ordering_provider| [Staff](/sdk/data-staff/#staff)  
priority| String  
delegated| Boolean  
document| File (S3 key)  
document_url| String (computed)  
task_ids| String  
results| ImagingReport[]  
action_events| [ImagingOrderActionEvent](/sdk/data-fax/#imagingorderactionevent)[]  
###  ImagingReview 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient_communication_method| [ReviewPatientCommunicationMethod](/sdk/data-enumeration-types/#reviewpatientcommunicationmethod)  
internal_comment| String  
message_to_patient| String  
is_released_to_patient| Boolean  
status| [ReviewStatus](/sdk/data-enumeration-types/#reviewstatus)  
note| [Note](/sdk/data-note/#note)  
patient| [Patient](/sdk/data-patient/#patient)  
###  ImagingReport 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
review_mode| [DocumentReviewMode](/sdk/data-enumeration-types/#documentreviewmode)|   
junked| Boolean|   
requires_signature| Boolean|   
assigned_date| DateTime|   
assigned_by| [CanvasUser](/sdk/data-canvasuser)|   
reviewers| [Staff](/sdk/data-staff/#staff)[]|   
team| [Team](/sdk/data-team/#team)|   
team_assigned_date| DateTime|   
patient| [Patient](/sdk/data-patient/#patient)|   
order| ImagingOrder|   
source| ImagingReportSource|   
name| String|   
result_date| Date|   
original_date| Date|   
review| ImagingReview|   
document_url| String (computed)| Presigned S3 URL, or `None` if the report has no file  
codings| ImagingReportCoding[]|   
###  ImagingReportCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
report| ImagingReport  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
value| String  
##  Enumeration types 
###  ImagingReportSource 
Value| Label  
---|---  
RADIOLOGY_PATIENT| Radiology Report From Patient  
VERBAL_PATIENT| Verbal Report From Patient  
DIRECTLY_RADIOLOGY| Directly Radiology Report  

---

# Immunization

Source: https://docs.canvasmedical.com/sdk/data-immunization/

##  Introduction 
The `Immunization` model represents a record of immunization events and immunization statements for a patient. Immunizations can be actively administered medications or historical records of immunizations received elsewhere. The `ImmunizationStatement` model represents historical immunization records and vaccination history.
##  Basic usage 
To get an immunization by identifier, use the `get` method on the `Immunization` model manager:
    ```python
    from canvas_sdk.v1.data.immunization import Immunization
    immunization = Immunization.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the immunizations for a patient can be accessed with the `immunizations` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    immunizations = patient.immunizations.all()
    ```
If you have a patient ID, you can get the immunizations for the patient with the `for_patient` method on the `Immunization` model manager:
    ```python
    from canvas_sdk.v1.data.immunization import Immunization
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    immunizations = Immunization.objects.for_patient(patient_id)
    ```
##  Codings 
The codings for an immunization can be accessed with the `codings` attribute on an `Immunization` object:
    ```python
    from canvas_sdk.v1.data.immunization import Immunization
    from logger import log
    immunization = Immunization.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in immunization.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
##  Filtering 
Immunizations can be filtered by any attribute that exists on the model.
Filtering for immunizations is done with the `filter` method on the `Immunization` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.immunization import Immunization
    immunizations = Immunization.objects.filter(status="completed")
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The `find` method on the model manager is used to perform `ValueSet` filtering:
    ```python
    from canvas_sdk.v1.data.immunization import Immunization
    from canvas_sdk.value_set.v2022.immunization import InfluenzaVaccine
    immunizations = Immunization.objects.find(InfluenzaVaccine)
    ```
`find` also works on the `ImmunizationStatement` model manager, matching against the statement's own coding records, which it exposes through the singular `coding` accessor (unlike `Immunization.codings`):
    ```python
    from canvas_sdk.v1.data.immunization import ImmunizationStatement
    from canvas_sdk.value_set.v2022.immunization import InfluenzaVaccine
    immunization_statements = ImmunizationStatement.objects.find(InfluenzaVaccine)
    ```
###  Committed and active records 
The `committed` method returns immunizations that have been committed and not entered in error. The `active` method is an alias for `committed` and returns the same records:
    ```python
    from canvas_sdk.v1.data.immunization import Immunization
    committed_immunizations = Immunization.objects.committed()
    active_immunizations = Immunization.objects.active()
    ```
The same methods are available on the `ImmunizationStatement` model manager:
    ```python
    from canvas_sdk.v1.data.immunization import ImmunizationStatement
    committed_statements = ImmunizationStatement.objects.committed()
    active_statements = ImmunizationStatement.objects.active()
    ```
##  Immunization Statements 
To work with immunization statements (historical records), use the `ImmunizationStatement` model:
    ```python
    from canvas_sdk.v1.data.immunization import ImmunizationStatement
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    immunization_statements = ImmunizationStatement.objects.for_patient(patient_id)
    ```
##  Attributes 
###  Immunization 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
status| ImmunizationStatus  
lot_number| String  
manufacturer| String  
exp_date_original| String  
exp_date| Date  
sig_original| String  
date_ordered| Date  
given_by| [Staff](/sdk/data-staff/#staff)  
consent_given| Boolean  
take_quantity| Float  
dose_form| String  
route| String  
frequency_normalized_per_day| Float  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
originator| [CanvasUser](/sdk/data-canvasuser)  
created| DateTime  
modified| DateTime  
codings| ImmunizationCoding[]  
###  ImmunizationCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
immunization| Immunization  
###  ImmunizationStatement 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
date_original| String  
date| Date  
evidence| String  
comment| String  
reason_not_given| ImmunizationReasonsNotGiven  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
originator| [CanvasUser](/sdk/data-canvasuser)  
created| DateTime  
modified| DateTime  
coding| ImmunizationStatementCoding[]  
###  ImmunizationStatementCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
immunization_statement| ImmunizationStatement  
##  Enumeration types 
###  ImmunizationStatus 
Value| Label  
---|---  
in-progress| In Progress  
on-hold| on-hold  
completed| completed  
stopped| stopped  
###  ImmunizationReasonsNotGiven 
Value| Label  
---|---  
NA| not applicable  
IMMUNE| immunity  
MEDPREC| medical precaution  
OSTOCK| product out of stock  
PATOBJ| patient objection  

---

# Instruction

Source: https://docs.canvasmedical.com/sdk/data-instruction/

##  Introduction 
The `Instruction` model represents an `Instruct` command in a patient's note — for example, "cessation of smoking" counseling, dietary instructions, or any other piece of clinical guidance recorded as an Instruct command. Instructions are included regardless of command state (staged or committed); use `.committed()` to filter to only committed commands.
Querying `Instruction` from a plugin is the recommended way to ask "has this patient been given an instruction in this value set?" — for example, when computing quality measures that look for tobacco cessation counseling or dialysis education.
##  Basic usage 
To get an instruction by identifier, use the `get` method on the `Instruction` model manager:
    ```python
    from canvas_sdk.v1.data.instruction import Instruction
    instruction = Instruction.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the instructions for a patient can be accessed with the `instructions` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    # Returns all instructions for the patient, regardless of command state (staged or committed)
    instructions = patient.instructions.all()
    ```
If you have a patient ID, you can get the instructions for the patient with the `for_patient` method on the `Instruction` model manager:
    ```python
    from canvas_sdk.v1.data.instruction import Instruction
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    # All instructions for the patient, regardless of command state (staged or committed)
    instructions = Instruction.objects.for_patient(patient_id)
    # Only committed instructions for the patient
    committed_instructions = Instruction.objects.for_patient(patient_id).committed()
    ```
##  Codings 
The codings for an instruction can be accessed with the `codings` attribute on an `Instruction` object:
    ```python
    from canvas_sdk.v1.data.instruction import Instruction
    from logger import log
    instruction = Instruction.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in instruction.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
Instruct commands originated through the SDK use either the SNOMED CT code system or an internal "unstructured" system for free-text instructions. See the [InstructCommand](/sdk/commands/#instruct) effect for the write-side details.
##  Committed instructions 
The `committed` method returns instructions whose underlying command has been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.instruction import Instruction
    committed_instructions = Instruction.objects.committed()
    ```
##  Filtering 
Instructions can be filtered by any attribute that exists on the model.
Filtering for instructions is done with the `filter` method on the `Instruction` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.instruction import Instruction
    instructions = Instruction.objects.filter(note__id="2c91b0d8-7b9d-4ef1-89e2-1f9a3a8a2b14")
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The `find` method on the model manager is used to perform `ValueSet` filtering:
    ```python
    from canvas_sdk.v1.data.instruction import Instruction
    from canvas_sdk.value_set.v2022.intervention import TobaccoUseCessationCounseling
    cessation_counseling = (
        Instruction.objects
        .for_patient("1eed3ea2a8d546a1b681a2a45de1d790")
        .committed()
        .find(TobaccoUseCessationCounseling)
    )
    ```
`find` joins through the `codings` reverse relation and filters on `(system, code)` pairs from the value set, so it composes naturally with `for_patient` and `committed`.
##  Attributes 
###  Instruction 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
narrative| String  
codings| InstructionCoding[]  
###  InstructionCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
instruction| Instruction  

---

# Integration Task

Source: https://docs.canvasmedical.com/sdk/data-integration-task/

##  Introduction 
The `IntegrationTask` and `IntegrationTaskReview` models represent incoming documents that need processing in Canvas. Integration tasks are created when documents arrive via fax, document upload, integration engine, or the patient portal. Each task can have one or more reviews that track who is responsible for processing the document and its current state.
##  Basic Usage 
To retrieve an `IntegrationTask` or `IntegrationTaskReview` by identifier, use the `get` method on the model manager:
    ```python
    from canvas_sdk.v1.data.integration_task import IntegrationTask, IntegrationTaskReview
    task = IntegrationTask.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    review = IntegrationTaskReview.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    ```
If you have a patient object, integration tasks can be accessed with the `integration_tasks` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    tasks = patient.integration_tasks.all()
    ```
##  Accessing the document file 
The `document_url` property returns a presigned S3 URL for the document as Canvas received it, or `None` when the task has no file. The URL is valid for one hour, so generate it when you need it rather than storing it.
    ```python
    from canvas_sdk.v1.data.integration_task import IntegrationTask
    task = IntegrationTask.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    # Presigned S3 URL to the received document, or None
    url = task.document_url
    ```
> **Info:** `document_url` always points to the original file. Canvas saves staff annotations as separate files that the SDK doesn't expose, so the URL doesn't reflect them.
##  Filtering 
Integration tasks and reviews can be filtered by any attribute that exists on the models.
###  By status 
Filter tasks by their processing status:
    ```python
    from canvas_sdk.v1.data.integration_task import IntegrationTask
    # Get all unread tasks
    unread = IntegrationTask.objects.unread()
    # Get tasks pending review (UNREAD or READ)
    pending = IntegrationTask.objects.pending_review()
    # Get processed tasks (PROCESSED or REVIEWED)
    processed = IntegrationTask.objects.processed()
    # Get tasks with errors
    errored = IntegrationTask.objects.with_errors()
    # Get non-junked tasks
    active = IntegrationTask.objects.not_junked()
    ```
###  By channel 
Filter tasks by their source channel:
    ```python
    from canvas_sdk.v1.data.integration_task import IntegrationTask
    faxes = IntegrationTask.objects.faxes()
    uploads = IntegrationTask.objects.uploads()
    engine_tasks = IntegrationTask.objects.from_integration_engine()
    portal_tasks = IntegrationTask.objects.from_patient_portal()
    ```
###  By patient 
    ```python
    from canvas_sdk.v1.data.integration_task import IntegrationTask
    tasks = IntegrationTask.objects.for_patient("patient-id")
    ```
###  Filtering reviews 
    ```python
    from canvas_sdk.v1.data.integration_task import IntegrationTaskReview
    # Get reviews for a specific task
    reviews = IntegrationTaskReview.objects.for_task("task-id")
    # Get active (non-junked) reviews
    active_reviews = IntegrationTaskReview.objects.active()
    # Get reviews by a specific reviewer
    reviewer_reviews = IntegrationTaskReview.objects.by_reviewer("staff-id")
    # Get reviews assigned to a specific team
    team_reviews = IntegrationTaskReview.objects.by_team("team-id")
    ```
##  Attributes 
###  IntegrationTask 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
status| IntegrationTaskStatus|   
type| String|   
title| String|   
document| File (S3 key)| The document as received  
channel| IntegrationTaskChannel|   
patient| [Patient](/sdk/data-patient/#patient)|   
service_provider| [ServiceProvider](/sdk/data-serviceprovider/#service-provider)|   
reviews| IntegrationTaskReview[]|   
action_events| [IntegrationTaskActionEvent](/sdk/data-fax/#integrationtaskactionevent)[]| Faxes of this task, with their [delivery status](/sdk/data-fax/#delivery-status)  
document_url| String (computed)| Presigned S3 URL for `document`, or `None` if unset  
is_fax| Boolean (computed)| Whether this is a fax task  
is_pending| Boolean (computed)| Whether this task is pending review  
is_processed| Boolean (computed)| Whether this task has been processed  
has_error| Boolean (computed)| Whether this task has an error  
is_junked| Boolean (computed)| Whether this task is junked  
###  IntegrationTaskReview 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
task| IntegrationTask|   
template_name| String|   
document_key| String|   
reviewer| [Staff](/sdk/data-staff/#staff)|   
team_reviewer| [Team](/sdk/data-team/#team)|   
junked| Boolean|   
is_active| Boolean (computed)| Whether this review is active (not junked)  
##  Enumeration types 
###  IntegrationTaskStatus 
Value| Label  
---|---  
UNR| Unread  
UER| Unread Error  
REA| Read  
ERR| Error  
PRO| Processed  
REV| Reviewed  
JUN| Junk  
###  IntegrationTaskChannel 
Value| Label  
---|---  
fax| Fax  
document_upload| Document Upload  
from_integration_engine| From Integration Engine  
from_patient_portal| From Patient Portal  

---

# Invoice

Source: https://docs.canvasmedical.com/sdk/data-invoice/

##  Introduction 
The `Invoice` model represents a statement generated for a patient or their guarantor — who it was addressed to, what it totals, how it was sent, and where it stands.
Invoices are produced by Canvas billing workflows rather than by plugins: automated statement runs, batch runs, and one-off statements each record their origin in `workflow`.
> **Info:** Invoice records have no UUID `id` — they are identified by their integer `dbid`.
##  Basic Usage 
    ```python
    from canvas_sdk.v1.data import Invoice
    invoice = Invoice.objects.get(dbid=42)
    ```
If you have a `Patient` object, the statements addressed to them are available through the `invoices` reverse relation:
    ```python
    from canvas_sdk.v1.data import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    invoices = patient.invoices.all()
    ```
A [Claim](/sdk/data-claim/#claim) points at the most recent statement it appeared on:
    ```python
    from canvas_sdk.v1.data import Claim
    claim = Claim.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    invoice = claim.latest_invoice
    ```
##  Filtering 
    ```python
    from canvas_sdk.v1.data.invoice import Invoice, InvoiceStatus, InvoiceWorkflow
    # Active statements only
    active = Invoice.objects.filter(status=InvoiceStatus.ACTIVE)
    # Statements a staff member generated one at a time, rather than by a batch or automated run
    adhoc = Invoice.objects.filter(workflow=InvoiceWorkflow.ADHOC)
    ```
`Invoice` is addressed through `recipient` rather than a `patient` field, so filter on `recipient` to scope to one patient:
    ```python
    from canvas_sdk.v1.data import Invoice
    invoices = Invoice.objects.filter(recipient__id="1eed3ea2a8d546a1b681a2a45de1d790")
    ```
##  Accessing the statement PDF 
The `invoice_pdf_url` property returns a presigned S3 URL for the statement's PDF, or `None` when the invoice has no PDF. The URL is valid for one hour, so generate it when you need it rather than storing it.
    ```python
    from canvas_sdk.v1.data import Invoice
    invoice = Invoice.objects.get(dbid=42)
    # Presigned S3 URL to the statement PDF, or None if there is no PDF
    url = invoice.invoice_pdf_url
    ```
##  The document reference 
Canvas also attaches the same PDF to a [DocumentReference](/sdk/data-document-reference/#the-related-object), which carries the statement's document coding and status and represents it in the FHIR API. Use `invoice_pdf_url` to get the file itself, and the document reference when you want that metadata.
To find it, resolve the [ContentType](/sdk/data-content-type/) for the invoice and match `object_id` against the invoice's `dbid`:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference, Invoice
    invoice = Invoice.objects.get(dbid=42)
    content_type = ContentType.objects.filter(
        app_label="quality_and_revenue", model="invoicefull"
    ).first()
    document = DocumentReference.objects.filter(
        content_type=content_type, object_id=invoice.dbid
    ).first()
    url = document.document_url if document else None
    ```
##  Attributes 
###  Invoice 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser/)  
recipient| [Patient](/sdk/data-patient/#patient)  
recipient_type| InvoiceRecipients  
total_amount| Decimal  
invoice_pdf| File (S3 key)  
invoice_pdf_url| String (computed)  
status| InvoiceStatus  
workflow| InvoiceWorkflow  
error_message| String  
sent_mean| InvoiceSentMeans  
`error_message` carries the reason a statement failed to go out, and is empty for statements that did not fail.
##  Enumeration types 
###  InvoiceRecipients 
Who the statement was addressed to.
Value| Label  
---|---  
patient| Patient  
guarantor| Guarantor  
###  InvoiceStatus 
Value| Label  
---|---  
active| Active  
error| Error  
archived| Archived  
###  InvoiceWorkflow 
How the statement was produced.
Value| Label  
---|---  
automated| Automated  
adhoc| Adhoc  
batch| Batch  
###  InvoiceSentMeans 
Value| Label  
---|---  
mail| Mail  
e-mail| E-mail

---

# LabPartner, LabPartnerTest & AOE Questions

Source: https://docs.canvasmedical.com/sdk/data-lab-partner-and-test/

##  Introduction 
The **LabPartner** , **LabPartnerTest** , **LabPartnerTestQuestion** , and **LabPartnerTestQuestionChoice** models represent external lab partners, the tests they offer, and the ask-at-order-entry (AOE) questions associated with each test within Canvas.
* * *
##  LabPartner 
The `LabPartner` model stores information about a lab partner
###  Basic Usage 
To retrieve a lab partner by its unique identifier:
    ```python
    from canvas_sdk.v1.data.lab import LabPartner
    lab_partner = LabPartner.objects.get(id="your-uuid-here")
    ```
You can also filter lab partners by attributes. For example, to list all active lab partners:
    ```python
    from canvas_sdk.v1.data.lab import LabPartner
    active_lab_partners = LabPartner.objects.filter(active=True)
    ```
##  LabPartnerTest 
The `LabPartnerTest` model represents a test offered by a lab partner. Each test is linked to a lab partner via a foreign key.
###  Basic Usage 
To retrieve tests for a given lab partner, you can access the related tests using the reverse relationship:
    ```python
    from canvas_sdk.v1.data.lab import LabPartner
    lab_partner = LabPartner.objects.get(id="your-uuid-here")
    tests = lab_partner.available_tests.all()
    ```
Alternatively, you can directly filter tests by attributes:
    ```python
    from canvas_sdk.v1.data.lab import LabPartnerTest
    tests_with_code = LabPartnerTest.objects.filter(order_code="XYZ123")
    ```
##  Attributes 
###  LabPartner 
Field Name| Type| Description  
---|---|---  
id| UUID| The universally unique identifier for the lab partner.  
dbid| Integer| The internal database identifier (primary key) for the lab partner.  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
name| String| The name of the lab partner.  
active| Boolean| Indicates whether the lab partner is currently active.  
electronic_ordering_enabled| Boolean| Indicates if electronic ordering is enabled for this lab partner.  
keywords| Text| Keywords associated with the lab partner.  
default_lab_account_number| String| The default lab account number used for orders.  
available_tests| LabPartnerTest[]| The tests offered by this lab partner (reverse relation, accessible via `available_tests`).  
###  LabPartnerTest Attributes 
Field Name| Type| Description  
---|---|---  
id| UUID| The universally unique identifier for the test record.  
dbid| Integer| The internal database identifier (primary key) for the test record.  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
lab_partner| LabPartner| A reference to the related `LabPartner` (accessible via the related name `available_tests`).  
order_code| String| A code used to identify the test order. May be blank.  
order_name| Text| The name of the test order.  
keywords| Text| Keywords associated with the test. May be blank.  
cpt_code| String| The CPT code for the test, if available. Can be blank or null.  
questions| LabPartnerTestQuestion[]| AOE questions associated with this test.  
* * *
##  LabPartnerTestQuestion 
The `LabPartnerTestQuestion` model represents an ask-at-order-entry (AOE) question associated with a lab partner test. AOE questions are prompts that must be answered when ordering a specific lab test (e.g., "Is the patient fasting?", "Source of specimen").
###  Basic Usage 
To retrieve questions for a given lab partner test:
    ```python
    from canvas_sdk.v1.data.lab import LabPartnerTest
    test = LabPartnerTest.objects.get(id="your-uuid-here")
    questions = test.questions.all()
    ```
To filter for required questions only:
    ```python
    required_questions = test.questions.filter(required=True)
    ```
To directly query questions by code:
    ```python
    from canvas_sdk.v1.data.lab import LabPartnerTestQuestion
    questions = LabPartnerTestQuestion.objects.filter(code="FAST")
    ```
* * *
##  LabPartnerTestQuestionChoice 
The `LabPartnerTestQuestionChoice` model represents a selectable answer option for an AOE question. Not all questions have predefined choices (e.g., free-text questions may have none).
###  Basic Usage 
To retrieve choices for a given question:
    ```python
    question = test.questions.first()
    choices = question.choices.all()
    ```
###  Example: Building AOE prompts for a lab test 
    ```python
    from canvas_sdk.v1.data.lab import LabPartnerTest
    from logger import log
    test = LabPartnerTest.objects.get(id="your-uuid-here")
    for question in test.questions.all():
        log.info(f"Question: {question.body} (required={question.required})")
        for choice in question.choices.all():
            log.info(f"  - {choice.label}: {choice.value}")
    ```
##  Attributes 
###  LabPartnerTestQuestion Attributes 
Field Name| Type| Description  
---|---|---  
dbid| Integer| The internal database identifier (primary key) for the question.  
lab_partner_test| LabPartnerTest| A reference to the related `LabPartnerTest` (accessible via the related name `questions`).  
required| Boolean| Whether this question must be answered when ordering the test.  
code| String| A code identifying the question (e.g., "FAST" for fasting status).  
body| Text| The full text of the question displayed to the user.  
type| String| The question type (e.g., "text", "select", "date", "numeric").  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
choices| LabPartnerTestQuestionChoice[]| Selectable answer options for this question.  
###  LabPartnerTestQuestionChoice Attributes 
Field Name| Type| Description  
---|---|---  
dbid| Integer| The internal database identifier (primary key) for the choice.  
lab_partner_test_question| LabPartnerTestQuestion| A reference to the related `LabPartnerTestQuestion` (accessible via the related name `choices`).  
label| String| The display label for this choice (shown to the user).  
value| String| The value submitted when this choice is selected.  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  

---

# Lab Report Template

Source: https://docs.canvasmedical.com/sdk/data-lab-report-template/

##  Introduction 
The `LabReportTemplate`, `LabReportTemplateField`, and `LabReportTemplateFieldOption` models represent the templates used for point-of-care (POC) labs and custom lab reports. Templates define the structure of a lab report, including what fields need to be filled in and what options are available for each field.
##  Basic Usage 
To retrieve a `LabReportTemplate` by identifier, use the `get` method on the model manager:
    ```python
    from canvas_sdk.v1.data.lab import LabReportTemplate
    template = LabReportTemplate.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    ```
To access the fields defined in a template:
    ```python
    from canvas_sdk.v1.data.lab import LabReportTemplate
    template = LabReportTemplate.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    fields = template.fields.all()
    ```
##  Filtering 
Templates can be filtered by any attribute on the models.
###  By active status 
    ```python
    from canvas_sdk.v1.data.lab import LabReportTemplate
    # Get all active templates
    active_templates = LabReportTemplate.objects.active()
    # Get inactive templates
    inactive_templates = LabReportTemplate.objects.inactive()
    ```
###  By type 
    ```python
    from canvas_sdk.v1.data.lab import LabReportTemplate
    # Get custom (user-created) templates
    custom = LabReportTemplate.objects.custom()
    # Get built-in (system) templates
    builtin = LabReportTemplate.objects.builtin()
    # Get point-of-care test templates
    poc = LabReportTemplate.objects.point_of_care()
    ```
###  By search 
    ```python
    from canvas_sdk.v1.data.lab import LabReportTemplate
    results = LabReportTemplate.objects.search("glucose")
    ```
##  Attributes 
###  LabReportTemplate 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
name| String  
code| String  
code_system| String  
search_keywords| String  
active| Boolean  
custom| Boolean  
poc| Boolean  
fields| LabReportTemplateField[]  
###  LabReportTemplateField 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
report_template| LabReportTemplate  
sequence| Integer  
code| String  
code_system| String  
label| String  
units| String  
type| FieldType  
required| Boolean  
options| LabReportTemplateFieldOption[]  
###  LabReportTemplateFieldOption 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
field| LabReportTemplateField  
label| String  
key| String  
##  Enumeration types 
###  FieldType 
Value| Label  
---|---  
float| Float  
select| Select  
text| Text  
checkbox| Checkbox  
radio| Radio  
array| Array  
labReport| Lab Report  
remoteFields| Remote Fields  
autocomplete| Autocomplete  
date| Date  

---

# Labs

Source: https://docs.canvasmedical.com/sdk/data-labs/

##  Introduction 
The Canvas SDK provides comprehensive models for working with laboratory data throughout the entire lab workflow—from ordering tests to reviewing results. The primary models include:
  - **`LabOrder`** : Represents a lab order placed for a patient, including order details, transmission type, and associated tests
  - **`LabTest`** : Individual tests within a lab order, tracking status from creation through processing
  - **`LabReport`** : Contains the results returned from the lab, including all values and associated metadata
  - **`LabReportRemark`** : Report-level remarks from lab personnel, accessible via `LabReport.remarks`
  - **`LabValue`** : Individual test results within a lab report, including values, units, and reference ranges
  - **`LabReview`** : Tracks the clinical review process for lab results, including provider comments and patient communication
  - **`DiagnosticReport`** : The `DiagnosticReport` linked to a `LabReport`, accessible via `LabReport.diagnostic_reports`
##  Basic Usage 
To retrieve a `LabReport` model by id, use the `objects.get` method on the model. For example:
    ```python
    from canvas_sdk.v1.data.lab import LabReport
    lab_report = LabReport.objects.get(id="bcd287b7-8b04-4540-a1ea-6529eb576565")
    ```
##  Filtering 
To retrieve the `LabValue` instances that are associated with the `LabReport`, you can either call the `values` on the `LabReport` instance:
    ```python
    from canvas_sdk.v1.data.lab import LabReport
    lab_report = LabReport.objects.get(id="bcd287b7-8b04-4540-a1ea-6529eb576565")
    lab_values = lab_report.values.all()
    ```
Or query the `LabValue` model and pass the `report` argument:
    ```python
    from canvas_sdk.v1.data.lab import LabReport, LabValue
    lab_report = LabReport.objects.get(id="bcd287b7-8b04-4540-a1ea-6529eb576565")
    lab_values = LabValue.objects.filter(lab_report=lab_report)
    ```
Additionally, codings for lab values can be attained by querying the `LabValueCoding` model. To retrieve the codings associated with a `LabValue`, you can call `codings` on the `LabValue` instance:
    ```python
    from logger import log
    from canvas_sdk.v1.data.lab import LabReport, LabValue
    lab_report = LabReport.objects.get(id="bcd287b7-8b04-4540-a1ea-6529eb576565")
    lab_values = LabValue.objects.filter(lab_report=lab_report)
    for value in lab_values:
        log.info(value.codings.all())
    ```
Or query the `LabValueCoding` model directly:
    ```python
    from logger import log
    from canvas_sdk.v1.data.lab import LabReport, LabValue, LabValueCoding
    lab_report = LabReport.objects.get(id="bcd287b7-8b04-4540-a1ea-6529eb576565")
    lab_values = LabValue.objects.filter(lab_report=lab_report)
    for value in lab_values:
        lab_value_codings = LabValueCoding.objects.filter(value=value)
        log.info(lab_value_codings)
    ```
###  Ordered vs. result tests 
A `LabReport` references two kinds of `LabTest` rows, and `LabReport` exposes each as its own property:
  - **`ordered_tests`** : `LabTest` rows created when a `LabOrder` is placed. These represent the tests that were requested and are not associated with any `LabValue` records.
  - **`result_tests`** : `LabTest` rows created for the results themselves. For FHIR `DiagnosticReport` and Health Gorilla ingested reports, `LabValue` records are attached to these tests.
    ```python
    from canvas_sdk.v1.data.lab import LabReport
    lab_report = LabReport.objects.get(id="bcd287b7-8b04-4540-a1ea-6529eb576565")
    for test in lab_report.ordered_tests:
        print(f"Ordered: {test.ontology_test_name}")
    for test in lab_report.result_tests:
        print(f"Result: {test.ontology_test_name}")
        for value in test.values.all():
            print(f"  {value.value} {value.units}")
    ```
When iterating many reports at once, the `LabReport` queryset exposes `with_result_tests_and_values()` to prefetch each report's result tests (with their values) and the report's full value list in bulk:
    ```python
    from canvas_sdk.v1.data.lab import LabReport
    reports = (
        LabReport.objects
        .filter(patient__id="patient-id")
        .with_result_tests_and_values()
    )
    ```
To query all lab reports for a particular patient, the `patient` argument can be used:
    ```python
    from logger import log
    from canvas_sdk.v1.data.lab import LabReport
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="6cbc40b408294a5f9b41f57ba1b2b487")
    lab_report = LabReport.objects.filter(patient=patient)
    ```
##  Example 
The following plugin code will run every time a new Lab Report is created and log the patient it is for, along with the values and codings from the report's results:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    from canvas_sdk.v1.data.lab import LabReport
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.LAB_REPORT_CREATED)
        def compute(self):
            lab_report = LabReport.objects.select_related("patient").get(id=self.target)
            if lab_report.patient:
                log.info(f"{lab_report.patient.first_name} {lab_report.patient.last_name}")
            for value in lab_report.values.all():
                log.info(f"{value.value} {value.units}")
                for coding in value.codings.all():
                    log.info(coding.system)
                    log.info(coding.name)
                    log.info(coding.code)
            return []
    ```
For complete field documentation on all lab models, see the Attributes section below.
###  Working with Lab Orders and Tests 
You can also work with lab orders and their associated tests. Here's an example of querying a lab order and checking the status of its tests:
    ```python
    from canvas_sdk.v1.data.lab import LabOrder, LabTest
    # Get a lab order by ID
    lab_order = LabOrder.objects.get(id="abc123...")
    # Access all tests in the order
    for test in lab_order.tests.all():
        print(f"Test: {test.ontology_test_name}")
        print(f"Status: {test.status}")
        print(f"Code: {test.ontology_test_code}")
        # Check if results have been received
        if test.report:
            print(f"Report available with {test.report.values.count()} values")
    ```
###  Navigating Between Lab Orders and Reports 
Lab orders and lab reports are connected through the `LabTest` model. Here's how to navigate between them:
####  Getting the LabOrder from a LabReport 
    ```python
    from canvas_sdk.v1.data.lab import LabReport
    # Get a lab report
    lab_report = LabReport.objects.get(id="report-id")
    # Direct access to all orders via the reverse many-to-many relationship
    for lab_order in lab_report.laborder_set.all():
        print(f"Order ID: {lab_order.id}")
        print(f"Ordered by: {lab_order.ordering_provider.full_name if lab_order.ordering_provider else 'N/A'}")
        print(f"Date ordered: {lab_order.date_ordered}")
    # Alternatively, access the order through the tests
    for test in lab_report.tests.all():
        lab_order = test.order
        print(f"Order ID: {lab_order.id}")
        break  # Usually all tests in a report share the same order
    ```
####  Getting LabReports from a LabOrder 
    ```python
    from canvas_sdk.v1.data.lab import LabOrder
    # Get a lab order
    lab_order = LabOrder.objects.get(id="order-id")
    # Direct access to all reports via the many-to-many relationship
    for report in lab_order.reports.all():
        print(f"Report ID: {report.id}")
        print(f"Date performed: {report.date_performed}")
        print(f"Number of values: {report.values.count()}")
    # Alternatively, access reports through the tests if you need test-level details
    for test in lab_order.tests.all():
        if test.report:
            print(f"Test: {test.ontology_test_name}")
            print(f"Report ID: {test.report.id}")
    ```
###  Working with Diagnostic Reports 
A `LabReport` may be linked to one or more `DiagnosticReport` records. The `DiagnosticReport` model exposes its `id`, `status`, the `subject` (Patient), and the `lab` foreign key back to the originating `LabReport`.
####  Getting the DiagnosticReport(s) from a LabReport 
    ```python
    from canvas_sdk.v1.data.lab import LabReport
    lab_report = LabReport.objects.get(id="report-id")
    for diagnostic_report in lab_report.diagnostic_reports.all():
        print(f"DiagnosticReport ID: {diagnostic_report.id}")
        print(f"Status: {diagnostic_report.status}")
    ```
####  Following a DiagnosticReport back to its LabReport 
    ```python
    from canvas_sdk.v1.data.diagnostic_report import DiagnosticReport
    diagnostic_report = DiagnosticReport.objects.get(id="diagnostic-report-id")
    # Follow the `lab` foreign key back to the originating LabReport
    lab_report = diagnostic_report.lab
    if lab_report:
        print(f"LabReport ID: {lab_report.id}")
    ```
####  Filtering DiagnosticReports by patient 
    ```python
    from canvas_sdk.v1.data.diagnostic_report import DiagnosticReport
    diagnostic_reports = DiagnosticReport.objects.for_patient("patient-id")
    ```
####  Reconciling with FHIR 
A `DiagnosticReport`'s `id` is the same id used by the FHIR API, so you can start from a `LabReport`, grab its `DiagnosticReport`, and use the FHIR client to read the corresponding FHIR [DiagnosticReport](/api/diagnosticreport/) resource:
    ```python
    from canvas_sdk.clients.canvas_fhir import CanvasFhir
    from canvas_sdk.v1.data.lab import LabReport
    lab_report = LabReport.objects.get(id="report-id")
    diagnostic_report = lab_report.diagnostic_reports.first()
    # Declare these secrets in the CANVAS_MANIFEST.json and set the values on the
    # plugin configuration page.
    client = CanvasFhir(
        self.secrets["CANVAS_FHIR_CLIENT_ID"],
        self.secrets["CANVAS_FHIR_CLIENT_SECRET"],
    )
    # Use the DiagnosticReport's id to read the corresponding FHIR DiagnosticReport resource.
    fhir_diagnostic_report = client.read("DiagnosticReport", str(diagnostic_report.id))
    ```
###  Working with Lab Reviews 
Lab reviews track the clinical review process for lab results, including provider comments and patient communication. Here's how to work with the LabReport and LabReview relationship:
####  Accessing the Review from a LabReport 
    ```python
    from canvas_sdk.v1.data.lab import LabReport
    # Get a lab report
    lab_report = LabReport.objects.get(id="report-id")
    # Check if the report has been reviewed
    if lab_report.review:
        lab_review = lab_report.review
        print(f"Review status: {lab_review.status}")
        print(f"Internal comment: {lab_review.internal_comment}")
        print(f"Message to patient: {lab_review.message_to_patient}")
        # Access the provider who reviewed it
        if lab_review.originator:
            print(f"Reviewed by: {lab_review.originator.full_name}")
    else:
        print("Report has not been reviewed yet")
    ```
####  Accessing Reports from a LabReview 
    ```python
    from canvas_sdk.v1.data.lab import LabReview
    # Get a lab review
    lab_review = LabReview.objects.get(id="review-id")
    # Access all reports in this review batch
    for report in lab_review.reports.all():
        print(f"Report ID: {report.id}")
        print(f"Date performed: {report.date_performed}")
        print(f"Number of values: {report.values.count()}")
        # Check if this report requires signature
        if report.requires_signature:
            print("  ⚠️  Requires provider signature")
    ```
####  Finding Unreviewed Lab Reports 
    ```python
    from canvas_sdk.v1.data.lab import LabReport
    from canvas_sdk.v1.data.patient import Patient
    # Get all unreviewed lab reports for a patient
    patient = Patient.objects.get(id="patient-id")
    unreviewed_reports = LabReport.objects.filter(
        patient=patient,
        review__isnull=True,
        deleted=False
    )
    print(f"Found {unreviewed_reports.count()} unreviewed reports")
    for report in unreviewed_reports:
        print(f"Report from {report.date_performed} - {report.values.count()} values")
    ```
####  Finding Lab Reports Assigned to a Reviewer 
A lab report is assigned for review to staff members or to a team. `reviewers` holds the assigned staff members, and `team` holds the assigned team, or `None` when no team is assigned.
    ```python
    from canvas_sdk.v1.data import LabReport, Staff
    lab_report = LabReport.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    # The staff members and the team the lab report is assigned to
    reviewers = lab_report.reviewers.all()
    team = lab_report.team
    # Every lab report assigned to this staff member
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    assigned = LabReport.objects.filter(reviewers__id=staff.id)
    ```
###  Filtering Lab Results by Abnormal Values 
A common use case is to alert a care team when an abnormal result arrives. Listen for [`LAB_REPORT_CREATED`](/sdk/events/#labs) (and the other [Lab events](/sdk/events/#labs) or [Imaging Report events](/sdk/events/#imaging-reports)) to react to new results, then inspect each `LabValue`'s `abnormal_flag` field — per Canvas, a value is flagged abnormal when `abnormal_flag` is set (non-null and non-empty). A common use case is to identify abnormal lab values that may require clinical attention:
    ```python
    from canvas_sdk.v1.data.lab import LabReport, LabValue
    from canvas_sdk.v1.data.patient import Patient
    # Get all lab reports for a patient
    patient = Patient.objects.get(id="patient-id")
    lab_reports = LabReport.objects.filter(patient=patient)
    # Find all abnormal values
    for report in lab_reports:
        abnormal_values = report.values.filter(abnormal_flag__isnull=False).exclude(abnormal_flag="")
        if abnormal_values.exists():
            print(f"Report from {report.date_performed}:")
            for value in abnormal_values:
                for coding in value.codings.all():
                    print(f"  {coding.name}: {value.value} {value.units} (Flag: {value.abnormal_flag})")
    ```
###  Committed records 
The `committed` method returns `LabReport`, `LabReview`, `LabOrder`, and `LabOrderReason` records that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.lab import LabReport, LabReview, LabOrder, LabOrderReason
    committed_reports = LabReport.objects.committed()
    committed_reviews = LabReview.objects.committed()
    committed_orders = LabOrder.objects.committed()
    committed_order_reasons = LabOrderReason.objects.committed()
    ```
###  POC (point-of-care) Lab Test results 
A [POC Lab Test](/sdk/commands/#poclabtest) command records its results as a `LabReport`. The command's `Command` record, with a `schema_key` of `pocLabTest`, points at that report through `anchor_object`, so you can move from the command to its results:
    ```python
    from canvas_sdk.v1.data.command import Command
    command = Command.objects.get(id="c1b5a4d2-7e3f-4a8b-9c6d-2f1e0a9b8c7d")
    lab_report = command.anchor_object
    ```
To react to new POC Lab Test results, listen for the [POC Lab Test command events](/sdk/events/#poc-lab-test-command), such as `POC_LAB_TEST_COMMAND__POST_COMMIT`.
##  The document reference 
`LabReport` carries the report's values and review state, not a file. When the report is reviewed, Canvas renders it to a PDF and stores it on a [DocumentReference](/sdk/data-document-reference/#the-related-object) pointing back at the report.
To find it, resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` — never hardcode the per-environment `dbid` — and match `object_id` against the report's `dbid`:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference, LabReport
    report = LabReport.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    content_type = ContentType.objects.filter(app_label="api", model="labreport").first()
    document = DocumentReference.objects.filter(
        content_type=content_type, object_id=report.dbid
    ).first()
    url = document.document_url if document else None
    ```
> **Info:** `object_id` holds the related record's integer `dbid`, not its UUID `id`. A report that has not been reviewed yet has no document reference, so handle `None`.
##  Attributes 
###  LabReport 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
review_mode| [DocumentReviewMode](/sdk/data-enumeration-types/#documentreviewmode)  
junked| Boolean  
requires_signature| Boolean  
assigned_date| DateTime  
assigned_by| [CanvasUser](/sdk/data-canvasuser)  
reviewers| [Staff](/sdk/data-staff/#staff)[]  
team| [Team](/sdk/data-team/#team)  
team_assigned_date| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
transmission_type| TransmissionType  
for_test_only| Boolean  
external_id| String  
version| Integer  
requisition_number| String  
review| LabReview  
original_date| DateTime  
date_performed| DateTime  
custom_document_name| String  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
values| LabValue[]  
tests| LabTest[]  
ordered_tests| LabTest[]  
result_tests| LabTest[]  
remarks| LabReportRemark[]  
diagnostic_reports| DiagnosticReport[]  
laborder_set| LabOrder[]  
###  LabReportRemark 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
report| LabReport  
comment| String  
###  DiagnosticReport 
The `DiagnosticReport` linked to a `LabReport`. The `id` is the DiagnosticReport id.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
status| DiagnosticReportStatus  
subject| [Patient](/sdk/data-patient/#patient)  
lab| LabReport  
###  LabReview 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
internal_comment| String  
message_to_patient| String  
status| String  
note| [Note](/sdk/data-note/#note)  
patient| [Patient](/sdk/data-patient/#patient)  
patient_communication_method| String  
reports| LabReport[]  
###  LabValue 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
report| LabReport  
value| String  
units| String  
abnormal_flag| String  
reference_range| String  
low_threshold| String  
high_threshold| String  
comment| String  
observation_status| String  
test| LabTest  
codings| LabValueCoding[]  
###  LabValueCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
value| LabValue  
code| String  
name| String  
system| String  
###  LabOrder 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
ontology_lab_partner| String  
ordering_provider| [Staff](/sdk/data-staff/#staff)  
comment| String  
requisition_number| String  
is_patient_bill| Boolean  
date_ordered| DateTime  
fasting_status| Boolean  
specimen_collection_type| SpecimenCollectionType  
transmission_type| TransmissionType  
courtesy_copy_type| CourtesyCopyType  
courtesy_copy_number| String  
courtesy_copy_text| String  
parent_order| LabOrder  
healthgorilla_id| String  
manual_processing_status| ManualProcessingStatus  
manual_processing_comment| String  
labcorp_abn_url| URL  
reasons| LabOrderReason[]  
tests| LabTest[]  
reports| LabReport[]  
laborder_set| LabOrder[]  
action_events| [LabOrderActionEvent](/sdk/data-fax/#laborderactionevent)[]  
###  LabOrderReason 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
order| LabOrder  
mode| LabReasonMode  
reason_conditions| LabOrderReasonCondition[]  
###  LabOrderReasonCondition 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
reason| LabOrderReason  
condition| [Condition](/sdk/data-condition)  
###  LabTest 
Represents an individual test within a lab order. Each `LabTest` tracks the lifecycle of a specific test from order creation through processing and result receipt.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
ontology_test_name| String  
ontology_test_code| String  
status| LabTestOrderStatus  
report| LabReport  
specimen_type| String  
specimen_source_code| String  
specimen_source_description| String  
specimen_source_coding_system| String  
order| LabOrder  
aoe_code| String  
procedure_class| String  
values| LabValue[]  
##  Enumeration types 
###  DiagnosticReportStatus 
Value| Label  
---|---  
`REGISTERED`| Registered  
`PARTIAL`| Partial  
`PRELIMINARY`| Preliminary  
`FINAL`| Final  
`AMENDED`| Amended  
`CORRECTED`| Corrected  
`APPENDED`| Appended  
`CANCELLED`| Cancelled  
`ENTERED_IN_ERROR`| Entered-in-error  
`UNKNOWN`| Unknown  
###  TransmissionType 
Value| Label  
---|---  
F| fax  
H| hl7  
M| manual  
###  SpecimenCollectionType 
Value| Label  
---|---  
L| on location  
P| patient service center  
O| other  
###  CourtesyCopyType 
Value| Label  
---|---  
A| account  
F| fax  
P| patient  
###  ManualProcessingStatus 
Value| Label  
---|---  
NEEDS_REVIEW| Needs Review  
IN_PROGRESS| In Progress  
PROCESSED| Processed  
FLAGGED| Flagged  
###  LabReasonMode 
Value| Label  
---|---  
MO| monitor  
IN| investigate  
SF| screen for  
UNK| unknown  
###  LabTestOrderStatus 
Value| Label  
---|---  
NE| new  
SR| staged for requisition  
SE| sending  
SF| sending failed  
PR| processing  
PF| processing failed  
RE| received  
RV| reviewed  
IN| inactive  

---

# LetterActionEvent

Source: https://docs.canvasmedical.com/sdk/data-letter-action-event/

##  Introduction 
The `LetterActionEvent` model represents occurrences of a letter being printed or faxed within Canvas. LetterActionEvents are associated with a [Letter](/sdk/data-letter/).
The other document types that can be faxed have their own action event models with the same fields. See [Fax](/sdk/data-fax/), which also explains how to read [delivery status](/sdk/data-fax/#delivery-status).
##  Basic Usage 
###  Retrieve a specific letter action event 
To get a letter action event by identifier, use the `get` method on the `LetterActionEvent` model manager:
    ```python
    from canvas_sdk.v1.data.letter import LetterActionEvent
    letterActionEvent = LetterActionEvent.objects.get(id="b5a0c1d2-e3f4-5678-9abc-def012345678")
    ```
###  Find a letter action event for a specific letter 
If you have a letter object, you can access its associated letter_action_events using the `letter_action_events` attribute:
    ```python
    from canvas_sdk.v1.data.letter import Letter
    letter = Letter.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    letter_action_events = letter.letter_action_events
    ```
##  Filtering 
LetterActionEvents can be filtered by any attribute that exists on the model.
###  By attribute 
Filtering for letter action events is done with the `filter` method on the `LetterActionEvent` model manager:
    ```python
    from canvas_sdk.v1.data.letter import LetterActionEvent
    # Find all successful deliveries
    delivered_letters = LetterActionEvent.objects.filter(delivered_by_fax=True)
    # Find letter action events with a specific send_fax_id
    letter_action_events = LetterActionEvent.objects.filter(send_fax_id="a1b2c3d4e5f6")
    ```
##  Attributes 
###  LetterActionEvent 
Field Name| Type| Notes  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
event_type| EventType| The type of the event  
send_fax_id| String| The id of the sent fax  
received_by_fax| Boolean| Whether the faxing service accepted the fax  
delivered_by_fax| Boolean| The [delivery outcome](/sdk/data-fax/#delivery-status)  
fax_result_msg| str| The fax result message  
letter| [Letter](/sdk/data-letter/)| The letter this action event is associated with  
originator| [User](/sdk/data-canvasuser/)| The user who printed or faxed the letter (nullable)  
fax| [Fax](/sdk/data-fax/#fax)| The fax record, including the number it was sent to (nullable)  
##  Enumeration types 
###  Event Type 
Value| Label  
---|---  
PRINTED| Printed  
FAXED| Faxed

---

# Letter

Source: https://docs.canvasmedical.com/sdk/data-letter/

##  Introduction 
The `Letter` model represents patient correspondence letters created within Canvas. Letters are associated with a [Note](/sdk/data-note/) and contain rendered content that can be printed or sent to patients.
##  Basic Usage 
###  Retrieve a specific letter 
To get a letter by identifier, use the `get` method on the `Letter` model manager:
    ```python
    from canvas_sdk.v1.data.letter import Letter
    letter = Letter.objects.get(id="b5a0c1d2-e3f4-5678-9abc-def012345678")
    ```
###  Find a letter for a specific note 
If you have a note object, you can access its associated letter using the `letter` attribute:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    letter = note.letter
    ```
###  Find all letters created by a staff member 
If you have a staff object, you can find all letters they created using the `letters` attribute:
    ```python
    from canvas_sdk.v1.data.staff import Staff
    staff = Staff.objects.get(id="a1b2c3d4e5f6")
    staff_letters = staff.letters.all()
    ```
##  Filtering 
Letters can be filtered by any attribute that exists on the model.
###  By attribute 
Filtering for letters is done with the `filter` method on the `Letter` model manager:
    ```python
    from canvas_sdk.v1.data.letter import Letter
    # Find all printed letters
    printed_letters = Letter.objects.filter(printed__isnull=False)
    # Find letters created by a specific staff member
    staff_letters = Letter.objects.filter(staff_id="a1b2c3d4e5f6")
    ```
##  The printed attachments 
`printed_document` holds the letter's attachments, merged into one PDF, not the letter body. Canvas saves it the first time the letter is printed or faxed, and reuses it for later prints and faxes. The `printed_document_url` property returns a presigned S3 URL for that PDF, or `None` when the letter hasn't been printed or faxed. The URL is valid for one hour, so generate it when you need it rather than storing it.
    ```python
    from canvas_sdk.v1.data.letter import Letter
    letter = Letter.objects.get(id="b5a0c1d2-e3f4-5678-9abc-def012345678")
    # Presigned S3 URL to the merged attachments PDF, or None
    attachments_url = letter.printed_document_url
    ```
To read the full letter as it went out, use its document reference.
##  The document reference 
`content` holds the letter's body, not the document that goes out. Canvas renders the letter — including anything attached to it — to a PDF and stores it on a [DocumentReference](/sdk/data-document-reference/#the-related-object) pointing back at the letter.
To read that PDF, resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` — never hardcode the per-environment `dbid` — and match `object_id` against the letter's `dbid`:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference, Letter
    letter = Letter.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    content_type = ContentType.objects.filter(app_label="api", model="letter").first()
    document = DocumentReference.objects.filter(
        content_type=content_type, object_id=letter.dbid
    ).first()
    url = document.document_url if document else None
    ```
> **Info:** `object_id` holds the related record's integer `dbid`, not its UUID `id`. The PDF is rendered after the letter is created rather than with it, so handle `None`.
##  Attributes 
###  Letter 
Field Name| Type| Notes  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
content| String| The rendered letter content  
printed| DateTime| When the letter was printed (null if not printed)  
printed_document| File (S3 key)| The letter's attachments merged into one PDF, saved when the letter is first printed or faxed (null until then)  
printed_document_url| String (computed)| Presigned S3 URL for `printed_document`, or `None` if unset  
note| [Note](/sdk/data-note/)| The note this letter is associated with  
staff| [Staff](/sdk/data-staff/#staff)| The staff member who created the letter (nullable)  
letter_action_events| QuerySet[LetterActionEvent]| Action events (e.g. printed, faxed) recorded for this letter

---

# Medication History

Source: https://docs.canvasmedical.com/sdk/data-medication-history/

##  Introduction 
The `MedicationHistoryMedication` model represents historical medication data for a patient, typically imported from external sources such as health information exchanges or pharmacy systems. The `MedicationHistoryResponse` model tracks responses to medication history requests.
##  Basic usage 
To get a medication history record by identifier, use the `get` method on the `MedicationHistoryMedication` model manager:
    ```python
    from canvas_sdk.v1.data.medication_history import MedicationHistoryMedication
    medication_history = MedicationHistoryMedication.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the medication history for a patient can be accessed with the `medication_history_medications` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    medication_history = patient.medication_history_medications.all()
    ```
##  Codings 
The codings for a medication history record can be accessed with the `codings` attribute on a `MedicationHistoryMedication` object:
    ```python
    from canvas_sdk.v1.data.medication_history import MedicationHistoryMedication
    from logger import log
    medication_history = MedicationHistoryMedication.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in medication_history.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
##  Filtering 
Medication history records can be filtered by any attribute that exists on the model.
Filtering is done with the `filter` method on the `MedicationHistoryMedication` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.medication_history import MedicationHistoryMedication
    medications = MedicationHistoryMedication.objects.filter(dea_schedule="CII")
    ```
###  By date range 
Filter by last fill date or written date:
    ```python
    from canvas_sdk.v1.data.medication_history import MedicationHistoryMedication
    from datetime import datetime
    medications = MedicationHistoryMedication.objects.filter(
        last_fill_date__gte=datetime(2023, 1, 1)
    )
    ```
##  Attributes 
###  MedicationHistoryMedication 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
drug_description| String  
strength_value| String  
strength_form| String  
strength_unit_of_measure| String  
quantity| Float  
quantity_unit_of_measure| String  
quantity_code_list_qualifier| String  
days_supply| Integer  
last_fill_date| DateTime  
written_date| DateTime  
other_date| DateTime  
other_date_qualifier| String  
substitutions| Boolean  
refills_remaining| Integer  
diagnosis_code| String  
diagnosis_qualifier| String  
diagnosis_description| String  
secondary_diagnosis_code| String  
secondary_diagnosis_qualifier| String  
secondary_diagnosis_description| String  
dea_schedule| String  
potency_unit_code| String  
etc_path_id| Array[Integer]  
etc_path_name| Array[String]  
fill_number| Integer  
prescriber_order_number| String  
source_description| String  
source_qualifier| String  
source_payer_id| String  
source_type| String  
note| String  
sig| String  
prior_authorization_status| String  
prior_authorization| String  
pharmacy_name| String  
pharmacy_ncpdp_id| String  
pharmacy_npi| String  
prescriber_business_name| String  
prescriber_first_name| String  
prescriber_last_name| String  
prescriber_npi| String  
prescriber_dea_number| String  
codings| MedicationHistoryMedicationCoding[]  
###  MedicationHistoryMedicationCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
medication| MedicationHistoryMedication  
###  MedicationHistoryResponse 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
staff| [Staff](/sdk/data-staff/#staff)  
message_id| String  
related_to_message_id| String  
status| MedicationHistoryResponseStatus  
reason| String  
reason_code| String  
note| String  
start_date| Date  
end_date| Date  
##  Enumeration types 
###  MedicationHistoryResponseStatus 
Value| Label  
---|---  
approved| approved  
denied| denied  

---

# Medication Statement

Source: https://docs.canvasmedical.com/sdk/data-medication-statement/

##  Introduction 
The `MedicationStatement` model represents a record of a medication statement by a patient from the past.
##  Basic usage 
To get a medication statement by identifier, use the `get` method on the `MedicationStatement` model manager:
    ```python
    from canvas_sdk.v1.data import MedicationStatement
    medication_statement = MedicationStatement.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    ```
If you have a patient object, the medication statements for a patient can be accessed with the `medication_statements` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    medication_statements = patient.medication_statements.all()
    ```
You can also access the referenced medication with the `medication` attribute:
    ```python
    from canvas_sdk.v1.data import MedicationStatement
    medication_statement = MedicationStatement.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    medication = medication_statement.medication
    ```
Or for a given medication, you can access all medication statements:
    ```python
    from canvas_sdk.v1.data import Medication
    medication = Medication.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    medication_statements = medication.medication_statements.all()
    ```
##  Latest sig 
A medication statement's sig is one of the sources a medication's [`latest_sig`](/sdk/data-medication/#latest-sig) draws on, alongside its active prescriptions and change medications. To get the most recent sig for the medication, read `latest_sig` from the referenced medication:
    ```python
    from canvas_sdk.v1.data import MedicationStatement
    medication_statement = MedicationStatement.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    sig = medication_statement.medication.latest_sig
    ```
##  Committed records 
The `committed` method returns medication statements that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import MedicationStatement
    committed_medication_statements = MedicationStatement.objects.committed()
    ```
##  Attributes 
###  MedicationStatement 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
medication| [Medication](/sdk/data-medication)  
indications| [Assessment](/sdk/data-assessment)[]  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
originator| [CanvasUser](/sdk/data-canvasuser)  
created| DateTime  
modified| DateTime  
start_date_original_input| String  
start_date| Date  
end_date_original_input| String  
end_date| Date  
dose_quantity| Number  
dose_form| String  
dose_route| String  
dose_frequency| Number  
dose_frequency_interval| String  
sig_original_input| String  

---

# Medication

Source: https://docs.canvasmedical.com/sdk/data-medication/

##  Introduction 
The `Medication` model represents a record of a medication that is being consumed by a patient, either now, in the past, or in the future. `Medication` records can represent both prescriptions and medication statements for a patient.
##  Basic usage 
To get a medication by identifier, use the `get` method on the `Medication` model manager:
    ```python
    from canvas_sdk.v1.data.medication import Medication
    medication = Medication.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the medications for a patient can be accessed with the `medications` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    medications = patient.medications.all()
    ```
If you have a patient ID, you can get the medications for the patient with the `for_patient` method on the `Medication` model manager:
    ```python
    from canvas_sdk.v1.data.medication import Medication
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    medication = Medication.objects.for_patient(patient_id)
    ```
#  Codings 
The codings for a medication can be accessed with the `codings` attribute on an `Medication` object:
    ```python
    from canvas_sdk.v1.data.medication import Medication
    from logger import log
    medication = Medication.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in medication.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
##  Filtering 
Medications can be filtered by any attribute that exists on the model.
Filtering for medications is done with the `filter` method on the `Medication` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.medication import Medication
    medications = Medication.objects.filter(status="active")
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The `find` method on the model manager is used to perform `ValueSet` filtering:
    ```python
    from canvas_sdk.v1.data.medication import Medication
    from canvas_sdk.value_set.v2022.medication import AdhdMedications
    medications = Medication.objects.find(AdhdMedications)
    ```
##  Latest sig 
The `latest_sig` property returns a medication's most recent sig — its directions for use — as a string. It draws on three sources: the medication's active [prescriptions](/sdk/data-prescription/), its [change medications](/sdk/data-change-medication/) that are not entered in error, and its [medication statements](/sdk/data-medication-statement/). It returns the sig from whichever of those is most recent. Because `latest_sig` is a property computed in Python, it is read from each `Medication` object and is not available to a queryset `.filter()` or `.order_by()`.
When both an active prescription and a change medication exist, the source whose [note](/sdk/data-note/) has the later date of service wins. Otherwise the sig comes from the first source that has one, in this order:
  1. The latest prescription.
  2. The latest change medication.
  3. The latest medication statement.
The latest source is the one with the highest `dbid`. A prescription contributes its `combined_sig` (its sig text, plus a maximum daily dose when one is set); a change medication or medication statement contributes its sig text. When no source has a sig, `latest_sig` returns an empty string.
    ```python
    from canvas_sdk.v1.data.medication import Medication
    medication = Medication.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    sig = medication.latest_sig  # "" when no source has a sig
    ```
###  Sig across many medications 
Reading `latest_sig` on each medication in a queryset issues a separate query per medication for the prescriptions, change medications, and medication statements `latest_sig` inspects. The `with_latest_sig` method prefetches those sources, so `latest_sig` resolves without a per-medication query:
    ```python
    from canvas_sdk.v1.data.medication import Medication
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    medications = Medication.objects.for_patient(patient_id).with_latest_sig()
    for medication in medications:
        sig = medication.latest_sig
    ```
##  Filtering to match the Patient Summary 
The Medications list in the Patient Summary section of the chart is not reproduced by filtering on `status == "active"` alone. Per Canvas, that list applies two exclusion layers before considering status:
  1. Exclude uncommitted and entered-in-error records — a medication must have a non-null `committer` (it was finalized) and a null `entered_in_error` (no one flagged it as erroneous).
  2. Filter by `status` — the list defaults to `status == "active"`; users can toggle to inactive or all.
The `Medication` queryset has both layers built in. `committed()` keeps records with a non-null `committer` and a null `entered_in_error`, and `active()` is `committed()` plus `status == "active"`. To replicate the Patient Summary's active medications:
    ```python
    from canvas_sdk.v1.data.medication import Medication
    active_meds = Medication.objects.for_patient(patient_id).active()
    ```
For every medication the list can show (its "All" toggle, active plus inactive), use `committed()` without the status filter:
    ```python
    from canvas_sdk.v1.data.medication import Medication
    all_visible_meds = Medication.objects.for_patient(patient_id).committed()
    ```
###  How status is computed 
Canvas sets a medication's `status` from its command history; users do not set it directly. A medication is `inactive` when any of the following is true, and `active` otherwise:
  - It has a committed stop medication event that has not been entered in error.
  - Its prescription has a committed cancellation that has not been entered in error.
  - A newer medication in the same chain of commands has replaced it, for example through an adjusted prescription.
  - Its only commands are refill denials.
  - It has no committed commands linked to it, apart from ones entered in error.
Canvas recomputes `status`, `start_date`, and `end_date` whenever a related command is created, committed, or entered in error. Related commands include medication statements, prescriptions, refills, adjustments, stop medication events, prescription cancellations, and eRx refill responses, and a change to a note's date of service triggers it too.
The FHIR API is the exception. Creating a `MedicationStatement` through FHIR writes `status` and the `effectivePeriod` start and end straight onto the `Medication` record without recomputing them, and those values stay until a later command triggers a recomputation.
##  Attributes 
###  Medication 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
patient| [Patient](/sdk/data-patient/#patient)|   
entered_in_error| [CanvasUser](/sdk/data-canvasuser)|   
committer| [CanvasUser](/sdk/data-canvasuser)|   
status| String|   
start_date| Date|   
end_date| Date|   
quantity_qualifier_description| String|   
clinical_quantity_description| String|   
potency_unit_code| String|   
national_drug_code| String|   
erx_quantity| String|   
codings| MedicationCoding[]|   
medication_statements| [MedicationStatement](/sdk/data-medication-statement)[]|   
change_medications| [ChangeMedication](/sdk/data-change-medication)[]|   
stopmedicationevent_set| [StopMedicationEvent](/sdk/data-stop-medication-event)[]|   
prescriptions| [Prescription](/sdk/data-prescription)[]|   
previous_medications| [Prescription](/sdk/data-prescription)[]|   
prescription_change_responses| [PrescriptionChangeResponse](/sdk/data-prescription-change-response/#prescriptionchangeresponse)[]|   
latest_sig| String (computed)| See Latest sig  
###  MedicationCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
medication| Medication  

---

# Message

Source: https://docs.canvasmedical.com/sdk/data-message/

#  Message Models 
The Canvas SDK defines messaging-related data models for sending, receiving, and tracking messages.
##  TransmissionChannel 
A `TextChoices` enum representing the available channels for transmitting messages.
Member| Value| Description  
---|---|---  
`MANUAL`| `manual`| Manual  
`TEXT_MESSAGE`| `sms`| Text Message  
`EMAIL`| `email`| Email  
`NOOP`| `noop`| No-op  
##  Message 
Represents an individual message record.
###  Fields 
Name| Type| Description  
---|---|---  
`id`| `UUID`| Unique identifier for the message.  
`dbid`| `Integer`| Database primary key.  
`created`| `DateTime`| Timestamp when the message was created.  
`modified`| `DateTime`| Timestamp when the message was last modified.  
`content`| `Text`| The body text of the message.  
`sender`| [CanvasUser](/sdk/data-canvasuser)| The user who sent the message. May be null.  
`recipient`| [CanvasUser](/sdk/data-canvasuser)| The user who received the message. May be null.  
`note`| [Note](/sdk/data-note)| Associated note (if any) for contextual linkage. May be null.  
`read`| `DateTime`| Timestamp when the recipient read the message. Null if unread.  
`team`| [Team](/sdk/data-team/#team)| The team the message is assigned to. Null if unassigned. See [Assigning a message to a team](/sdk/effect-messages/#assigning-a-message-to-a-team).  
`transmissions`| QuerySet[MessageTransmission]| The delivery transmissions associated with this message.  
`message`| QuerySet[MessageAttachment]| The file attachments associated with this message.  
##  MessageAttachment 
Represents a file attachment linked to a message.
###  Fields 
Name| Type| Description  
---|---|---  
`id`| `UUID`| Unique identifier for the attachment.  
`dbid`| `Integer`| Database primary key.  
`created`| `DateTime`| When the record was created.  
`modified`| `DateTime`| When the record was last modified.  
`file`| `Text`| Storage path or identifier for the file.  
`content_type`| `String`| MIME type of the attachment.  
`message`| Message| The parent message to which this belongs.  
`file_url`| String (computed)| Presigned S3 URL for accessing the file.  
##  MessageTransmission 
Tracks delivery attempts and status for a message.
###  Fields 
Name| Type| Description  
---|---|---  
`id`| `UUID`| Unique identifier for the transmission record.  
`dbid`| `Integer`| Database primary key.  
`created`| `DateTime`| Timestamp when the transmission was created.  
`modified`| `DateTime`| Timestamp when the transmission was last modified.  
`message`| Message| The message associated with this transmission.  
`delivered`| `DateTime`| When delivery succeeded. Null if not delivered.  
`failed`| `DateTime`| When delivery failed. Null if it has not failed.  
`contact_point_system`| TransmissionChannel| The channel used for delivery.  
`contact_point_value`| `String`| The destination address or identifier (e.g., phone, email).  
`comment`| `Text`| Optional comments or error details.  
`delivered_by`| [Staff](/sdk/data-staff/#staff)| The staff member who processed the delivery. May be null.

---

# Note

Source: https://docs.canvasmedical.com/sdk/data-note/

##  Introduction 
The `Note` model represents clinical notes that appear on a patient's chart. A `Note` can contain multiple [commands](/sdk/data-command).
##  Basic usage 
###  Retrieve a specific note 
To get a note by identifier, use the `get` method on the `Note` model manager:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    ```
###  Find all notes for a patient 
If you have a patient object, the notes for a patient can be found using the `notes` attribute on the `Patient` instance:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="fd2ecd87c26044a6a755287f296dd17f")
    patient_notes = patient.notes.all()
    ```
###  Retrieve the content of commands in a note 
If you have a note object, the [commands](/sdk/data-command) for that note can be found using the `commands` attribute on the `Note` instance:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    note_commands = note.commands.all()
    ```
You can also filter commands by their state or other attributes:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    # Get only committed commands
    committed_commands = note.commands.filter(state="committed")
    # Get commands by schema_key (e.g., prescriptions)
    prescriptions = note.commands.filter(schema_key="prescribe")
    ```
To access the content of a command, use the `data` attribute which contains a JSON object with the command's data:
    ```python
    import json
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    for command in note.commands.all():
        # Get the command type
        command_type = command.schema_key
        # Get the command data as a dictionary
        command_data = command.data
        # Pretty print the command data
        print(f"Command Type: {command_type}")
        print(json.dumps(command_data, indent=2))
    ```
For more information about command types and their data structure, see the [Command](/sdk/data-command/) documentation.
###  Retrieve educational materials for a note 
Educational material shared through the Educational Material command is recorded on the note. If you have a note object, those records can be found using the `education_material` reverse relation:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    educational_materials = note.education_material.all()
    ```
###  Understanding the note body structure 
The `body` of a note is a JSON array that represents the structure and layout of the note. It intermixes text content with references to commands:
    ```python
    import json
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    # The body is an array of objects
    print(json.dumps(note.body, indent=2))
    ```
The body array contains objects of two types:
  1. **Text objects** : Represent free-form text content
         ```json
         {"type": "text", "value": "Patient reports feeling better"}
         ```
  2. **Command objects** : Reference commands with their metadata
         ```json
         {
           "type": "command",
           "value": "reasonForVisit",
           "data": {
             "command_uuid": "691123c4-6c7d-415b-880b-2beefab9f64a"
           }
         }
         ```
`command_uuid` identifies the command and is present on every command object. It matches the `id` of the [Command](/sdk/data-command/) model. A command object on a note that has not yet moved to the [refactored body structure](/release-notes/note-v2-2026-09-15/) can also carry an `id`, holding the integer identifier of the record the command created. A note on the refactored structure never carries one, so read the [Command](/sdk/data-command/) through `command_uuid` and take `anchor_object` from it instead.
####  Querying on the body 
`body` is computed on each access rather than stored in a column, because Canvas assembles it from more than one column. That does not change the value you read, but it does limit which query operations can name it:
Operation| Supported| Notes  
---|---|---  
`Note.objects.filter(body=...)`| Yes| Also `exclude()` and `get()`, and lookups nested inside a `Q` object  
`Note.objects.only("body")`| Yes| Loads every column the property reads, so building a body costs no further queries  
`Note.objects.defer("body")`| Yes| Defers all of them  
`Note.objects.values("body")`, `values_list("body")`| No| Raises a `FieldError` telling you to use `only("body")`. No single column holds the value to return  
`Note.objects.order_by("body")`| No| Raises a `FieldError`  
`body` named through a relation| No| For example `Appointment.objects.defer("note__body")` or `filter(note__body=...)`. Query `Note` itself instead  
> **Warning:** Naming `body` through a relation stopped working in the [September 8, 2026 release](/release-notes/1-348-0/). A queryset on another model that defers or filters `note__body` now raises an error. If you were deferring it to keep a large body out of a joined scan, query the notes you need separately with `Note.objects.defer("body")`.
A `body` filter reads the column holding that note's body, and the two columns hold different shapes: a legacy note holds an ordered list of lines, while a note on the refactored structure holds an object keyed by line identifier. A filter written against one shape matches no notes on the other, and returns no rows instead of raising.
So read the body from a note you already have, or filter notes by it, rather than trying to select it as a value:
    ```python
    from canvas_sdk.v1.data.note import Note
    # Load only the columns the body needs.
    notes = Note.objects.only("body").filter(patient__id="b80b1cdc2e6a4aca90ccebc02e683f35")
    for note in notes:
        print(note.body)
    ```
####  Reading a note's commands 
To work with the commands in a note, use the note's `commands` relation rather than walking `body`. It returns the note's [Command](/sdk/data-command/) records in a single query, the same way for every note:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    for command in note.commands.all():
        print(f"Command type: {command.schema_key}")
        print(f"Command data: {command.data}")
    ```
`commands` includes commands that were entered in error; leave them out with `note.commands.exclude(state="entered_in_error")`. It never includes [Private Notes commands](/sdk/data-command/#introduction), which only their author can see. Its results are not in the order the commands appear in the note. When order matters, take the order from `body`, whose command lines carry a `command_uuid` matching each command's `id`, and still load the commands in one query:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    commands = {str(command.id): command for command in note.commands.all()}
    commands_in_order = [
        commands[line["data"]["command_uuid"]]
        for line in note.body
        if line.get("type") == "command" and line["data"]["command_uuid"] in commands
    ]
    ```
###  Fetch command details from a command lifecycle event 
When a command lifecycle event such as `LAB_ORDER_COMMAND__POST_COMMIT` fires, `self.target` contains the command's `id`. Use that ID to load the [`Command`](/sdk/data-command/) data record and read its `data` JSON — either to act on it inside the listener, or to expose it through a [`SimpleAPIRoute`](/sdk/handlers-simple-api-http/#simpleapiroute) endpoint your application can query later by command ID:
    ```python
    import json
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    from canvas_sdk.v1.data.command import Command
    class CommandAPI(SimpleAPIRoute):
        PATH = "/routes/commands/<id>"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            ...
        def get(self) -> list[Response | Effect]:
            command_id = self.request.path_params["id"]
            command = Command.objects.get(id=command_id)
            return [
                JSONResponse(json.dumps(command.data), status_code=HTTPStatus.OK)
            ]
    ```
Your application would then GET `https://<your-instance>.canvasmedical.com/plugin-io/api/<plugin_name>/routes/commands/<id>`.
###  Retrieve the audit history for a note 
The audit history for a note can be found using the [`NoteStateChangeEvent`](/sdk/data-note/#notestatechangeevent) model. You can access this model directly or through the `state_history` relation on the note object.
    ```python
    from canvas_sdk.v1.data.note import Note, NoteStateChangeEvent
    note = Note.objects.first()
    # Use the state_history relation
    option_1 = note.state_history.all()
    # Use the note object to filter the QuerySet
    option_2 = NoteStateChangeEvent.objects.filter(note=note)
    # Use the note's UUID to filter the QuerySet, which joins to the note table
    # where the note's dbid column is equal to the note_id column of the note
    # state change event and the note's id column is equal to the note's UUID.
    option_3 = NoteStateChangeEvent.objects.filter(note__id=note.id)
    # Use the note's auto-increment database id to filter the QuerySet by the
    # foreign key column without joining to the notes table.
    option_4 = NoteStateChangeEvent.objects.filter(note_id=note.dbid)
    ```
In the above code sample, options 1, 2, and 4 produce identical SQL queries.
###  Determine if a note is locked 
To see if a note is presently locked, you can use the [`CurrentNoteStateEvent`](/sdk/data-note/#currentnotestateevent) model to check if the current note state is 'Locked'. (See: [NoteState](/sdk/data-note/#notestates) for an explanation of the different note states you might encounter)
    ```python
    from canvas_sdk.v1.data.note import Note, CurrentNoteStateEvent, NoteStates
    note = Note.objects.first()
    # You can retrieve the CurrentNoteStateEvent record for the note and check its
    # state attribute.
    if CurrentNoteStateEvent.objects.get(note=note).state == NoteStates.LOCKED:
        # This note is locked!
        pass
    # You can skip retrieving the record by just checking if a
    # CurrentNoteStateEvent record exists for that note with the state 'Locked'.
    if CurrentNoteStateEvent.objects.filter(note=note, state=NoteStates.LOCKED).exists():
        # This note is locked!
        pass
    ```
###  Retrieve the PDF of a locked or signed note 
Finalizing a note captures it as a PDF showing the note at that moment. A note type that does not require a signature is captured when the note is locked, and a note type with `is_sig_required` set is captured when the note is signed. The file is stored on a [DocumentReference](/sdk/data-document-reference/#the-related-object) pointing back at the [NoteStateChangeEvent](/sdk/data-note/#notestatechangeevent) that recorded the lock or signature, so you reach it through the note's state history rather than from the note itself.
> **Info:** Only notes whose note type has a [category](/sdk/data-note/#notetypecategories) of `ENCOUNTER`, `INPATIENT`, or `REVIEW` are captured this way; notes in any other category have no PDF. A note can be finalized more than once. Each time captures its own PDF and Canvas supersedes the earlier ones, so filter on `CURRENT` for the version that is in force, or drop the status filter to see every captured version.
####  Look up a note's PDF 
Resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` rather than hardcoding the per-environment `dbid`, and match `object_id` against the `dbid` of the note's lock and signature events:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference, DocumentReferenceStatus
    from canvas_sdk.v1.data.note import Note, NoteStates
    note = Note.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    finalized_events = note.state_history.filter(state__in=[NoteStates.LOCKED, NoteStates.SIGNED])
    content_type = ContentType.objects.filter(
        app_label="api", model="notestatechangeevent"
    ).first()
    document = DocumentReference.objects.filter(
        content_type=content_type,
        object_id__in=[event.dbid for event in finalized_events],
        status=DocumentReferenceStatus.CURRENT,
    ).first()
    url = document.document_url if document else None
    ```
####  React when a PDF is captured 
The PDF is generated in the background after the note is locked or signed, so it does not exist yet when the state change itself fires. Listen for [`DOCUMENT_REFERENCE_CREATED`](/sdk/events/#document-references) instead. Canvas creates the note's DocumentReference once the PDF is ready, with `related_object` already pointing at the lock or signature event, so `document_url` can be read straight away:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import DocumentReference
    from canvas_sdk.v1.data.note import NoteStateChangeEvent
    from logger import log
    class NotePdfCaptured(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.DOCUMENT_REFERENCE_CREATED)
        def compute(self):
            document = DocumentReference.objects.get(id=self.event.target.id)
            state_change = document.related_object
            if not isinstance(state_change, NoteStateChangeEvent):
                return []  # a document reference that is not a note PDF
            log.info(f"Note {state_change.note.id} PDF: {document.document_url}")
            return []
    ```
`document_url` is a presigned link that expires after an hour. To export the PDF to an external system, either fetch the file within that window, or send only the note ID and let your application request a fresh link later through a [SimpleAPI](/sdk/handlers-simple-api-http/) endpoint you stand up in Canvas.
###  Determine if a note is signed 
For note types where `is_sig_required` is `True`, the terminal state is `SGN` (Signed) rather than `LKD` (Locked). To check whether a note is currently signed, retrieve its [`CurrentNoteStateEvent`](/sdk/data-note/#currentnotestateevent) and compare against `NoteStates.SIGNED`:
    ```python
    from canvas_sdk.v1.data.note import Note, CurrentNoteStateEvent, NoteStates
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    current_state = CurrentNoteStateEvent.objects.filter(note=note).first()
    is_signed = current_state is not None and current_state.state == NoteStates.SIGNED
    ```
Because a note can be signed, amended, and re-signed, the full state history lives in [`NoteStateChangeEvent`](/sdk/data-note/#notestatechangeevent). To get the signer and the timestamp of the most recent signature, query for the latest `SGN` event and read its `originator` (the [`CanvasUser`](/sdk/data-canvasuser) who signed) and `created` timestamp:
    ```python
    from canvas_sdk.v1.data.note import NoteStateChangeEvent, NoteStates
    # `note` is the Note from the previous example
    sign_event = NoteStateChangeEvent.objects.filter(
        note=note,
        state=NoteStates.SIGNED,
    ).order_by("-created").first()
    if sign_event:
        signed_at = sign_event.created
        signed_by = sign_event.originator  # CanvasUser who signed
    ```
> **Info:** The PDF reached here through `DocumentReference` (`document_url`) is one of the consumer-read copies described under [NoteStateChangeEvent](/sdk/data-note/#notestatechangeevent). On an instance with the exclusion setting enabled, the PDF omits entered-in-error commands — see that section.
###  Find all open notes 
You can find all open notes by retrieving the note records with a current state which indicates it can be edited. (See list below)
    ```python
    from canvas_sdk.v1.data.note import Note, CurrentNoteStateEvent, NoteStates
    open_note_states = [
        NoteStates.NEW,
        NoteStates.PUSHED,
        NoteStates.CONVERTED,
        NoteStates.UNLOCKED,
        NoteStates.RESTORED,
        NoteStates.UNDELETED,
    ]
    # This will execute one query per CurrentNoteStateEvent object returned
    open_notes_via_list_comprehension = [event.note for event in CurrentNoteStateEvent.objects.filter(state__in=open_note_states)]
    # This will always execute two queries: one to find the note ids of open
    # notes, and a second query to fetch the note records by the ids returned in the
    # first query
    open_note_ids = CurrentNoteStateEvent.objects.filter(state__in=open_note_states).values_list('note_id', flat=True)
    open_notes_via_multiple_queries = Note.objects.filter(dbid__in=open_note_ids)
    ```
###  Get the current state of a given note 
To get a note's current state, retrieve its [`CurrentNoteStateEvent`](/sdk/data-note/#currentnotestateevent) and check the `state` attribute. If you are trying to assess if the current note state represents that note as being editable, you can call the `editable()` method on the `CurrentNoteStateEvent` object.
    ```python
    from canvas_sdk.v1.data.note import Note, CurrentNoteStateEvent
    note = Note.objects.first()
    current_note_state = CurrentNoteStateEvent.objects.get(note=note).state
    is_editable = current_note_state.editable()
    ```
###  Get the current claim of a given note 
You can retrieve the current claim using the method `get_claim()` presented in the Note object.
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.first()
    claim = note.get_claim()
    ```
###  Get the NoteType of a given note 
A note's type is available through its `note_type_version` attribute, which returns the related NoteType object:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    # Get the note type name (e.g., "Office Visit")
    note_type_name = note.note_type_version.name
    # Access other note type attributes
    note_type_display = note.note_type_version.display
    note_type_code = note.note_type_version.code
    note_type_system = note.note_type_version.system
    ```
##  Filtering 
###  By attribute 
Notes can also be filtered by attribute. For example, to get all notes for a patient where the `datetime_of_service` is after a certain date, the following code can be used:
    ```python
    import arrow
    from canvas_sdk.v1.data.note import Note
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="fd2ecd87c26044a6a755287f296dd17f")
    recent_notes = Note.objects.filter(
        patient=patient,
        datetime_of_service__gte=arrow.now().shift(weeks=-3).datetime
    )
    ```
The `NoteType` model can also be used to find notes by type.
    ```python
    from canvas_sdk.v1.data.note import Note
    from canvas_sdk.v1.data.note import NoteType
    from canvas_sdk.v1.data.patient import Patient
    note_type = NoteType.objects.get(name="Office visit")
    patient = Patient.objects.get(id="fd2ecd87c26044a6a755287f296dd17f")
    patient_office_visits = Note.objects.filter(patient=patient, note_type_version=note_type)
    ```
##  Attributes 
###  Note 
Field Name| Type| Notes  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
patient| [Patient](/sdk/data-patient/#patient)|   
note_type_version| NoteType|   
title| String|   
body| JSON (computed)| Array of objects representing the note structure. Each object has a `type` (either `"text"` or `"command"`) and a `value`. Command objects also carry a `data` field holding `command_uuid` (matching the Command `id`); older notes may additionally include an integer `id`. See Understanding the note body structure.  
originator| [CanvasUser](/sdk/data-canvasuser)|   
provider| [Staff](/sdk/data-staff/#staff)|   
supervising_provider| [Staff](/sdk/data-staff/#staff)| The note's supervising provider, if one has been set  
last_modified_by_staff| [Staff](/sdk/data-staff/#staff)| The staff member who last modified the note  
checksum| String|   
billing_note| String|   
related_data| JSON| Can contain one key, `roomNumber`, if the Note is an inpatient stay.  
datetime_of_service| DateTime|   
place_of_service| String|   
encounter| [Encounter](/sdk/data-encounter)|   
location| [PracticeLocation](/sdk/data-practicelocation/#practicelocation)| The practice location associated with the note  
commands| QuerySet[[Command](/sdk/data-command)]| All commands associated with this note  
clipboards| QuerySet[[Clipboard](/sdk/data-clipboard/#clipboard)]| All clipboard commands recorded on this note  
custom_commands| QuerySet[[CustomCommand](/sdk/data-custom-command/#customcommand)]| All custom commands recorded on this note  
note_tasks| QuerySet[[NoteTask](/sdk/data-task)]| All tasks associated with this note  
metadata| QuerySet[NoteMetadata]| All metadata key-value pairs associated with this note  
lab_reviews| QuerySet[[LabReview](/sdk/data-labs/#labreview)]| All lab reviews associated with this note  
imaging_reviews| QuerySet[[ImagingReview](/sdk/data-imaging/#imagingreview)]| All imaging reviews associated with this note  
referral_reviews| QuerySet[[ReferralReview](/sdk/data-referral/#referralreview)]| All referral reviews associated with this note  
chart_section_reviews| QuerySet[[ChartSectionReview](/sdk/data-chart-section-review/#chartsectionreview)]| All chart section reviews associated with this note  
visual_exam_findings| QuerySet[[VisualExamFinding](/sdk/data-visual-exam-finding/#visualexamfinding)]| All visual exam findings associated with this note  
state_history| QuerySet[NoteStateChangeEvent]| The note's state-change audit history  
action_events| QuerySet[[NoteActionEvent](/sdk/data-fax/#noteactionevent)]| Faxes of this note, with their [delivery status](/sdk/data-fax/#delivery-status)  
current_state| CurrentNoteStateEvent| The note's current state event  
assessments| QuerySet[[Assessment](/sdk/data-assessment/#assessment)]| All assessments associated with this note  
goals| QuerySet[[Goal](/sdk/data-goal/#goal)]| All goals associated with this note  
updategoals| QuerySet[[UpdateGoal](/sdk/data-goal/#updategoal)]| All goal updates and closures recorded on this note  
instructions| QuerySet[[Instruction](/sdk/data-instruction/#instruction)]| All instructions associated with this note  
immunizations| QuerySet[[Immunization](/sdk/data-immunization/#immunization)]| All immunizations associated with this note  
claims| QuerySet[[Claim](/sdk/data-claim/#claim)]| All claims associated with this note (see the `get_claim()` method)  
letter| [Letter](/sdk/data-letter/#letter)| The letter associated with this note, if any  
referral_set| QuerySet[[Referral](/sdk/data-referral/#referral)]| All referrals associated with this note  
laborder_set| QuerySet[[LabOrder](/sdk/data-labs/#laborder)]| All lab orders associated with this note  
appointment_set| QuerySet[[Appointment](/sdk/data-appointment/#appointment)]| All appointments associated with this note  
education_material| QuerySet[[EducationalMaterial](/sdk/data-educational-material/#educationalmaterial)]| All educational materials recorded on this note  
procedures| QuerySet[[Procedure](/sdk/data-procedure/#procedure)]| All procedures recorded on this note  
family_histories| QuerySet[[FamilyHistory](/sdk/data-family-history/#familyhistory)]| All family history records recorded on this note  
plans| QuerySet[[Plan](/sdk/data-plan/#plan)]| All plans recorded on this note  
dme_orders| QuerySet[[DmeOrder](/sdk/data-dme/#dmeorder)]| All Order DME commands signed on this note  
follow_ups| QuerySet[[FollowUp](/sdk/data-follow-up/#followup)]| All follow-ups recorded on this note  
reasons_for_visit| QuerySet[[ReasonForVisit](/sdk/data-reason-for-visit/#reasonforvisit)]| All reasons for visit recorded on this note  
assessed_coding_gaps| QuerySet[[AssessCodingGapEvent](/sdk/data-coding-gap-event/#assesscodinggapevent)]| All coding gaps assessed on this note  
assessed_detected_issues| QuerySet[[ValidateCodingGapEvent](/sdk/data-coding-gap-event/#validatecodinggapevent)]| All coding gaps validated on this note  
created_detected_issues| QuerySet[[CreateCodingGapEvent](/sdk/data-coding-gap-event/#createcodinggapevent)]| All coding gaps created on this note  
deferred_detected_issues| QuerySet[[DeferCodingGapEvent](/sdk/data-coding-gap-event/#defercodinggapevent)]| All coding gaps deferred on this note  
removed_allergies| QuerySet[[RemoveAllergyEvent](/sdk/data-remove-allergy-event/#removeallergyevent)]| All allergies removed on this note  
removed_past_medical_history| QuerySet[[RemovePastMedicalHistoryEvent](/sdk/data-remove-past-medical-history-event/#removepastmedicalhistoryevent)]| All past medical history entries removed on this note  
resolved_conditions| QuerySet[[ResolveConditionEvent](/sdk/data-resolve-condition-event/#resolveconditionevent)]| All conditions resolved on this note  
histories_of_present_illness| QuerySet[[HistoryOfPresentIllness](/sdk/data-history-present-illness/#historyofpresentillness)]| All histories of present illness recorded on this note  
vital_sign_readings| QuerySet[[VitalSignReading](/sdk/data-vital-sign-reading/#vitalsignreading)]| All vital sign readings recorded on this note  
cancel_prescriptions| QuerySet[[CancelPrescription](/sdk/data-cancel-prescription/#cancelprescription)]| All prescription cancellations recorded on this note  
prescription_change_requests| QuerySet[[PrescriptionChangeRequest](/sdk/data-prescription-change-request/#prescriptionchangerequest)]| All pharmacy change requests recorded on this note  
prescription_change_responses| QuerySet[[PrescriptionChangeResponse](/sdk/data-prescription-change-response/#prescriptionchangeresponse)]| All responses to change requests recorded on this note  
###  NoteType 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
name| String  
icon| String  
category| NoteTypeCategories  
rank| Integer  
is_default_appointment_type| Boolean  
is_scheduleable| Boolean  
is_telehealth| Boolean  
is_billable| Boolean  
defer_place_of_service_to_practice_location| Boolean  
available_places_of_service| Array[PracticeLocationPOS]  
default_place_of_service| PracticeLocationPOS  
is_system_managed| Boolean  
is_visible| Boolean  
is_active| Boolean  
unique_identifier| UUID  
deprecated_at| DateTime  
is_patient_required| Boolean  
allow_custom_title| Boolean  
is_scheduleable_via_patient_portal| Boolean  
online_duration| Integer  
is_sig_required| Boolean  
notes| QuerySet[Note]  
appointments| QuerySet[[Appointment](/sdk/data-appointment/#appointment)]  
###  NoteMetadata 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
note| Note  
key| String  
value| String  
    ```python
    from canvas_sdk.v1.data.note import Note
    from logger import log
    note_id = "89992c23-c298-4118-864a-26cb3e1ae822"
    note = Note.objects.get(id=note_id)
    note_metadata = note.metadata.all()
    for metadata in note_metadata:
       log.info(f"Note metadata: {metadata.key}, {metadata.value}")
    ```
###  NoteStateChangeEvent 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
note| [Note](/sdk/data-note/)  
originator| [CanvasUser](/sdk/data-canvasuser)  
state| [NoteState](/sdk/data-note/#notestates)  
note_state_document| String  
note_state_html| String  
> **Info:** The `note_state_document` and `note_state_html` fields hold the snapshot captured when a note is locked. The FHIR `DocumentReference` PDF content is copied from `note_state_document` at that same time, so all three are the copies consumers read. By default they include commands that were entered in error, which appear struck through in `note_state_html` as `Entered in Error/Removed on …` entries. When Canvas Support enables the opt-in setting (`EXCLUDE_ENTERED_IN_ERROR_FROM_NOTE_DOCUMENTS`, off by default) on an instance, these read copies instead omit entered-in-error commands — the field names and the `DocumentReference` schema are unchanged, only each copy's content differs. The full audit copy that keeps entered-in-error commands remains available from the note-footer PDF link served by `/api/NoteStateChangeEventDocument/{id}.pdf`.
###  CurrentNoteStateEvent 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
state| [NoteState](/sdk/data-note/#notestates)  
note| [Note](/sdk/data-note/)  
##  Enumeration types 
###  NoteStates 
Value| Description| Notes  
---|---|---  
NEW| Created|   
PSH| Pushed the charges for|   
LKD| Locked|   
ULK| Unlocked|   
DLT| Deleted|   
RLK| Relocked|   
RST| Restored|   
RCL| Recalled|   
UND| Undeleted|   
DSC| Discharged|   
SGN| Signed| Used when the note type's `is_sig_required` is True  
SCH| Scheduling| Used in appointment notes  
BKD| Booked| Used in appointment notes  
CVD| Converted| Used in appointment notes  
CLD| Canceled| Used in appointment notes  
NSW| No show| Used in appointment notes  
RVT| Reverted| Used in appointment notes  
CNF| Confirmed| Used for CCDA import notes  
###  NoteTypeCategories 
Value| Description  
---|---  
message| Message  
letter| Letter  
inpatient| Inpatient Visit Note  
review| Chart Review Note  
encounter| Encounter Note  
appointment| Appointment Note  
task| Task  
data| Data  
ccda| C-CDA  
schedule_event| Schedule Event  
###  PracticeLocationPOS 
Value| Description  
---|---  
01| Pharmacy  
02| Telehealth  
03| Education Facility  
04| Homeless Shelter  
09| Prison  
10| Telehealth in Patient's Home  
11| Office  
12| Home  
13| Asssisted Living Facility  
14| Group Home  
15| Mobile Unit  
17| Walk-In Retail Health Clinic  
19| Off-Campus Outpatient Hospital  
20| Urgent Care Facility  
21| Inpatient Hospital  
22| On-Campus Outpatient Hospital  
23| Emergency Room Hospital  
24| Ambulatory Surgery Center  
25| Birthing Center  
26| Military Treatment Facility  
27| Outreach Site / Street  
31| Skilled Nursing Facility  
32| Nursing Facility  
33| Custodial Care Facility  
34| Hospice  
41| Ambulance Land  
42| Ambulance Air or Water  
49| Independent Clinic  
50| Federally Qualified Health Center  
51| Inpatient Psychiatric Facility  
52| Inpatient Psychiatric Facility - Partial Hospitalization  
53| Community Mental Health Center  
54| Intermediate Care Facility for Mentally Retarded  
55| Residential Substance Abuse Treatment Facility  
56| Psychiatric Residential Treatment Center  
57| Non-Residential Substance Abuse Treatment Facility  
60| Mass Immunization Center  
61| Inpatient Rehabilitation Facility  
62| Outpatient Rehabilitation Facility  
65| End-Stage Renal Disease Treatment Facility  
71| State or Local Public Health Clinic  
72| Rural Health Clinic  
81| Independent Laboratory  
99| Other Place of Service

---

# Observation

Source: https://docs.canvasmedical.com/sdk/data-observation/

##  Introduction 
The `Observation` model represents measurements or assertions made about a patient, such as vital signs, lab results, or other clinical findings.
##  Basic usage 
To get an observation by identifier, use the `get` method on the `Observation` model manager:
    ```python
    from canvas_sdk.v1.data.observation import Observation
    observation = Observation.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the observations for a patient can be accessed with the `observations` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    observations = patient.observations.all()
    ```
If you have a patient ID, you can get the observations for the patient with the `for_patient` method on the `Observation` model manager:
    ```python
    from canvas_sdk.v1.data.observation import Observation
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    observations = Observation.objects.for_patient(patient_id)
    ```
##  Accessing questionnaire scores 
The `QuestionnaireResult` model, and the `score` on it, is not exposed in the SDK data module. When Canvas scores a questionnaire, it records the score on an `Observation` created alongside the result, so you read scores through the patient's observations. Each scored questionnaire produces one observation:
Attribute| Value  
---|---  
`name`| The questionnaire's name, such as `PHQ-9`  
`value`| The score, as a string  
`category`| `survey`  
`note_id`| The `dbid` of the note the questionnaire was completed in  
`codings`| The questionnaire's scoring code, such as LOINC `44261-6` for the PHQ-9 total score. A questionnaire that could not be scored, such as one left incomplete, has no coding.  
To find a patient's scores for one questionnaire, filter on its coding. `effective_datetime` is not set on these observations, so order by `created`:
    ```python
    from canvas_sdk.v1.data.observation import Observation
    phq9_scores = (
        Observation.objects.for_patient("b80b1cdc2e6a4aca90ccebc02e683f35")
        .committed()
        .filter(category="survey", codings__system="http://loinc.org", codings__code="44261-6")
        .order_by("-created")
    )
    for observation in phq9_scores:
        print(observation.name, observation.value, observation.created)
    ```
To get the scores recorded in a specific note, filter on `note_id` with the note's `dbid` instead of the coding.
##  Codings 
The codings for an observation can be accessed with the `codings` attribute on an `Observation` object:
    ```python
    from canvas_sdk.v1.data.observation import Observation
    from logger import log
    observation = Observation.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in observation.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
##  Components 
The components for an observation can be accessed with the `components` attribute on an `Observation` object:
    ```python
    from canvas_sdk.v1.data.observation import Observation
    from logger import log
    observation = Observation.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for component in observation.components.all():
        log.info(f"name: {component.name}")
        log.info(f"value: {component.value_quantity}")
        log.info(f"unit: {component.value_quantity_unit}")
    ```
###  Component codings 
Component codings can be accessed similarly to codings on the observation, by using the `codings` attribute on an `ObservationComponent` object.
##  Filtering 
Observations can be filtered by any attribute that exists on the model.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.observation import Observation
    observations = Observation.objects.filter(effective_datetime__gte="2024-11-20")
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The `find` method on the model manager is used to perform `ValueSet` filtering:
    ```python
    from canvas_sdk.v1.data.observation import Observation
    from canvas_sdk.value_set.v2022.physical_exam import Weight
    observations = Observation.objects.find(Weight)
    ```
##  Attributes 
###  Observation 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
is_member_of| Observation  
category| String (comma-separated list of categories  
units| String  
value| String  
note_id| Integer  
name| String  
effective_datetime| DateTime  
codings| ObservationCoding[]  
members| Observation[]  
components| ObservationComponent[]  
value_codings| ObservationValueCoding[]  
###  ObservationCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
observation| Observation  
###  ObservationComponent 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
observation| Observation  
value_quantity| String  
value_quantity_unit| String  
name| String  
codings| ObservationComponentCoding[]  
###  ObservationComponentCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
observation_component| ObservationComponent  
###  ObservationValueCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
observation| Observation  

---

# Organization

Source: https://docs.canvasmedical.com/sdk/data-organization/

##  Introduction 
The `Organization` model represents the overall Organization in a Canvas EMR instance. An `Organization` can have multiple related [Practice Locations](/sdk/data-practicelocation).
##  Basic usage 
Canvas instances can contain only a single `Organization` entry. To retrieve the `Organization` entry, you can either query by the organization's name:
    ```python
    from canvas_sdk.v1.data.organization import Organization
    organization = Organization.objects.get(full_name="Medical Organization")
    ```
Or since there will only be one `Organization` in an instance, it can also be fetched by using the `first` method:
    ```python
    from canvas_sdk.v1.data.organization import Organization
    organization = Organization.objects.first()
    ```
##  Attributes 
###  Organization 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
full_name| String  
short_name| String  
subdomain| String  
logo_url| String  
background_image_url| String  
background_gradient| String  
active| Boolean  
tax_id| String  
tax_id_type| [TaxIDType](/sdk/data-enumeration-types/#taxidtype)  
group_npi_number| String  
group_taxonomy_number| String  
include_zz_qualifier| Boolean  
main_location| [PracticeLocation](/sdk/data-practicelocation/#practicelocation)  
practice_locations| QuerySet[[PracticeLocation](/sdk/data-practicelocation/#practicelocation)]  
addresses| QuerySet[OrganizationAddress]  
telecom| QuerySet[OrganizationContactPoint]  
business_lines| QuerySet[[BusinessLine](/sdk/data-business-line/#businessline)]  
##  OrganizationAddress 
The `OrganizationAddress` model represents a physical or mailing address associated with an Organization. Multiple addresses can be linked to a single Organization, each with its own type and details.
###  Attributes 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
organization| Organization  
use| [AddressUseWithBilling](/sdk/data-enumeration-types/#addressusewithbilling)  
type| [AddressType](/sdk/data-enumeration-types/#addresstype)  
longitude| Float  
latitude| Float  
start| Date  
end| Date  
country| String  
state| [AddressState](/sdk/data-enumeration-types/#addressstate)  
address_search_index| String  
line1| String  
line2| String  
city| String  
district| String  
state_code| String  
postal_code| String  
##  OrganizationContactPoint 
The `OrganizationContactPoint` model represents a contact method (such as phone, email, or fax) for an Organization. Multiple contact points can be associated with a single Organization, each with its own type, use, and status.
###  Attributes 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
organization| Organization  
system| [ContactPointSystem](/sdk/data-enumeration-types/#contactpointsystem)  
value| String  
use| [ContactPointUse](/sdk/data-enumeration-types/#contactpointuse)  
use_notes| String  
rank| Integer  
state| [ContactPointState](/sdk/data-enumeration-types/#contactpointstate)  

---

# OrganizationalEntity

Source: https://docs.canvasmedical.com/sdk/data-organizational-entity/

##  Introduction 
The `OrganizationalEntity` model represents an external entity that Canvas references through a generic relation — for example, the [ServiceProvider](/sdk/data-serviceprovider/#service-provider) backing a patient's external care team member. Its `type` indicates which kind of entity it points at, and the `content_type` and `object_id` fields identify the specific record.
The most common use is reaching the external members of a patient's care team. A [CareTeamMembership](/sdk/data-care-team/#careteammembership) with no `staff` is an external member, and its `organizational_entity` links to the `OrganizationalEntity` describing the external provider.
##  Basic usage 
When an `OrganizationalEntity` has a `type` of `Service Provider`, its `service_provider` property resolves to the linked [ServiceProvider](/sdk/data-serviceprovider/#service-provider), giving you access to the provider's contact details — such as `business_fax` — without leaving the plugin:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="a74592ae8a6c4d0ebe0799d3fb3713d1")
    external_member = patient.care_team_memberships.filter(staff__isnull=True).first()
    entity = external_member.organizational_entity
    if entity and entity.service_provider:
        print(entity.service_provider.business_fax)
    ```
For entities of any other `type`, the `service_provider` property returns `None`.
##  Attributes 
###  OrganizationalEntity 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
content_type| [ContentType](/sdk/data-content-type/#contenttype)|   
object_id| Integer|   
name| String|   
active| Boolean|   
type| OrganizationalEntityType|   
service_provider| [ServiceProvider](/sdk/data-serviceprovider/#service-provider) | `None` (computed)| The linked `ServiceProvider` when `type` is `Service Provider`; otherwise `None`.  
##  Enumeration types 
###  OrganizationalEntityType 
Value| Label  
---|---  
Transactor| Transactor  
Business Entity| Business Entity  
Vendor| Vendor  
Service Provider| Service Provider

---

# PatientAdministrativeDocument

Source: https://docs.canvasmedical.com/sdk/data-patient-administrative-document/

The `PatientAdministrativeDocument` model represents patient-facing administrative documents: prior authorizations, advance directives and beneficiary notices, signed consent forms and agreements, insurance and prescription cards, driver's licenses, intake forms, releases of information, powers of attorney, and workers' compensation attachments. Each carries a document file and an optional `DocumentCoding`.
A signed consent form is one of these records: `patient_consents` lists the [PatientConsent](/sdk/data-patient-consent/#signed-consent-documents) records it was signed for. The blank template the patient was sent lives on the consent itself, not here.
##  Basic Usage 
    ```python
    from canvas_sdk.v1.data import PatientAdministrativeDocument
    # Get all administrative documents
    documents = PatientAdministrativeDocument.objects.all()
    # Get a specific record by its id
    document = PatientAdministrativeDocument.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    # Get a patient's administrative documents
    patient_documents = PatientAdministrativeDocument.objects.filter(
        patient__id="1eed3ea2a8d546a1b681a2a45de1d790"
    )
    ```
##  Filtering 
Patient administrative documents can be filtered by any attribute that exists on the model.
###  By patient 
    ```python
    from canvas_sdk.v1.data import PatientAdministrativeDocument, Patient
    patient = Patient.objects.get(id="b80b1cdc2e6a4aca90ccebc02e683f35")
    documents = PatientAdministrativeDocument.objects.filter(patient=patient)
    ```
##  Accessing the document file 
The `document_url` property returns a presigned S3 URL for securely accessing the document file, or `None` when no file is present.
    ```python
    from canvas_sdk.v1.data import PatientAdministrativeDocument
    document = PatientAdministrativeDocument.objects.exclude(document="").first()
    # Returns a presigned S3 URL (valid for 1 hour)
    url = document.document_url
    ```
##  Review assignment 
A document is assigned for review to staff members or to a team. `reviewers` holds the assigned staff members, and `team` holds the assigned team, or `None` when no team is assigned.
    ```python
    from canvas_sdk.v1.data import PatientAdministrativeDocument, Staff
    document = PatientAdministrativeDocument.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    # The staff members and the team the document is assigned to
    reviewers = document.reviewers.all()
    team = document.team
    # Every document assigned to this staff member
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    assigned = PatientAdministrativeDocument.objects.filter(reviewers__id=staff.id)
    ```
##  The document reference 
Each record also has a [DocumentReference](/sdk/data-document-reference/#the-related-object) pointing back at it — the record that carries the document's coding, category and status, and that represents it in the FHIR API. `document_url` above is the direct route to the file itself; reach for the document reference when you want that surrounding metadata.
Resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` — never hardcode the per-environment `dbid` — and match `object_id` against the record's `dbid`:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference, PatientAdministrativeDocument
    record = PatientAdministrativeDocument.objects.get(
        id="d2194110-5c9a-4842-8733-ef09ea5ead11"
    )
    content_type = ContentType.objects.filter(
        app_label="api", model="patientadministrativedocument"
    ).first()
    document = DocumentReference.objects.filter(
        content_type=content_type, object_id=record.dbid
    ).first()
    ```
> **Info:** `object_id` holds the related record's integer `dbid`, not its UUID `id`.
##  Document codings 
The `code` field comes from the document's type, which is drawn from a fixed list rather than set freely — either the type selected in Data Integration, or, when a document is created through the FHIR [DocumentReference](/api/documentreference/) endpoint, the LOINC code supplied in `type.coding`, which must match one of the codes below. Every coding uses the LOINC system (`http://loinc.org`). The document types stored as patient administrative documents are:
Document type| Code| Display  
---|---|---  
Advance Beneficiary Notice| 53243-2| Advanced beneficiary notice  
Advance Directive| 42348-3| Advance directives  
Commercial Driver License| 53245-7| Driver license  
Insurance Card Image| 64290-0| Health insurance card  
Insurer Prior Authorization| 52034-6| Payer letter  
Patient Agreement| 80570-5| Agreement  
Patient Consent Documents| 59284-0| Consent Document  
Power of Attorney| 64298-3| Power of attorney  
Provider Order| 46209-3| Provider orders  
Release of Information Request| 101904-1| Release of Information request  
Uncategorized Administrative Document| 51851-4| Administrative note  
Workers Compensation Documents| 52070-0| Workers compensation attachment  
Disability Form| —| none  
Handicap Parking Permit| —| none  
Medicaid Documents| —| none  
Patient Assistance Documents| —| none  
Patient Intake Form| —| none  
Prescription Card Documents| —| none  
> **Warning:** Six of these document types have no coding assigned, so their `code` is `None`. Filtering on `code` silently excludes them — check for a null `code` if you need to catch every administrative document. Because the FHIR endpoint identifies a document's type by its LOINC code, these six can only be created through Data Integration.
Clinical document types are stored as [UncategorizedClinicalDocument](/sdk/data-uncategorized-clinical-document/) instead. Lab reports, imaging reports and specialist consult reports have their own models, so their codings never appear here.
##  Attributes 
###  PatientAdministrativeDocument 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
patient| [Patient](/sdk/data-patient/#patient)|   
originator| [CanvasUser](/sdk/data-canvasuser)|   
assigned_by| [CanvasUser](/sdk/data-canvasuser)|   
team| [Team](/sdk/data-team/#team)|   
reviewers| [Staff](/sdk/data-staff/#staff)[]|   
integration_task_review| [IntegrationTaskReview](/sdk/data-integration-task/#integrationtaskreview)|   
code| DocumentCoding|   
name| String|   
review_mode| [DocumentReviewMode](/sdk/data-enumeration-types/#documentreviewmode)|   
junked| Boolean|   
assigned_date| DateTime|   
team_assigned_date| DateTime|   
original_date| Date|   
comment| String|   
priority| Boolean|   
document| String|   
document_url| String (computed)| Presigned S3 URL or None  
patient_consents| QuerySet[[PatientConsent](/sdk/data-patient-consent/#patientconsent)]| The consents this document is a signed copy of  
###  DocumentCoding 
A coding entry representing the type of document. Also used by [UncategorizedClinicalDocument](/sdk/data-uncategorized-clinical-document/#uncategorizedclinicaldocument).
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean

---

# PatientConsent

Source: https://docs.canvasmedical.com/sdk/data-patient-consent/

##  Introduction 
The `PatientConsent` model represents documented patient consents in Canvas that ensure legal compliance and protect patient rights. Each `PatientConsent` is linked to a `Patient`, has a category (which is a `PatientConsentCoding`), and optionally a rejection reason (which is a `PatientConsentRejectionCoding`).
##  Usage 
The `PatientConsent` model can be used to find all of the patient consents for a given patient and organization:
    ```python
    >>> from canvas_sdk.v1.data import PatientConsent, Patient, Organization
    >>> patient_1 = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> organization_1 = Organization.objects.first()
    >>> patient_1_consents = PatientConsent.objects.filter(patient=patient_1, organization=organization_1)
    >>> print([consent.category.display for consent in patient_1_consents])
    ['Surgical Consent Form', 'Telehealth', 'HIPAA']
    ```
You can also access a patient's consents from the `Patient` model:
    ```python
    >>> from canvas_sdk.v1.data import PatientConsent, Patient
    >>> patient_1 = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> patient_1_consents = patient_1.patient_consent.all()
    >>> print([consent.category.display for consent in patient_1_consents])
    ['Surgical Consent Form', 'Telehealth', 'HIPAA']
    ```
And you can also access all of the PatientConsents for a given PatientConsentCoding (aka category):
    ```python
    >>> from canvas_sdk.v1.data import PatientConsentCoding
    >>> coding = PatientConsentCoding.objects.get(code='59284-0', system='LOINC')
    >>> consents = coding.patient_consent.all()
    >>> print([consent.state for consent in consents])
    ['accepted', 'accepted_via_patient_portal', 'rejected']
    ```
Each `PatientConsentCoding` has a `document` field containing the URL to the consent template document:
    ```python
    >>> from canvas_sdk.v1.data import PatientConsentCoding
    >>> coding = PatientConsentCoding.objects.first()
    >>> print(coding.document)
    'consent_templates/hipaa_consent.pdf'
    ```
##  Accessing Document Files 
The `document_url` property returns a presigned S3 URL for securely accessing the blank consent template — the form you send to a patient to collect their consent. The copy the patient signs and returns is a separate record; see Signed consent documents.
    ```python
    from canvas_sdk.v1.data import PatientConsentCoding
    consent_coding = PatientConsentCoding.objects.first()
    # Returns a presigned S3 URL (valid for 1 hour)
    url = consent_coding.document_url
    ```
##  Signed consent documents 
The `PatientConsentCoding.document` above is the blank **template** sent to the patient. The **signed** documents the patient completes and returns are [PatientAdministrativeDocument](/sdk/data-patient-administrative-document/) records, reachable from the consent through the `documents` relation:
    ```python
    from canvas_sdk.v1.data import PatientConsent
    consent = PatientConsent.objects.get(id="8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d")
    # Every signed document attached to this consent.
    signed_documents = consent.documents.all()
    # The current signed document (the most recent non-junked one), or None.
    current = consent.active_document
    ```
Each signed document's FHIR [DocumentReference](/sdk/data-document-reference/) is reachable through `document_references`, so a plugin can read the reference (and its `related_object`) in-process without a FHIR call:
    ```python
    from canvas_sdk.v1.data import PatientConsent
    consent = PatientConsent.objects.get(id="8a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d")
    for reference in consent.document_references:
        url = reference.document_url
    ```
##  Attributes 
###  PatientConsent 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
patient| [Patient](/sdk/data-patient)|   
category| PatientConsentCoding|   
state| PatientConsentStatus|   
effective_date| DateTime|   
expired_date| DateTime|   
rejection_reason| PatientConsentRejectionCoding|   
originator| [CanvasUser](/sdk/data-canvasuser)|   
documents| QuerySet[[PatientAdministrativeDocument](/sdk/data-patient-administrative-document/)]| The signed consent documents  
active_document| [PatientAdministrativeDocument](/sdk/data-patient-administrative-document/) (computed)| The current signed document, or `None`  
document_references| QuerySet[[DocumentReference](/sdk/data-document-reference/)] (computed)| References for the signed documents  
###  PatientConsentCoding 
Field Name| Type| Description  
---|---|---  
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
system| String|   
version| String|   
code| String|   
display| String|   
user_selected| Boolean|   
expiration_rule| PatientConsentExpirationRule|   
is_mandatory| Boolean|   
is_proof_required| Boolean|   
show_in_patient_portal| Boolean|   
summary| String|   
document| String|   
document_url| String (computed)| Presigned S3 URL  
patient_consent| QuerySet[PatientConsent]|   
###  PatientConsentRejectionCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
patient_consents| QuerySet[PatientConsent]  
##  Enumeration types 
###  PatientConsentStatus 
Member| Value| Label  
---|---|---  
`ACCEPTED`| accepted| Accepted  
`ACCEPTED_VIA_PORTAL`| accepted_via_patient_portal| Accepted Via Patient Portal  
`REJECTED`| rejected| Rejected  
`REJECTED_VIA_PORTAL`| rejected_via_patient_portal| Rejected Via Patient Portal  
###  PatientConsentExpirationRule 
Value| Label  
---|---  
never| Never  
in_one_year| In one year  
end_of_year| End of year

---

# Patient Group

Source: https://docs.canvasmedical.com/sdk/data-patient-group/

##  Introduction 
The `PatientGroup` model represents a named collection of patients. Patients are associated with a group through the `PatientGroupMember` model, which tracks membership along with start/end dates and active status.
##  Basic usage 
To get a patient group by identifier, use the `get` method on the `PatientGroup` model manager:
    ```python
    from canvas_sdk.v1.data.patient_group import PatientGroup
    group = PatientGroup.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
To get the members of a group:
    ```python
    from canvas_sdk.v1.data.patient_group import PatientGroup
    from logger import log
    group = PatientGroup.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for patient in group.members.all():
        log.info(f"Patient: {patient.id}")
    ```
If you have a patient object, the groups that a patient belongs to can be accessed with the `patient_groups` attribute on a [Patient](/sdk/data-patient/#patient) object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="a74592ae8a6c4d0ebe0799d3fb3713d1")
    groups = patient.patient_groups.all()
    ```
##  Membership 
The `PatientGroupMember` model represents a patient's membership in a group. To access the membership records for a group:
    ```python
    from canvas_sdk.v1.data.patient_group import PatientGroup, PatientGroupMember
    from logger import log
    group = PatientGroup.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    # Get active members
    active_members = PatientGroupMember.objects.filter(patient_group=group, active=True)
    for membership in active_members:
        log.info(f"Patient: {membership.member.id}, Start: {membership.start_date}")
    ```
##  Filtering 
Patient groups and memberships can be filtered by any attribute that exists on the model.
###  By name 
    ```python
    from canvas_sdk.v1.data.patient_group import PatientGroup
    groups = PatientGroup.objects.filter(name="Diabetes Management")
    ```
###  By active membership 
    ```python
    from canvas_sdk.v1.data.patient_group import PatientGroupMember
    active_memberships = PatientGroupMember.objects.filter(active=True, patient_group__name="Diabetes Management")
    ```
##  Attributes 
###  PatientGroup 
Field Name| Type  
---|---  
id| UUID  
name| String  
members| [Patient](/sdk/data-patient/)[]  
created| DateTime  
modified| DateTime  
patientgroupmember_set| PatientGroupMember[]  
###  PatientGroupMember 
Field Name| Type  
---|---  
created| DateTime  
modified| DateTime  
patient_group| PatientGroup  
member| [Patient](/sdk/data-patient/)  
start_date| DateTime  
end_date| DateTime (nullable)  
locked| Boolean  
active| Boolean  

---

# Patient

Source: https://docs.canvasmedical.com/sdk/data-patient/

##  Introduction 
The `Patient` model represents an individual receiving care or other health-related services.
##  Basic usage 
To get a patient by identifier, use the `get` method on the `Patient` model manager:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="b80b1cdc2e6a4aca90ccebc02e683f35")
    ```
##  Filtering 
Patients can be filtered by any attribute that exists on the model.
Filtering for patients is done with the `filter` method on the `Patient` model manager.
###  By attribute 
Specify attributes with `filter` to filter by those attributes:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patients = Patient.objects.filter(first_name="Bob", last_name="Loblaw", birth_date="1960-09-22")
    ```
###  Retrieving only committed, recorded data 
To restrict a patient's clinical data to committed records, use the queryset's `committed()` method. It keeps records with a non-null `committer` and a null `entered_in_error`, and the model's default manager already excludes deleted records. For example, for a patient's observations:
    ```python
    from canvas_sdk.v1.data.observation import Observation
    observations = Observation.objects.for_patient(patient.id).committed()
    ```
Most clinical data models provide `committed()`. On a model that records a committer without providing it, such as [`Command`](/sdk/data-command/), filter on `committer_id__isnull=False, entered_in_error_id__isnull=True` directly.
##  Accessing the patient photo 
The `photo_url` property returns a presigned S3 URL for securely accessing the patient's uploaded avatar photo. If the patient has no uploaded avatar, the property returns a default avatar URL instead — so the value is always safe to render without a null check.
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="d7af3e356368446c85b40a5d6ff7288e")
    # Returns a presigned S3 URL (valid for 1 hour), or the default avatar URL when no photo is on file
    url = patient.photo_url
    ```
If you need the underlying `PatientPhoto` record (for example, to read its `title`, or the stored file key with `url.name`), use the `photo` property:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="d7af3e356368446c85b40a5d6ff7288e")
    photo = patient.photo  # PatientPhoto or None
    if photo:
        print(photo.title)
    ```
##  Reading uploaded images and PDFs 
To read uploaded files (such as insurance card images or scanned PDFs) programmatically, use the file-upload data models, which expose the underlying S3 link rather than requiring direct bucket/AWS credentials:
  - [`DocumentReference`](/sdk/data-document-reference/) — uploaded documents
  - [`Snapshot` / `SnapshotImage`](/sdk/data-snapshot/) — snapshot images
  - `PatientIdentificationCard` — insurance card and ID card images (`image_url` property)
  - [`MessageAttachment.file_url`](/sdk/data-message/#messageattachment) — files attached to messages
##  Accessing educational materials 
If you have a `Patient` object, the educational materials recorded on their notes can be accessed with the `education_material` reverse relation:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="d7af3e356368446c85b40a5d6ff7288e")
    educational_materials = patient.education_material.all()
    ```
##  Detecting patient portal registration 
To detect whether a patient has registered for the patient portal, use the `is_portal_registered` boolean on the patient's [`CanvasUser`](/sdk/data-canvasuser) record (via the `user` relation). Patient portal verification is a separate process from contact-point verification, so check this boolean rather than `PatientContactPoint.last_verified` for portal registration:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="d7af3e356368446c85b40a5d6ff7288e")
    registered = patient.user.is_portal_registered
    ```
##  Attributes 
###  Patient 
Field Name| Type| Description  
---|---|---  
id| String|   
dbid| Integer|   
first_name| String|   
last_name| String|   
birth_date| Date|   
sex_at_birth| SexAtBirth|   
created| DateTime|   
modified| DateTime|   
prefix| String|   
suffix| String|   
middle_name| String|   
maiden_name| String|   
nickname| String|   
sexual_orientation_term| String|   
sexual_orientation_code| String|   
gender_identity_term| String|   
gender_identity_code| String|   
preferred_pronouns| String|   
biological_race_codes| Array[String]|   
cultural_ethnicity_codes| Array[String]|   
last_known_timezone| String|   
mrn| String|   
active| Boolean|   
deceased| Boolean|   
deceased_datetime| DateTime|   
deceased_cause| String|   
deceased_comment| String|   
other_gender_description| String|   
social_security_number| String|   
administrative_note| String|   
clinical_note| String|   
mothers_maiden_name| String|   
multiple_birth_indicator| Boolean|   
birth_order| Integer|   
default_location_id| Integer|   
default_provider_id| Integer|   
addresses| PatientAddress[]|   
allergy_intolerances| [AllergyIntolerance](/sdk/data-allergy-intolerance/#allergyintolerance)[]|   
assessed_coding_gaps| [AssessCodingGapEvent](/sdk/data-coding-gap-event/#assesscodinggapevent)[]|   
assessed_detected_issues| [ValidateCodingGapEvent](/sdk/data-coding-gap-event/#validatecodinggapevent)[]|   
billing_line_items| [BillingLineItem](/sdk/data-billing-line-item/)|   
business_line| [BusinessLine](/sdk/data-business-line/)|   
care_team_memberships| [CareTeamMembership](/sdk/data-care-team/#careteammembership)[]|   
change_medications| [ChangeMedication](/sdk/data-change-medication/#changemedication)[]|   
clipboards| [Clipboard](/sdk/data-clipboard/#clipboard)[]|   
conditions| [Condition](/sdk/data-condition/#condition)[]|   
coverages| [Coverage](/sdk/data-coverage/#coverage)[]|   
created_detected_issues| [CreateCodingGapEvent](/sdk/data-coding-gap-event/#createcodinggapevent)[]|   
custom_commands| [CustomCommand](/sdk/data-custom-command/#customcommand)[]|   
deferred_detected_issues| [DeferCodingGapEvent](/sdk/data-coding-gap-event/#defercodinggapevent)[]|   
dependent_coverages| [Coverage](/sdk/data-coverage/#coverage)[]|   
detected_issues| [DetectedIssue](/sdk/data-detected-issue/#detectedissue)[]|   
devices| [Device](/sdk/data-device/#device)[]|   
dme_orders| [DmeOrder](/sdk/data-dme/#dmeorder)[]|   
external_identifiers| PatientExternalIdentifier[]|   
identification_cards| PatientIdentificationCard[]|   
imaging_orders| [ImagingOrder](/sdk/data-imaging/#imagingorder)[]|   
imaging_results| [ImagingReport](/sdk/data-imaging/#imagingreport)[]|   
imaging_reviews| [ImagingReview](/sdk/data-imaging/#imagingreview)[]|   
interviews| [Interview](/sdk/data-questionnaire/#interview)[]|   
lab_orders| [LabOrder](/sdk/data-labs/#laborder)[]|   
lab_reports| [LabReport](/sdk/data-labs/#labreport)[]|   
lab_reviews| [LabReview](/sdk/data-labs/#labreview)[]|   
medications| [Medication](/sdk/data-medication/#medication)[]|   
metadata| PatientMetadata[]|   
observations| [Observation](/sdk/data-observation/#observation)[]|   
payment_cards| [PaymentCard](/sdk/data-payment-card/#paymentcard)[]|   
photos| PatientPhoto[]|   
preferred_pharmacy| JSON|   
preferred_pharmacies| JSON|   
protocol_overrides| [ProtocolOverride](/sdk/data-protocol-override/#protocoloverride)[]|   
settings| PatientSetting|   
subscribed_coverages| [Coverage](/sdk/data-coverage/#coverage)[]|   
tasks| [Task](/sdk/data-task/#task)[]|   
telecom| PatientContactPoint[]|   
contacts| PatientContactPerson[]|   
related_contacts| PatientContactPerson[]| Contacts on _other_ patients that reference this one  
user| [CanvasUser](/sdk/data-canvasuser/)[]|   
patient_groups| [PatientGroup](/sdk/data-patient-group/)[]|   
chart_section_reviews| [ChartSectionReview](/sdk/data-chart-section-review/#chartsectionreview)[]|   
visual_exam_findings| [VisualExamFinding](/sdk/data-visual-exam-finding/#visualexamfinding)[]|   
vital_sign_readings| [VitalSignReading](/sdk/data-vital-sign-reading/#vitalsignreading)[]|   
assessments| [Assessment](/sdk/data-assessment/#assessment)[]|   
patient_visits| [ExternalVisit](/sdk/data-external-event/#externalvisit)[]|   
patient_events| [ExternalEvent](/sdk/data-external-event/#externalevent)[]|   
medication_statements| [MedicationStatement](/sdk/data-medication-statement/#medicationstatement)[]|   
diagnostic_reports| DiagnosticReport[]|   
medication_history_medications| [MedicationHistoryMedication](/sdk/data-medication-history/#medicationhistorymedication)[]|   
medication_history_responses| [MedicationHistoryResponse](/sdk/data-medication-history/#medicationhistoryresponse)[]|   
payments| [BulkPatientPosting](/sdk/data-posting/#bulkpatientposting)[]|   
protocol_currents| [ProtocolCurrent](/sdk/data-protocol-current/)[]|   
stopped_medications| [StopMedicationEvent](/sdk/data-stop-medication-event/#stopmedicationevent)[]|   
banner_alerts| [BannerAlert](/sdk/data-banner-alert/#banneralert)[]|   
immunizations| [Immunization](/sdk/data-immunization/#immunization)[]|   
immunization_statements| [ImmunizationStatement](/sdk/data-immunization/#immunizationstatement)[]|   
integration_tasks| [IntegrationTask](/sdk/data-integration-task/#integrationtask)[]|   
installment_plans| [InstallmentPlan](/sdk/data-claim/#installmentplan)[]|   
uncategorized_clinical_document_reviews| [UncategorizedClinicalDocumentReview](/sdk/data-uncategorized-clinical-document/#uncategorizedclinicaldocumentreview)[]|   
patient_consent| [PatientConsent](/sdk/data-patient-consent/#patientconsent)[]|   
goals| [Goal](/sdk/data-goal/#goal)[]|   
updategoals| [UpdateGoal](/sdk/data-goal/#updategoal)[]|   
instructions| [Instruction](/sdk/data-instruction/#instruction)[]|   
appointments| [Appointment](/sdk/data-appointment/#appointment)[]|   
notes| [Note](/sdk/data-note/#note)[]|   
prescriptions| [Prescription](/sdk/data-prescription/#prescription)[]|   
refill_requests| [RefillRequest](/sdk/data-refill-request/#refillrequest)[]|   
referral_reviews| [ReferralReview](/sdk/data-referral/#referralreview)[]|   
referral_reports| [ReferralReport](/sdk/data-referral/#referralreport)[]|   
invoices| Invoice[]|   
education_material| [EducationalMaterial](/sdk/data-educational-material/#educationalmaterial)[]|   
procedures| [Procedure](/sdk/data-procedure/#procedure)[]|   
family_histories| [FamilyHistory](/sdk/data-family-history/#familyhistory)[]|   
histories_of_present_illness| [HistoryOfPresentIllness](/sdk/data-history-present-illness/#historyofpresentillness)[]|   
plans| [Plan](/sdk/data-plan/#plan)[]|   
follow_ups| [FollowUp](/sdk/data-follow-up/#followup)[]|   
reasons_for_visit| [ReasonForVisit](/sdk/data-reason-for-visit/#reasonforvisit)[]|   
removed_allergies| [RemoveAllergyEvent](/sdk/data-remove-allergy-event/#removeallergyevent)[]|   
removed_past_medical_history| [RemovePastMedicalHistoryEvent](/sdk/data-remove-past-medical-history-event/#removepastmedicalhistoryevent)[]|   
resolved_conditions| [ResolveConditionEvent](/sdk/data-resolve-condition-event/#resolveconditionevent)[]|   
cancel_prescriptions| [CancelPrescription](/sdk/data-cancel-prescription/#cancelprescription)[]|   
cancel_prescription_responses| [CancelPrescriptionResponse](/sdk/data-cancel-prescription-response/#cancelprescriptionresponse)[]|   
prescription_change_requests| [PrescriptionChangeRequest](/sdk/data-prescription-change-request/#prescriptionchangerequest)[]|   
prescription_change_responses| [PrescriptionChangeResponse](/sdk/data-prescription-change-response/#prescriptionchangeresponse)[]|   
full_name| String (computed)| The full name of the patient, combining first, middle, and last names  
preferred_pharmacy| Dict (computed)| The patient's preferred pharmacy for medication fulfillment  
preferred_full_name| String (computed)| The patient's preferred full name, if different from the legal name  
preferred_first_name| String (computed)| The patient's preferred first name, if different from the legal first name  
primary_phone_number| PatientContactPoint (computed)| The patient's primary contact number  
photo| PatientPhoto (computed)| The patient's first uploaded avatar, if any  
photo_url| String (computed)| A presigned URL for the patient's avatar photo, or the default avatar URL when no photo is set  
###  PatientAddress 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
line1| String  
line2| String  
city| String  
district| String  
state_code| String  
postal_code| String  
use| [AddressUse](/sdk/data-enumeration-types/#addressuse)  
type| [AddressType](/sdk/data-enumeration-types/#addresstype)  
longitude| Float  
latitude| Float  
start| Date  
end| Date  
country| String  
state| [AddressState](/sdk/data-enumeration-types/#addressstate)  
patient| Patient  
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from logger import log
    patient_id = "d7af3e356368446c85b40a5d6ff7288e"
    patient = Patient.objects.get(id=patient_id)
    patient_addresses = patient.addresses.all()
    for addr in patient_addresses:
      log.info(f"Patient address: {addr.city}, {addr.state_code}, {addr.postal_code}") # Seattle, WA, 98118
    ```
###  PatientContactPoint 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| [ContactPointSystem](/sdk/data-enumeration-types/#contactpointsystem)  
value| String  
use| String  
use_notes| String  
rank| Integer  
state| [ContactPointState](/sdk/data-enumeration-types/#contactpointstate)  
patient| Patient  
has_consent| Boolean  
last_verified| DateTime  
verification_token| String  
opted_out| Boolean  
To fetch a patient's contact points, query the patient's `telecom` relation. Use `.all()` for every contact point, or `.filter()` for a subset such as phone numbers:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from logger import log
    patient_id = "d7af3e356368446c85b40a5d6ff7288e"
    patient = Patient.objects.get(id=patient_id)
    # All contact points
    patient_contacts = patient.telecom.all()
    # Just the phone numbers
    phone_contacts = patient.telecom.filter(system="phone")
    for contact in patient_contacts:
       log.info(f"Patient contact: {contact.system} - {contact.value}") # phone - 5555555555
    ```
###  PatientExternalIdentifier 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| Patient  
use| String  
identifier_type| String  
system| String  
value| String  
issued_date| Date  
expiration_date| Date  
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from logger import log
    patient_id = "d7af3e356368446c85b40a5d6ff7288e"
    patient = Patient.objects.get(id=patient_id)
    patient_external_identifiers = patient.external_identifiers.all()
    for identifier in patient_external_identifiers:
       log.info(f"Patient external identifier: {identifier.system}, {identifier.value}")  # https://www.example.com - abc123
    ```
###  PatientSetting 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| Patient  
name| String  
value| JSON  
####  Setting names 
A patient carries at most one setting per `name`. Canvas maintains these:
Name| Holds  
---|---  
`pharmacy`| The patient's preferred pharmacies. Read this through `preferred_pharmacies`, which normalizes the older single-pharmacy shape into a list  
`preferredSchedulingTimezone`| The timezone to schedule the patient in, for example `America/New_York`  
Because `value` is JSON, its shape differs from one setting to the next.
Use `get_setting` to read one by name. It returns `None` when the patient has no setting by that name, so a missing setting and a stored empty value are distinguishable.
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from logger import log
    patient_id = "d7af3e356368446c85b40a5d6ff7288e"
    patient = Patient.objects.get(id=patient_id)
    log.info(patient.get_setting("preferredSchedulingTimezone"))  # America/New_York
    log.info(patient.get_setting("unset-setting-name"))  # None
    ```
###  PatientMetadata 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| Patient  
key| String  
value| String  
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from logger import log
    patient_id = "d7af3e356368446c85b40a5d6ff7288e"
    patient = Patient.objects.get(id=patient_id)
    patient_metadata = patient.metadata.all()
    for metadata in patient_metadata:
       log.info(f"Patient metadata: {metadata.key}, {metadata.value}") # favorite_color - red
    ```
###  PatientPhoto 
Represents a patient's uploaded avatar photo.
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| Patient  
url| File (S3 key)  
title| String  
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from logger import log
    patient = Patient.objects.get(id="d7af3e356368446c85b40a5d6ff7288e")
    for photo in patient.photos.all():
        log.info(f"Photo: {photo.title}, stored at: {photo.url.name}")
    ```
###  PatientIdentificationCard 
Represents a patient identification card image (e.g., driver's license, insurance card).
To create, update, or delete identification cards from a plugin, use the [PatientIdentificationCard effect](/sdk/effect-patient-identification-card/).
Field Name| Type| Description  
---|---|---  
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
patient| Patient|   
image| File (S3 key)|   
title| String|   
active| Boolean|   
image_url| String (computed)| Presigned S3 URL  
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from logger import log
    patient = Patient.objects.get(id="d7af3e356368446c85b40a5d6ff7288e")
    for card in patient.identification_cards.filter(active=True):
        log.info(f"ID card: {card.title}, URL: {card.image_url}")
    ```
###  PatientFacilityAddress 
Field Name| Type  
---|---  
patientaddress| PatientAddress  
facility| Facility  
room_number| String  
###  PatientContactPerson 
One of the patient's contacts — an emergency contact, next-of-kin, or other related person. A contact either holds the person's details directly, or references another Canvas patient through `related_patient`; when it does, that patient's own details supersede the values stored here.
`id` is the value the [Patient effect](/sdk/effect-patient/#managing-patient-contacts) takes as `contact_identifier` when modifying or removing a contact.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| Patient  
name| String  
phone_number| String  
email| String  
comments| String  
related_patient| Patient  
categories| PatientContactCategory[]  
    ```python
    from canvas_sdk.v1.data import PatientContactPerson
    from logger import log
    contacts = PatientContactPerson.objects.filter(
        patient__id="d7af3e356368446c85b40a5d6ff7288e"
    ).select_related("related_patient").prefetch_related("categories__category")
    for contact in contacts:
        who = contact.related_patient.first_name if contact.related_patient else contact.name
        codings = ", ".join(link.category.code for link in contact.categories.all())
        log.info(f"Contact: {who} ({codings})")  # Contact: Jane (EMC)
    ```
###  PatientContactCategory 
Links one of the patient's contacts to one of the category codings the instance defines.
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
contact_person| PatientContactPerson  
category| ContactCategory  
###  ContactCategory 
A contact-category coding available in this Canvas instance — the set a contact's relationship can be drawn from.
Use this to look up a coding before writing it with the [Patient effect](/sdk/effect-patient/#patientcontactcategory). Writing a coding that does not appear here is rejected rather than created, so querying this model first is how you find out what the instance actually has.
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
name| String  
code| String  
system| String  
protected| Boolean  
    ```python
    from canvas_sdk.v1.data import ContactCategory
    from logger import log
    for coding in ContactCategory.objects.order_by("code"):
        log.info(f"{coding.code} / {coding.system} — {coding.name}")  # EMC / INTERNAL — Emergency contact
    ```
##  Enumeration types 
###  SexAtBirth 
Value| Label  
---|---  
F| female  
M| male  
O| other  
UNK| unknown  
"" (empty string)| ""  

---

# PaymentCard

Source: https://docs.canvasmedical.com/sdk/data-payment-card/

##  Introduction 
The `PaymentCard` model represents a patient's stored payment card on file. Cards are tokenized and stored by Canvas's payment processor, and this model exposes only the non-sensitive card metadata — brand, last four digits, expiration, cardholder name, and whether the card is the patient's default. The underlying processor token is never exposed through the SDK.
Reference a `PaymentCard` by its Canvas `id` when charging a patient's card on file with the [Charge Stored Card](/sdk/effect-charge-stored-card/) effect.
##  Basic usage 
Each `PaymentCard` is linked to a [Patient](/sdk/data-patient/#patient). Access a patient's stored cards through the `payment_cards` reverse relation:
    ```python
    >>> from canvas_sdk.v1.data import Patient
    >>> patient = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> cards = patient.payment_cards.all()
    >>> print([(card.brand, card.card_last_four_digits, card.is_default) for card in cards])
    [('visa', '4242', True), ('mastercard', '5555', False)]
    ```
To retrieve the patient's default card:
    ```python
    >>> from canvas_sdk.v1.data import Patient
    >>> patient = Patient.objects.get(id="aebe4d3f5d18410388dc69c4b5169fc3")
    >>> default_card = patient.payment_cards.filter(is_default=True).first()
    ```
##  Attributes 
###  PaymentCard 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
brand| String  
card_last_four_digits| String  
expiration_month| String  
expiration_year| String  
card_holder_name| String  
postal_code| String  
is_default| Boolean  

---

# PayorSpecificCharge

Source: https://docs.canvasmedical.com/sdk/data-payor-specific-charge/

##  Introduction 
The `PayorSpecificCharge` model represents charges specific to a [Transactor](/sdk/data-coverage/#transactor) in Canvas.
##  Usage 
The `PayorSpecificCharge` model can be used to find all of the charges specific to a single `Transactor`:
    ```python
    >>> from canvas_sdk.v1.data import PayorSpecificCharge, Transactor
    >>> aetna = Transactor.objects.get(payer_id="60054")
    >>> aetna_charges = PayorSpecificCharge.objects.filter(transactor=aetna)
    >>> print([charge.charge_amount for charge in aetna_charges])
    [150.00, 40.00, 99.99]
    ```
You can also access a transactor's specific charges from the `Transactor` model:
    ```python
    >>> from canvas_sdk.v1.data import Transactor
    >>> aetna = Transactor.objects.get(payer_id="60054")
    >>> aetna_charges = aetna.specific_charges.all()
    >>> print([charge.charge_amount for charge in aetna_charges])
    [150.00, 40.00, 99.99]
    ```
`
##  Attributes 
###  PayorSpecificCharge 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
transactor| [Transactor](/sdk/data-coverage/#transactor)  
charge| [ChargeDescriptionMaster](/sdk/data-charge-description-master)  
charge_amount| Decimal  
effective_date| Date  
end_date| Date  
part_of_capitated_set| Boolean

---

# Plan

Source: https://docs.canvasmedical.com/sdk/data-plan/

##  Introduction 
The `Plan` model represents a Plan (plan of care) recorded on a Note, and is always associated with a Note and a Patient. It is the anchor for the [Plan](/sdk/commands/#plan) command.
##  Basic usage 
To get a plan by identifier, use the `get` method on the `Plan` model manager:
    ```python
    from canvas_sdk.v1.data.plan import Plan
    plan = Plan.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, or note object, the plans for a patient or note can be accessed with the `plans` attribute on a `Patient` or `Note` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.v1.data.note import Note
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    plans = patient.plans.all()
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    plans = note.plans.all()
    ```
##  Reading the narrative 
The plan text is exposed through the `narrative` property:
    ```python
    from canvas_sdk.v1.data.plan import Plan
    plan = Plan.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    text = plan.narrative
    ```
##  Filtering 
Plans can be filtered by any attribute that exists on the model.
###  Committed plans 
The `committed` method returns plans that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.plan import Plan
    committed_plans = Plan.objects.committed()
    ```
##  Attributes 
###  Plan 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
narrative| String  

---

# PluginCommand

Source: https://docs.canvasmedical.com/sdk/data-plugin-command/

##  Introduction 
The `PluginCommand` model exposes the custom commands a plugin registers in its [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#commands). Use it to read back a registered command's `label` and `section` instead of reconstructing display text from its camelCase `command_key`.
##  Basic usage 
To get a plugin command by identifier, use the `get` method on the `PluginCommand` model manager:
    ```python
    from canvas_sdk.v1.data.plugin_command import PluginCommand
    plugin_command = PluginCommand.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
##  Filtering 
Plugin commands can be filtered by any attribute that exists on the model.
Filtering for plugin commands is done with the `filter` method on the `PluginCommand` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.plugin_command import PluginCommand
    # Find all plugin commands in a specific chart section
    plugin_commands = PluginCommand.objects.filter(section="assessment")
    ```
###  By command key 
To find a registered command by the key declared in the manifest, filter on `command_key` — or on `schema_key`, which holds the same value:
    ```python
    from canvas_sdk.v1.data.plugin_command import PluginCommand
    plugin_command = PluginCommand.objects.filter(command_key="riskAssessment").first()
    if plugin_command:
        print(f"Label: {plugin_command.label}")
        print(f"Section: {plugin_command.section}")
    ```
##  Attributes 
###  PluginCommand 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
name| String  
command_key| String  
schema_key| String  
label| String  
section| String  
plugin_name| String  
  - **id** : The unique UUID identifier for the plugin command.
  - **dbid** : The internal database primary key.
  - **name** : The registered name of the command (e.g., `RiskAssessment`).
  - **command_key** : The command key declared in the plugin's manifest (e.g., `riskAssessment`). There is exactly one row per `command_key`: reinstalling or upgrading the plugin updates that row in place, so a command always carries its current `label` and `section`.
  - **schema_key** : Always equal to `command_key`. It exists as its own field because chart command lines use the same name — see [`Command.schema_key`](/sdk/data-command/#command), which plugin authors query with `Command.objects.filter(schema_key="riskAssessment")`. Two installed plugins cannot declare the same key; the second install fails with a validation error.
  - **label** : The user-friendly display label for the command (e.g., `Risk Assessment`).
  - **section** : The chart section where the command appears: `subjective`, `objective`, `assessment`, `plan`, `procedures`, `history`, or `internal`.
  - **plugin_name** : The name of the plugin that registered the command.

---

# Posting

Source: https://docs.canvasmedical.com/sdk/data-posting/

##  Introduction 
This module defines models related to payments and postings associated with healthcare claims.
##  Basic usage 
To retrieve a posting by ID:
    ```python
    from canvas_sdk.v1.data.posting import BasePosting
    posting = BasePosting.objects.get(dbid=1234)
    ```
To retrieve all active postings for a given claim:
    ```python
    from canvas_sdk.v1.data.claim import Claim
    claim = Claim.objects.get(id="<uuid>")
    claim_postings = claim.postings.active()
    ```
Payments, adjustments, and transfers each record the claim line item the amount was posted to. To find the charge behind a payment, go through its claim line item:
    ```python
    from canvas_sdk.v1.data import NewLineItemPayment
    payment = NewLineItemPayment.objects.select_related("claim_line_item").get(dbid=1234)
    claim_line_item = payment.claim_line_item
    print(claim_line_item.proc_code)
    # None when the claim line item has no billing line item
    charge = claim_line_item.billing_line_item
    ```
> **Warning:** **Deprecation Notice:** The `billing_line_item` attribute on `NewLineItemPayment`, `NewLineItemAdjustment`, and `LineItemTransfer` is deprecated. It can return an unrelated charge, because the stored ID belongs to a claim line item, not a billing line item. Use `claim_line_item.billing_line_item` instead. `billing_line_item_id` holds the same claim line item ID as `claim_line_item_id`.
##  Attributes 
###  BasePosting 
Base model for aggregating multiple line item-level transactions (payments, adjustments, transfers) associated with a claim.
Field Name| Type| Description  
---|---|---  
dbid| Integer|   
corrected_posting| BasePosting|   
claim| [Claim](/sdk/data-claim/#claim)|   
payment_collection| PaymentCollection|   
description| String|   
entered_in_error| [CanvasUser](/sdk/data-canvasuser/)|   
created| DateTime|   
modified| DateTime|   
correction_postings| QuerySet[BasePosting]|   
paid_amount| Decimal (computed)| Total paid  
contractual_adjusted_amount| Decimal (computed)| Adjustments marked as write-offs  
non_write_off_adjusted_amount| Decimal (computed)| Non-write-off adjustments  
transferred_amount| Decimal (computed)| Total transferred  
transferred_to_patient_amount| Decimal (computed)| Portion transferred to the patient  
transferred_to_coverage_amount| Decimal (computed)| Portion transferred to another coverage  
adjusted_and_transferred_amount| Decimal (computed)| Combined adjusted and transferred amount  
posted_amount| Decimal (computed)| Total of payments and write-offs  
###  CoveragePosting 
Represents an insurance payment or adjustment associated with a claim's coverage.
Field Name| Type  
---|---  
remittance| BaseRemittanceAdvice  
claim_coverage| [ClaimCoverage](/sdk/data-claim/#claimcoverage)  
crossover_carrier| String  
crossover_id| String  
payer_icn| String  
position_in_era| Integer  
###  PatientPosting 
Represents patient-side payments or adjustments, including links to copays or patient-level discounts.
Field Name| Type| Description  
---|---|---  
claim_patient| [ClaimPatient](/sdk/data-claim/#claimpatient)|   
patient_payment| BulkPatientPosting|   
copay| BulkPatientPosting|   
discounted_amount| Decimal (computed)| Discount applied  
charges_amount| Decimal (computed)| Discount plus paid amount  
###  BulkPatientPosting 
Aggregates bulk patient payments on multiple claims.
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
payment_collection| PaymentCollection|   
total_paid| Decimal|   
created| DateTime|   
modified| DateTime|   
discount| Discount|   
payer| [Patient](/sdk/data-patient/)|   
postings| QuerySet[PatientPosting]|   
copays| QuerySet[PatientPosting]|   
total_posted_amount| Decimal (computed)| Sum of all posted amounts  
discounted_amount| Decimal (computed)| Sum of discounted amounts  
###  BaseRemittanceAdvice 
Represents shared data for both electronic and manual remittance advice.
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
payment_collection| PaymentCollection|   
total_paid| Decimal|   
created| DateTime|   
modified| DateTime|   
transactor| [Transactor](/sdk/data-coverage/#transactor)|   
era_id| String|   
postings| QuerySet[CoveragePosting]|   
total_posted_amount| Decimal (computed)| Sum of all posted amounts  
###  PaymentCollection 
Captures metadata about the method and details of a collected payment.
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
total_collected| Decimal  
method| PostingMethods  
check_number| String  
check_date| Date  
deposit_date| Date  
description| String  
created| DateTime  
modified| DateTime  
postings| QuerySet[BasePosting]  
receipt| [Receipt](/sdk/data-receipt/#receipt)  
###  NewLineItemPayment 
Represents a payment applied to a claim line item.
Field Name| Type  
---|---  
dbid| Integer  
posting| BasePosting  
billing_line_item| [BillingLineItem](/sdk/data-billing-line-item/) (deprecated)  
claim_line_item| [ClaimLineItem](/sdk/data-claim/#claimlineitem)  
amount| Decimal  
charged| Decimal  
entered_in_error| [CanvasUser](/sdk/data-canvasuser/)  
created| DateTime  
modified| DateTime  
###  NewLineItemAdjustment 
Represents an adjustment applied to a claim line item.
Field Name| Type  
---|---  
dbid| Integer  
posting| BasePosting  
billing_line_item| [BillingLineItem](/sdk/data-billing-line-item/) (deprecated)  
claim_line_item| [ClaimLineItem](/sdk/data-claim/#claimlineitem)  
amount| Decimal  
code| String  
group| String  
deviated_from_posting_ruleset| Boolean  
write_off| Boolean  
entered_in_error| [CanvasUser](/sdk/data-canvasuser/)  
created| DateTime  
modified| DateTime  
###  LineItemTransfer 
Represents a transfer of a claim line item balance to another coverage or patient.
Field Name| Type  
---|---  
dbid| Integer  
posting| BasePosting  
billing_line_item| [BillingLineItem](/sdk/data-billing-line-item/) (deprecated)  
claim_line_item| [ClaimLineItem](/sdk/data-claim/#claimlineitem)  
amount| Decimal  
code| String  
group| String  
deviated_from_posting_ruleset| Boolean  
transfer_to| [ClaimCoverage](/sdk/data-claim/#claimcoverage)  
transfer_to_patient| Boolean  
entered_in_error| [CanvasUser](/sdk/data-canvasuser/)  
created| DateTime  
modified| DateTime  
###  Discount 
Represents a discount applied to a claim or patient posting, linked by adjustment group and code.
Field Name| Type  
---|---  
dbid| Integer  
name| String  
adjustment_group| String  
adjustment_code| String  
discount| Decimal  
created| DateTime  
modified| DateTime  
patient_postings| QuerySet[BulkPatientPosting]  
##  Enumeration types 
###  PostingMethods 
Value| Label  
---|---  
cash| Cash  
check| Check  
card| Card  
other| Other

---

# Practice Location

Source: https://docs.canvasmedical.com/sdk/data-practicelocation/

##  Introduction 
The `PracticeLocation` model lists all the clinical practice locations that fall under an [Organization](/sdk/data-organization).
##  Basic usage 
To query a `PracticeLocation` by name, the `filter` method can be used like so:
    ```python
    from canvas_sdk.v1.data.practicelocation import PracticeLocation
    practice_location = PracticeLocation.objects.filter(full_name__icontains="downtown")
    ```
To retrieve a list of all practice locations:
    ```python
    from canvas_sdk.v1.data.practicelocation import PracticeLocation
    practice_locations = PracticeLocation.objects.all()
    ```
To query addresses that are associated with a `PracticeLocation`, related `PracticeLocationAddress` model instances can be accessed by using the `addresses` attribute. For exmample:
    ```python
    from canvas_sdk.v1.data.practicelocation import PracticeLocation
    practice_location = PracticeLocation.objects.first()
    practice_location_addresses = practice_location.addresses.all()
    ```
Each `PracticeLocation` has location-specific settings that control certain behavior within the EMR application. To retrieve the available settings for a `PracticeLocation` instance, the `settings` attribute can be used to retrieve a list of names:
    ```python
    from canvas_sdk.v1.data.practicelocation import PracticeLocation
    practice_location = PracticeLocation.objects.first()
    available_settings = practice_location.settings.values_list('name', flat=True)
    ```
Additionally, a setting's value can be found by accessing the `value` attribute on the `PracticeLocationSetting`:
    ```python
    from canvas_sdk.v1.data.practicelocation import PracticeLocation
    practice_location = PracticeLocation.objects.first()
    preferred_lab_partner_text = practice_location.settings.get(name="preferredLabPartner").value
    ```
Please note that the content of each `value` field can contain any value that is JSON-serializable, which includes string values. This means that `value` could be any of the Python types `string`, `list` or `dict`.
##  Attributes 
###  PracticeLocation 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
organization| [Organization](/sdk/data-organization/#organization)  
place_of_service_code| String  
full_name| String  
short_name| String  
background_image_url| String  
background_gradient| String  
active| Boolean  
npi_number| String  
bill_through_organization| Boolean  
tax_id| String  
tax_id_type| [TaxIDType](/sdk/data-enumeration-types/#taxidtype)  
billing_location_name| String  
group_npi_number| String  
taxonomy_number| String  
include_zz_qualifier| Boolean  
addresses| PracticeLocationAddress  
settings| PracticeLocationSetting  
telecom| PracticeLocationContactPoint  
###  PracticeLocationAddress 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
practice_location| PracticeLocation  
line1| String  
line2| String  
city| String  
district| String  
state_code| String  
postal_code| String  
use| [AddressUse](/sdk/data-enumeration-types/#addressuse)  
type| [AddressType](/sdk/data-enumeration-types/#addresstype)  
longitude| Float  
latitude| Float  
start| Date  
end| Date  
country| String  
state| [AddressState](/sdk/data-enumeration-types/#addressstate)  
###  PracticeLocationSetting 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
practice_location| PracticeLocation  
name| String  
value| JSON  
##  PracticeLocationContactPoint 
The `PracticeLocationContactPoint` model represents a contact method (such as phone, email, or fax) for a Practice Location. Multiple contact points can be associated with a single Practice Location, each with its own type, use, and status.
###  Attributes 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
practice_location| PracticeLocation  
system| [ContactPointSystem](/sdk/data-enumeration-types/#contactpointsystem)  
value| String  
use| [ContactPointUse](/sdk/data-enumeration-types/#contactpointuse)  
use_notes| String  
rank| Integer  
state| [ContactPointState](/sdk/data-enumeration-types/#contactpointstate)

---

# PrescriptionChangeRequest

Source: https://docs.canvasmedical.com/sdk/data-prescription-change-request/

##  Introduction 
The `PrescriptionChangeRequest` model represents an incoming Surescripts (NCPDP SCRIPT) request to change a prescription — for example, a generic substitution, a prior-authorization requirement, or a script clarification. Each request carries the raw request payload in its `content` attribute, the medication codings that describe the drug in question (`PrescriptionChangeRequestCoding`), and a reference to the original prescription it relates to.
Because a `PrescriptionChangeRequest` originates from the pharmacy, its `patient`, `note`, and `staff` associations are nullable and may be unset. The provider's approve/deny decision is recorded as a [PrescriptionChangeResponse](/sdk/data-prescription-change-response/), which links back to the request and is available through the request's `response` reverse relation.
##  Basic usage 
To get a prescription change request by identifier, use the `get` method on the `PrescriptionChangeRequest` model manager:
    ```python
    from canvas_sdk.v1.data import PrescriptionChangeRequest
    change_request = PrescriptionChangeRequest.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    ```
##  Related data 
A change request's medication codings are available through the `codings` reverse relation, and the responses recorded against it are available through the `response` reverse relation:
    ```python
    from canvas_sdk.v1.data import PrescriptionChangeRequest
    from logger import log
    change_request = PrescriptionChangeRequest.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    for coding in change_request.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    responses = change_request.response.all()
    ```
The `PrescriptionChangeRequestCoding` entries represent the coding of the medication in question (for example, FDB or RxNorm), with an unstructured fallback whose `display` carries the drug description text when no structured code is available.
##  Message content 
The `message_id` and `content` attributes carry the details of the inbound eRx message.
`message_id` is the eRx (NCPDP SCRIPT / Surescripts) message identifier of the inbound change request.
`content` is a JSON field holding the parsed inbound NCPDP SCRIPT change-request payload. It is a free-form, unstructured representation whose exact shape can vary between messages, typically including the pharmacy, the prescriber as reported by the sender, and the dispensed medication details (drug description, NDC, quantity, and similar). `content` defaults to an empty object (`{}`), so it is safe to call `.get()` on, but individual keys may be absent — plugins should access it defensively.
##  Change types 
The `type_code` attribute identifies the kind of change the pharmacy is requesting:
Code| Description  
---|---  
G| Generic Substitution  
P| Prior Authorization Required  
S| Therapeutic Interchange/Substitution  
D| Drug Use Evaluation  
S| Script Clarification  
OS| Pharmacy is out of stock  
U| Prescriber Authorization  
`S` really does carry two meanings. Canvas maps it to both Therapeutic Interchange/Substitution and Script Clarification, so the two are indistinguishable from `type_code` alone.
The `sub_type_code` attribute further qualifies the request. It is nullable and currently supports:
Code| Description  
---|---  
A| Confirm Prescriber State License  
##  Attributes 
###  PrescriptionChangeRequest 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
staff| [Staff](/sdk/data-staff/#staff)  
message_id| String  
original_prescription| [Prescription](/sdk/data-prescription/#prescription)  
type_code| PrescriptionChangeRequestType  
sub_type_code| PrescriptionChangeRequestSubType  
content| JSON  
codings| PrescriptionChangeRequestCoding[]  
response| [PrescriptionChangeResponse](/sdk/data-prescription-change-response/)[]  
###  PrescriptionChangeRequestCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
change_request| PrescriptionChangeRequest  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
##  Enumeration types 
###  PrescriptionChangeRequestType 
Name| Value| Label  
---|---|---  
GENERIC| G| Generic Substitution  
PRIOR| P| Prior Authorization Required  
SUBSTITUTION| S| Therapeutic Interchange/Substitution  
DRUG| D| Drug Use Evaluation  
OUTOFSTOCK| OS| Pharmacy is out of stock  
AUTHORIZATION| U| Prescriber Authorization  
###  PrescriptionChangeRequestSubType 
Name| Value| Label  
---|---|---  
LICENSE| A| Confirm Prescriber State License

---

# PrescriptionChangeResponse

Source: https://docs.canvasmedical.com/sdk/data-prescription-change-response/

##  Introduction 
The `PrescriptionChangeResponse` model is the anchor for the ApproveChange and DenyChange commands — a response to a Surescripts prescription change request, recorded on a Note.
##  Basic usage 
To get a prescription change response by identifier, use the `get` method on the `PrescriptionChangeResponse` model manager:
    ```python
    from canvas_sdk.v1.data import PrescriptionChangeResponse
    response = PrescriptionChangeResponse.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the prescription change responses for a patient can be accessed with the `prescription_change_responses` attribute:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    responses = patient.prescription_change_responses.all()
    ```
The same attribute is available on a medication:
    ```python
    from canvas_sdk.v1.data import Medication
    medication = Medication.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    responses = medication.prescription_change_responses.all()
    ```
##  Committed records 
The `committed` method returns responses that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import PrescriptionChangeResponse
    committed_responses = PrescriptionChangeResponse.objects.committed()
    ```
##  Attributes 
###  PrescriptionChangeResponse 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
medication| [Medication](/sdk/data-medication)  
response_type| PrescriptionChangeResponseType  
status| PrescriptionChangeResponseStatus  
denied_medication| String  
refills| Integer  
note_to_pharmacist| String  
approved_drug_index| Integer  
reason_code| String  
message_id| String  
prior_authorization_number| String  
request| [PrescriptionChangeRequest](/sdk/data-prescription-change-request/)  
##  Enumeration types 
###  PrescriptionChangeResponseType 
Name| Value  
---|---  
APPROVED| A  
DENIED| D  
###  PrescriptionChangeResponseStatus 
Name| Value  
---|---  
OPEN| open  
PENDING| pending  
ULTIMATELY_ACCEPTED| ultimately-accepted  
ERROR| error  

---

# Prescription

Source: https://docs.canvasmedical.com/sdk/data-prescription/

##  Introduction 
The `Prescription` model represents a prescription for a medication that has been written for a patient. Prescriptions track the full lifecycle of a medication order, including dosage details, pharmacy information, and electronic prescribing status.
##  Basic usage 
To get a prescription by identifier, use the `get` method on the `Prescription` model manager:
    ```python
    from canvas_sdk.v1.data.prescription import Prescription
    prescription = Prescription.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the prescriptions for a patient can be accessed with the `prescriptions` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    prescriptions = patient.prescriptions.all()
    ```
If you have a patient ID, you can get the prescriptions for the patient with the `for_patient` method on the `Prescription` model manager:
    ```python
    from canvas_sdk.v1.data.prescription import Prescription
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    prescriptions = Prescription.objects.for_patient(patient_id)
    ```
##  Filtering 
Prescriptions can be filtered by any attribute that exists on the model.
Filtering for prescriptions is done with the `filter` method on the `Prescription` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.prescription import Prescription, PrescriptionStatus
    prescriptions = Prescription.objects.filter(status=PrescriptionStatus.OPEN)
    ```
    ```python
    from canvas_sdk.v1.data.prescription import Prescription, PrescriptionResponse
    approved_prescriptions = Prescription.objects.filter(response_type=PrescriptionResponse.APPROVED)
    ```
###  Active prescriptions 
The `active` method returns committed prescriptions that have not been denied:
    ```python
    from canvas_sdk.v1.data.prescription import Prescription
    active_prescriptions = Prescription.objects.active()
    ```
###  Committed prescriptions 
The `committed` method returns prescriptions that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.prescription import Prescription
    committed_prescriptions = Prescription.objects.committed()
    ```
##  Combined sig 
The `combined_sig` property returns a prescription's sig — its directions for use — as a string. It returns `sig_original_input`, and when `maximum_daily_dose` is set, `combined_sig` appends `. Maximum Daily Dose: {maximum_daily_dose}` to the sig. For example, a prescription with the sig `1 tab bid` and a maximum daily dose of `2 tabs` returns `1 tab bid. Maximum Daily Dose: 2 tabs`. When `maximum_daily_dose` is not set, `combined_sig` returns `sig_original_input` unchanged. When the prescription has no sig, `combined_sig` returns an empty string. Because `combined_sig` is a property computed in Python, it is read from each `Prescription` object and is not available to a queryset `.filter()` or `.order_by()`.
    ```python
    from canvas_sdk.v1.data.prescription import Prescription
    prescription = Prescription.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    sig = prescription.combined_sig  # "" when the prescription has no sig
    ```
An active prescription's `combined_sig` is one of the sources a medication's [`latest_sig`](/sdk/data-medication/#latest-sig) draws on, alongside its change medications and medication statements. To get the most recent sig for the medication, read `latest_sig` from the referenced medication:
    ```python
    from canvas_sdk.v1.data.prescription import Prescription
    prescription = Prescription.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    sig = prescription.medication.latest_sig
    ```
##  Attributes 
###  Prescription 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
patient| [Patient](/sdk/data-patient/)|   
note| [Note](/sdk/data-note/)|   
assessment| [Assessment](/sdk/data-assessment/#assessment)|   
prescriber| [Staff](/sdk/data-staff/)|   
supervising_provider| [Staff](/sdk/data-staff/)|   
medication| [Medication](/sdk/data-medication/)|   
compound_medication| [CompoundMedication](/sdk/data-compound-medication/)|   
previous_medication| [Medication](/sdk/data-medication/)|   
indications| [Assessment](/sdk/data-assessment/)[]|   
related_refill| Prescription|   
refill_request| [RefillRequest](/sdk/data-refill-request/)|   
status| PrescriptionStatus|   
response_type| PrescriptionResponse|   
is_refill| Boolean|   
is_adjustment| Boolean|   
is_epcs| Boolean|   
generic_substitutions_allowed| Boolean|   
written_date| DateTime|   
dispensed_date| DateTime|   
end_date| Date|   
end_date_original_input| String|   
sig_original_input| String|   
dose_form| String|   
dose_route| String|   
dose_quantity| Float|   
dose_frequency| Float|   
dose_frequency_interval| String|   
maximum_daily_dose| String|   
combined_sig| String (computed)| See Combined sig  
potency_quantity| Float|   
dispense_quantity| Float|   
duration_in_days| Integer|   
count_of_refills_allowed| Integer|   
note_to_pharmacist| String|   
pharmacy_name| String|   
pharmacy_ncpdp_id| String|   
pharmacy_address| String|   
pharmacy_phone_number| String|   
pharmacy_fax_number| String|   
pharmacy_is_read_only| Boolean|   
message_id| String|   
prescription_order_number| String|   
reason_code| String|   
error_message| String|   
entered_in_error| [CanvasUser](/sdk/data-canvasuser)|   
committer| [CanvasUser](/sdk/data-canvasuser)|   
originator| [CanvasUser](/sdk/data-canvasuser)|   
created| DateTime|   
modified| DateTime|   
cancel_prescriptions| [CancelPrescription](/sdk/data-cancel-prescription/#cancelprescription)[]|   
change_requests| [PrescriptionChangeRequest](/sdk/data-prescription-change-request/#prescriptionchangerequest)[]|   
##  Enumeration types 
###  PrescriptionStatus 
Enum| Value| Label  
---|---|---  
OPEN| open| Open  
PENDING| pending| Pending  
ACCEPTED| ultimately-accepted| Ultimately Accepted  
ERROR| error| Error  
CANCEL_REQUESTED| cancel-requested| Cancel Requested  
CANCELED| canceled| Canceled  
CANCEL_DENIED| cancel-denied| Cancel Denied  
RECEIVED| received| Received by DrFirst  
SIGNED| signed| Signed  
INQUEUE| inqueue| In Queue  
TRANSMITTED| transmitted| Transmitted  
DELIVERED| delivered| Delivered  
###  PrescriptionResponse 
Enum| Value| Label  
---|---|---  
APPROVED| A| Approved  
APPROVED_WITH_CHANGES| C| Approved with changes  
DENIED| D| Denied  
DENIED_PRESCRIPTION_TO_FOLLOW| N| Denied, new prescription to follow  

---

# Procedure

Source: https://docs.canvasmedical.com/sdk/data-procedure/

##  Introduction 
The `Procedure` model represents a procedure performed on or ordered for a patient. It is the data model behind the Perform command, is always associated with a Note and a Patient, and has an optional performing provider. Its CPT (or other) codings are available via `codings`.
##  Basic usage 
To get a procedure by identifier, use the `get` method on the `Procedure` model manager:
    ```python
    from canvas_sdk.v1.data.procedure import Procedure
    procedure = Procedure.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient or note object, the procedures for a patient or note can be accessed with the `procedures` attribute:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.v1.data.note import Note
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    procedures = patient.procedures.all()
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    procedures = note.procedures.all()
    ```
If you have a patient ID, you can get the procedures for the patient with the `for_patient` method on the `Procedure` model manager:
    ```python
    from canvas_sdk.v1.data.procedure import Procedure
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    procedures = Procedure.objects.for_patient(patient_id)
    ```
##  Codings 
The codings for a procedure can be accessed with the `codings` attribute on a `Procedure` object:
    ```python
    from canvas_sdk.v1.data.procedure import Procedure
    from logger import log
    procedure = Procedure.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for coding in procedure.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    ```
##  Filtering 
Procedures can be filtered by any attribute that exists on the model.
Filtering for procedures is done with the `filter` method on the `Procedure` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.procedure import Procedure, ProcedureStatus
    procedures = Procedure.objects.filter(status=ProcedureStatus.COMPLETED)
    ```
###  Committed procedures 
The `committed` method returns procedures that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.procedure import Procedure
    committed_procedures = Procedure.objects.committed()
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The `find` method on the model manager is used to perform `ValueSet` filtering:
    ```python
    from canvas_sdk.v1.data.procedure import Procedure
    from canvas_sdk.value_set.v2022.procedure import Colonoscopy
    procedures = Procedure.objects.find(Colonoscopy)
    ```
##  Attributes 
###  Procedure 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
provider| [Staff](/sdk/data-staff/)  
status| ProcedureStatus  
notes| String  
codings| ProcedureCoding[]  
###  ProcedureCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
procedure| Procedure  
##  Enumeration types 
###  ProcedureStatus 
Name| Value| Label  
---|---|---  
IN_PROGRESS| 1| in-progress  
ABORTED| 2| aborted  
COMPLETED| 3| completed  

---

# Protocol Current

Source: https://docs.canvasmedical.com/sdk/data-protocol-current/

##  Introduction 
The `ProtocolCurrent` object represents the current state of clinical protocols applied to patients within Canvas. Protocols are typically structured plans or guidelines that outline specific medical interventions, treatments, or care pathways for managing various health conditions. The `ProtocolCurrent` object contains essential information about the protocol's status, associated patient, and relevant clinical details.
##  Basic Usage 
To get a protocol by identifier, use the `get` method on the `ProtocolCurrent` model manager:
    ```python
    from canvas_sdk.v1.data.protocol_current import ProtocolCurrent
    protocol = ProtocolCurrent.objects.get(id="12345678-1234-1234-1234-123456789012")
    ```
##  Filtering 
    ```python
    from canvas_sdk.v1.data.protocol_current import ProtocolCurrent
    protocols = ProtocolCurrent.objects.filter(status="active", patient_id="b80b1cdc2e6a4aca90ccebc02e683f35")
    ```
##  Attributes 
###  ProtocolResult 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
title| String  
narrative| String  
result_identifiers| Array[String]  
types| Array[String]  
protocol_key| String  
plugin_name| String  
status| String  
due_in| DateTime  
days_of_notice| Integer  
snoozed| Boolean  
sources| Array[String]  
recommendations| Array[String]  
top_recommendation_key| String  
next_review| DateTime  
feedback_enabled| Boolean  
plugin_can_be_snoozed| Boolean  
patient_id| UUID  
result_hash| String  
snooze_date| DateTime

---

# ProtocolOverride

Source: https://docs.canvasmedical.com/sdk/data-protocol-override/

##  Introduction 
The `ProtocolOverride` model represents an instance of a protocol being snoozed for a patient.
##  Basic usage 
To get a protocol override by identifier, use the `get` method on the `ProtocolOverride` model manager:
    ```python
    from canvas_sdk.v1.data.protocol_override import ProtocolOverride
    protocol_override = ProtocolOverride.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the protocol overrides for a patient can be accessed with the `protocol_overrides` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    overrides = patient.protocol_overrides.all()
    ```
If you have a patient ID, you can get the protocol overrides for the patient with the `for_patient` method on the `ProtocolOverride` model manager:
    ```python
    from canvas_sdk.v1.data.protocol_override import ProtocolOverride
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    override = ProtocolOverride.objects.for_patient(patient_id)
    ```
##  Filtering 
Protocol overrides can be filtered by any attribute that exists on the model.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.protocol_override import ProtocolOverride
    overrides = ProtocolOverride.objects.filter(status="active")
    ```
##  Convenience methods 
The `ProtocolOverride` model manager includes convenience methods for the filters plugins most often apply when working with protocol overrides.
`active` returns the overrides whose `status` is `active`:
    ```python
    from canvas_sdk.v1.data.protocol_override import ProtocolOverride
    active_overrides = ProtocolOverride.objects.active()
    ```
`adjustments` returns the adjustment overrides (`is_adjustment=True`) for a given protocol key, and `snoozes` returns the snooze overrides (`is_snooze=True`) for a given protocol key:
    ```python
    from canvas_sdk.v1.data.protocol_override import ProtocolOverride
    adjustments = ProtocolOverride.objects.adjustments("HCC001v1")
    snoozes = ProtocolOverride.objects.snoozes("HCC001v1")
    ```
Each method returns a queryset, so you can chain them with `for_patient`, `committed`, and with one another. For example, to get the active adjustments for a given patient and protocol key:
    ```python
    from canvas_sdk.v1.data.protocol_override import ProtocolOverride
    adjustments = (
        ProtocolOverride.objects
        .for_patient("1eed3ea2a8d546a1b681a2a45de1d790")
        .committed()
        .active()
        .adjustments("HCC001v1")
    )
    ```
##  Attributes 
###  ProtocolOverride 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
protocol_key| String  
is_adjustment| Boolean  
reference_date| DateTime  
cycle_in_days| Integer  
is_snooze| Boolean  
snooze_date| Date  
snoozed_days| Integer  
snooze_comment| String  
narrative| String  
cycle_quantity| Integer  
cycle_unit| IntervalUnit  
status| Status  
##  Enumeration types 
###  IntervalUnit 
Value| Label  
---|---  
days| days  
months| months  
years| years  
###  Status 
Value| Label  
---|---  
active| active  
inactive| inactive  

---

# Questionnaire

Source: https://docs.canvasmedical.com/sdk/data-questionnaire/

##  Introduction 
The `Questionnaire` model represents a structured set of questions intended to guide the collection of answers from end-users.
The `Interview` model represents answers to a structured set of questions represented by a `Questionnaire`.
##  Basic usage 
To get a questionnaire or interview by identifier, use the `get` method on the `Questionnaire` or `Interview` model managers:
    ```python
    from canvas_sdk.v1.data.questionnaire import Interview, Questionnaire
    questionnaire = Questionnaire.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    interview = Interview.objects.get(id="75df6d7f-d58d-443b-9fa0-ce43b4d7b2a0")
    ```
If you have a patient object, the interviews for a patient can be accessed with the `interviews` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    interviews = patient.interviews.all()
    ```
If you have a patient ID, you can get the interviews for the patient with the `for_patient` method on the `Interview` model manager:
    ```python
    from canvas_sdk.v1.data.questionnaire import Interview
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    interviews = Interview.objects.for_patient(patient_id)
    ```
##  Questionnaire questions 
The questions for a questionnaire can be accessed with the `questions` attribute on an `Questionnaire` object:
    ```python
    from canvas_sdk.v1.data.questionnaire import Questionnaire
    from logger import log
    questionnaire = Questionnaire.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for question in questionnaire.questions.all():
        log.info(f"system: {question.code_system}")
        log.info(f"code: {question.code}")
        log.info(f"name: {question.name}")
    ```
##  Interview responses 
The interview responses for an interview can be accessed with the `interview_responses` attribute on an `Interview` object:
    ```python
    from canvas_sdk.v1.data.questionnaire import Interview
    from logger import log
    interview = Interview.objects.get(id="75df6d7f-d58d-443b-9fa0-ce43b4d7b2a0")
    for interview_response in interview.interview_responses.all():
        log.info(f"response option: {interview_response.response_option_value}")
    ```
> **Info:** A date question writes its answer to `response_option_date` as a real date, and to `response_option_value` as the same date in ISO-8601 form. Use `response_option_date` to compare or to filter, because date lookups such as `__gte` and `__year` work only on it. It is `None` for every other question type, and also when nobody answered the date question.
##  Filtering 
Questionnaires and interviews can be filtered by any attribute that exists on the models.
Filtering for questionnaires and interviews is done with the `filter` method on the `Questionnaire` and `Interview` model managers.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.questionnaire import Interview, Questionnaire
    questionnaires = Questionnaire.objects.filter(name="Tobacco")
    interviews = Interview.objects.filter(progress_status="F")
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The `find` method on the model manager is used to perform `ValueSet` filtering:
    ```python
    from canvas_sdk.v1.data.questionnaire import Questionnaire
    from canvas_sdk.value_set.v2022.assessment import TobaccoUseScreening
    questionnaires = Questionnaire.objects.find(TobaccoUseScreening)
    ```
`Interview` also supports `find`, which returns the interviews whose questionnaire has a code in the value set:
    ```python
    from canvas_sdk.v1.data.questionnaire import Interview
    from canvas_sdk.value_set.v2022.assessment import TobaccoUseScreening
    interviews = Interview.objects.find(TobaccoUseScreening)
    ```
For interviews, `find` matches against the related `Questionnaire` through the `questionnaires` relation. Questionnaires store their code system by name (for example, `"LOINC"`) rather than by URL, and `find` handles this for you. It also composes with `for_patient`:
    ```python
    from canvas_sdk.v1.data.questionnaire import Interview
    from canvas_sdk.value_set.v2022.assessment import TobaccoUseScreening
    interviews = (
        Interview.objects
        .for_patient("1eed3ea2a8d546a1b681a2a45de1d790")
        .find(TobaccoUseScreening)
    )
    ```
##  Attributes 
###  ResponseOptionSet 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
status| String  
name| String  
code_system| String  
code| String  
type| String — one of the question types below  
use_in_shx| Boolean  
options| ResponseOption[]  
questions| Question[]  
####  Question types 
`type` holds the code for the kind of question the option set describes. It decides how the question renders in a note and which value an answer carries.
`type`| Question| Answer  
---|---|---  
`TXT`| Free text| Text, on the response's `response_option_value`.  
`INT`| Integer| A whole number.  
`DEC`| Decimal| A decimal number.  
`DATE`| Date| A calendar date, on the response's `response_option_date`.  
`SING`| Single select| One ResponseOption.  
`MULT`| Multi select| One or more ResponseOption records.  
`TXT` and `DATE` questions are not scored, so they are skipped when a questionnaire calculates a score. Authoring a questionnaire in a plugin sets this through the question's `responses_type` — see [Response types](/sdk/effect-questionnaires/#response-types).
###  ResponseOption 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
status| String  
name| String  
code| String  
code_description| String  
value| String  
response_option_set| ResponseOptionSet  
ordering| Integer  
interview_responses| InterviewQuestionResponse[]  
enablement_conditions| QuestionEnablementCondition[]  
`enablement_conditions` holds the conditions that test for this response option, which is how you find the questions a given answer unlocks.
###  Question 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
status| String  
name| String  
response_option_set| ResponseOptionSet  
acknowledge_only| Boolean  
show_prologue| Boolean  
code_system| String  
code| String  
enable_behavior| String — `all` or `any`  
interview_responses| InterviewQuestionResponse[]  
dependent_conditions| QuestionEnablementCondition[]  
triggers_condition| QuestionEnablementCondition[]  
`enable_behavior` decides whether all of the question's enablement conditions must be met for it to be enabled, or only one of them. It is empty on a question authored without an `enabled_behavior`, so handle an empty value when reading it.
The read-side attribute here is `enable_behavior` (no "d"). When authoring a questionnaire through the effect or the manifest schema, the matching config field is spelled `enabled_behavior` (with a "d"). The difference is intentional.
A question sits on both sides of the branching, so it carries a relation for each direction:
  - `dependent_conditions`: the conditions that decide whether this question is enabled.
  - `triggers_condition`: the conditions on other questions that test this question's answer.
###  QuestionEnablementCondition 
A `QuestionEnablementCondition` controls when a `Question` is enabled, following FHIR's `enableWhen` pattern. Import it with `from canvas_sdk.v1.data import QuestionEnablementCondition`. Here `question` is the question the condition governs, and `dependent_on` is the question whose answer is tested.
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
status| String  
question| Question  
dependent_on| Question  
operator| String — `=`, `!=`, `exists`, or `not_exists`  
answer_option| ResponseOption  
answer_value| String  
`operator` takes the same comparison operators as a questionnaire's enabled conditions (see [Enablement operators](/sdk/effect-questionnaires/#enablement-operators)). `answer_option` references the ResponseOption matched, the read-side counterpart of a condition's `value_code`; `answer_value` holds a literal value matched, the counterpart of a condition's `value_string`.
###  Questionnaire 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
status| String  
name| String  
expected_completion_time| Float  
can_originate_in_charting| Boolean  
use_case_in_charting| String  
scoring_function_name| String  
scoring_code_system| String  
scoring_code| String  
code_system| String  
code| String  
search_tags| String  
questions| Question[]  
use_in_shx| Boolean  
carry_forward| String  
interview_responses| InterviewQuestionResponse[]  
###  QuestionnaireQuestionMap 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
status| String  
questionnaire| Questionnaire  
question| Question  
###  Interview 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
status| String  
name| String  
language_id| Integer  
use_case_in_charting| String  
patient| [Patient](/sdk/data-patient/#patient)  
note_id| Integer  
appointment_id| Integer  
questionnaires| Questionnaire[]  
progress_status| String  
created| DateTime  
modified| DateTime  
interview_responses| InterviewQuestionResponse[]  
assessment_set| [Assessment](/sdk/data-assessment/#assessment)[]  
###  InterviewQuestionnaireMap 
The join between an Interview and the questionnaires it covers. Reach them through the interview's `questionnaires` attribute rather than querying this model.
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
status| String  
interview| Interview  
questionnaire| Questionnaire  
###  InterviewQuestionResponse 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
status| String  
interview| Interview  
questionnaire| Questionnaire  
question| Question  
response_option| ResponseOption  
response_option_value| String  
response_option_date| Date  
questionnaire_state| String  
interview_state| String  
comment| String  

---

# ReasonForVisit

Source: https://docs.canvasmedical.com/sdk/data-reason-for-visit/

##  Introduction 
This page covers three models:
  - `ReasonForVisit` — a Reason for Visit recorded on a note, and the anchor for the [Reason for Visit](/sdk/commands/#reasonforvisit) command.
  - `ReasonForVisitCoding` — the codings on a recorded Reason for Visit.
  - `ReasonForVisitSettingCoding` — the configured codings an instance offers, used to populate the coding field when a Reason for Visit is recorded.
##  ReasonForVisit 
A `ReasonForVisit` is always associated with a note and a patient. To get one by identifier:
    ```python
    from canvas_sdk.v1.data import ReasonForVisit
    rfv = ReasonForVisit.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
From a patient or a note, use the `reasons_for_visit` attribute:
    ```python
    from canvas_sdk.v1.data import Note, Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    reasons = patient.reasons_for_visit.all()
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    reasons = note.reasons_for_visit.all()
    ```
###  Reading the narrative 
The text is exposed through the `narrative` property, which returns the free-text value when there is one and otherwise renders the structured `narrative_json`:
    ```python
    from canvas_sdk.v1.data import ReasonForVisit
    rfv = ReasonForVisit.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    text = rfv.narrative
    ```
###  Commit state 
The Reason for Visit command has no commit step, so a recorded reason is readable as soon as it exists. Read the records directly, as shown above, rather than filtering for committed ones.
> **Warning:** `committed()` is inherited from the shared queryset for committable models, so it runs against `ReasonForVisit` without raising. It filters on `committer`, a field the Reason for Visit command has no step to populate, so it can return nothing at all. For the actions this command does support, see the command types table under [Commands](/sdk/effects/#commands) in Effects.
###  Codings 
Each `ReasonForVisit` exposes its codings through `codings`:
    ```python
    from canvas_sdk.v1.data import ReasonForVisit
    rfv = ReasonForVisit.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    codings = rfv.codings.all()
    ```
###  Attributes 
####  ReasonForVisit 
Field Name| Type| Description  
---|---|---  
id| UUID| The universally unique identifier for this record.  
dbid| Integer| The database identifier for this record.  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
originator| [CanvasUser](/sdk/data-canvasuser)| The user who originated the command.  
committer| [CanvasUser](/sdk/data-canvasuser)| The user who committed the record, if set. The Reason for Visit command has no commit step, so this field is not reliably populated.  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)| The user who entered the record in error, if it has been.  
patient| [Patient](/sdk/data-patient/#patient)| The patient the reason for visit was recorded for.  
note| [Note](/sdk/data-note)| The note it was recorded on.  
narrative| String| The reason for visit text.  
codings|  _list_|  The `ReasonForVisitCoding` records on this reason for visit.  
####  ReasonForVisitCoding 
Field Name| Type| Description  
---|---|---  
dbid| Integer| The database identifier for this coding record.  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
code| String| The code representing the concept.  
display| String| The human-readable display name for the concept.  
system| String| The coding system.  
version| String| The version of the coding system.  
user_selected| Boolean| Whether a user chose this coding directly.  
reason_for_visit| ReasonForVisit| The reason for visit this coding belongs to.  
##  ReasonForVisitSettingCoding 
The `ReasonForVisitSettingCoding` model represents the coding information used to populate the coding field within a Reason For Visit in Canvas.
###  Basic Usage 
To retrieve a specific coding record by its identifier, use the model manager's `get` method:
    ```python
    from canvas_sdk.v1.data import ReasonForVisitSettingCoding
    rfv_coding = ReasonForVisitSettingCoding.objects.get(id="e2b1e1e3-3f52-4a0a-bb3a-123456789abc")
    ```
You can also filter records by attributes. For example, to get all codings from a specific coding system:
    ```python
    from canvas_sdk.v1.data import ReasonForVisitSettingCoding
    codings = ReasonForVisitSettingCoding.objects.filter(system="http://snomed.info/sct")
    ```
###  Attributes 
####  ReasonForVisitSettingCoding 
Field Name| Type| Description  
---|---|---  
id| UUID| The universally unique identifier for this coding record.  
dbid| Integer| The database identifier for this coding record.  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
code| String| The code representing the concept.  
display| String| The human-readable display name for the concept.  
system| String| The coding system (e.g., `http://snomed.info/sct`).  
version| String| The version of the coding system.  
duration| Array of Duration| An array of durations (as Python `timedelta` objects) associated with the coding.  
user_selected| Boolean| The active/inactive flag for this reason-for-visit coding: `True` = active, `False` = inactive.  

---

# Receipt

Source: https://docs.canvasmedical.com/sdk/data-receipt/

The `Receipt` model represents the single canonical payment receipt Canvas generates for a payment collection. Canvas creates one receipt per [PaymentCollection](/sdk/data-posting/#paymentcollection), and the model exposes that receipt's PDF through a presigned URL.
##  Basic Usage 
    ```python
    from canvas_sdk.v1.data import Receipt
    receipt = Receipt.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    ```
Each receipt belongs to one [PaymentCollection](/sdk/data-posting/#paymentcollection), and you can reach it from the collection through the one-to-one reverse accessor:
    ```python
    from canvas_sdk.v1.data import PaymentCollection
    collection = PaymentCollection.objects.get(id="f47ac10b-58cc-4372-a567-0e02b2c3d479")
    receipt = collection.receipt  # the one-to-one Receipt; raises if the collection has none
    ```
##  Finding a patient's receipts 
A patient-portal plugin should show only the signed-in patient's receipts. A receipt belongs to a [PaymentCollection](/sdk/data-posting/#paymentcollection), and the patient who paid is the `payer` on that collection's [BulkPatientPosting](/sdk/data-posting/#bulkpatientposting), so filter on that path:
    ```python
    from canvas_sdk.v1.data import Patient, Receipt
    patient = Patient.objects.get(id="b80b1cdc2e6a4aca90ccebc02e683f35")
    receipts = Receipt.objects.filter(
        payment_collection__bulkpatientposting__payer=patient,
        entered_in_error__isnull=True,
    )
    ```
##  Accessing the receipt PDF 
The `receipt_url` property returns a presigned S3 URL for the receipt PDF. The URL is valid for one hour and is regenerated on each access, so fetch it at render time rather than persisting or caching it. It returns `None` when the receipt has no PDF. The `receipt` field itself holds the stored file path, not a URL, so use `receipt_url` to link a patient to their PDF.
    ```python
    from canvas_sdk.v1.data import Receipt
    receipt = Receipt.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    url = receipt.receipt_url  # presigned S3 URL (valid for 1 hour), or None
    ```
##  Attributes 
###  Receipt 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
originator| [CanvasUser](/sdk/data-canvasuser/)|   
entered_in_error| [CanvasUser](/sdk/data-canvasuser/)|   
payment_collection| [PaymentCollection](/sdk/data-posting/#paymentcollection)|   
account_balance_before_collection| Decimal|   
account_balance_after_collection| Decimal|   
discount| Decimal|   
receipt| String|   
receipt_url| String (computed)| Presigned S3 URL for the receipt PDF, valid for 1 hour, or `None` while the PDF is still being generated  
total_posted_amount| Decimal (computed)| Sum of the payments and write-off adjustments across the payment collection's active postings  
copay_amount| Decimal (computed)| Amount posted as copays with the payment collection  
  - `account_balance_before_collection` and `account_balance_after_collection` are snapshots of the patient's account balance taken when the receipt was generated. They don't change as the balance changes.
  - `discount` is the discount amount recorded on the receipt, or `0.00` when no discount was applied.

---

# Reference

Source: https://docs.canvasmedical.com/sdk/data-reference/

##  Introduction 
The `Reference` model is the record of a diagnostic view embedded in a note, created when the [Reference](/sdk/commands/#reference) command is originated, for example when a clinician adds a diagnostic view to a note through diagnostic theater, or a plugin originates a `ReferenceCommand`. It captures a snapshot of the referenced diagnostic view's rendered table. The command creates the reference record when it is originated, and commits it when the command is committed.
##  Basic usage 
To get a reference by identifier, use the `get` method on the `Reference` model manager:
    ```python
    from canvas_sdk.v1.data import Reference
    reference = Reference.objects.get(id="a1b2c3d4-e5f6-7890-abcd-ef1234567890")
    ```
If you have a patient object, the references for a patient can be accessed with the `references` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    references = patient.references.all()
    ```
If you have a note object, the references on that note can be accessed with the `references` attribute on a `Note` object:
    ```python
    from canvas_sdk.v1.data import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    references = note.references.all()
    ```
##  Committed references 
A reference stays staged until its command is committed, so it can exist in an uncommitted state while the command is staged. The basic-usage queries above return staged and committed references together. Use the `committed` method to get only references that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import Reference
    committed = Reference.objects.committed()
    ```
##  Attributes 
###  Reference 
Field Name| Type| Description  
---|---|---  
id| UUID| The universally unique identifier for this record.  
dbid| Integer| The database identifier for this record.  
created| DateTime| When the record was created.  
modified| DateTime| When the record was last modified.  
originator| [CanvasUser](/sdk/data-canvasuser)| The user who originated the command.  
committer| [CanvasUser](/sdk/data-canvasuser)| The user who committed the command, if it has been committed.  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)| The user who entered the record in error, if it has been.  
patient| [Patient](/sdk/data-patient/#patient)| The patient the reference was recorded for.  
note| [Note](/sdk/data-note/#note)| The note it was recorded on.  
diagnostic_view| [DiagnosticView](/sdk/data-diagnostic-view/#diagnosticview)| The diagnostic view that was referenced. May be null if no view was set when the command was originated, or if the supplied view id did not match a diagnostic view on the instance and was discarded.  
name| String (up to 100 characters)| The label shown on the note, captured at origination. May be an empty string. Derived from the diagnostic view when the command is originated and not recalculated if the command is later pointed at a different diagnostic view with `edit()`.  
content| JSON| A snapshot of the referenced diagnostic view's rendered table, captured when the reference was created and not updated if the command is later pointed at a different diagnostic view with `edit()`.

---

# Referral

Source: https://docs.canvasmedical.com/sdk/data-referral/

##  Introduction 
The `Referral`, `ReferralReport`, and `ReferralReview` models represent referral results and their reviews.
##  Basic Usage 
To retrieve a `Referral`, `ReferralReport`, or `ReferralReview` by identifier, use the `get` method on the model manager:
    ```python
    from canvas_sdk.v1.data.referral import Referral, ReferralReport, ReferralReview
    referral = Referral.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    referral_report = ReferralReport.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    referral_review = ReferralReview.objects.get(id="b3e6f74c-2a1b-4c8d-9f2e-31842ae7d3b9")
    ```
If you have a patient object, the referrals, reports, and reviews can be accessed with the `referral_set`, `referral_reports`, and `referral_reviews` attributes, respectively on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    referrals = patient.referral_set.all()
    reports = patient.referral_reports.all()
    reviews = patient.referral_reviews.all()
    ```
##  Filtering 
Referrals, reports, and reviews can be filtered by any attribute that exists on the models.
Filtering is done with the `filter` method on the `Referral`, `ReferralReport`, and `ReferralReview` model managers.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.referral import Referral, ReferralReport, ReferralReview
    referrals = Referral.objects.filter(priority="urgent")
    reports = ReferralReport.objects.filter(requires_signature=True)
    reviews = ReferralReview.objects.filter(status="completed")
    ```
###  By ValueSet 
See [Value Sets](/sdk/data-value-sets/) for the library of built-in value sets and how to create your own.
`ReferralReport` supports `ValueSet` filtering through the `find` method on its model manager:
    ```python
    from canvas_sdk.v1.data.referral import ReferralReport
    from canvas_sdk.value_set.v2022.procedure import DialysisServices
    reports = ReferralReport.objects.find(DialysisServices)
    ```
`find` joins through the report's `codings` reverse relation and matches on `(system, code)` pairs from the value set, so a coding must match both the code system and the code to be included.
###  Committed records 
The `committed` method returns `Referral` and `ReferralReview` records that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.referral import Referral, ReferralReview
    committed_referrals = Referral.objects.committed()
    committed_reviews = ReferralReview.objects.committed()
    ```
##  Related Tasks 
To retrieve an Referral's related tasks, use the `get_task_objects` method on the Referral object.
    ```python
    from canvas_sdk.v1.data.referral import Referral
    referral = Referral.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    tasks = referral.get_task_objects().all()
    ```
The `task_list` computed property returns the same related tasks as a `list[Task]`:
    ```python
    from canvas_sdk.v1.data.referral import Referral
    referral = Referral.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    tasks = referral.task_list
    ```
##  Review assignment 
A referral report is assigned for review to staff members or to a team. `reviewers` holds the assigned staff members, and `team` holds the assigned team, or `None` when no team is assigned.
    ```python
    from canvas_sdk.v1.data import ReferralReport, Staff
    referral_report = ReferralReport.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    # The staff members and the team the referral report is assigned to
    reviewers = referral_report.reviewers.all()
    team = referral_report.team
    # Every referral report assigned to this staff member
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    assigned = ReferralReport.objects.filter(reviewers__id=staff.id)
    ```
##  The document reference 
`ReferralReport` carries the consult report's specialty, review state and comments, not the file. Canvas stores the file on a [DocumentReference](/sdk/data-document-reference/#the-related-object) pointing back at the report, which is also how it appears in the FHIR API.
To read it, resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` — never hardcode the per-environment `dbid` — and match `object_id` against the report's `dbid`:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference, ReferralReport
    report = ReferralReport.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    content_type = ContentType.objects.filter(app_label="api", model="referralreport").first()
    document = DocumentReference.objects.filter(
        content_type=content_type, object_id=report.dbid
    ).first()
    url = document.document_url if document else None
    ```
> **Info:** `object_id` holds the related record's integer `dbid`, not its UUID `id`.
##  Attributes 
###  Referral 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note/#note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
assessments| [Assessment](/sdk/data-assessment/#assessment)  
service_provider| [ServiceProvider](/sdk/data-serviceprovider/#service-provider)  
clinical_question| String  
priority| String  
include_visit_note| Boolean  
notes| String  
date_referred| DateTime  
internal_comment| String  
forwarded| Boolean  
ignored| Boolean  
internal_task_comment| [TaskComment](/sdk/data-task/#taskcomment)  
task_ids| String  
reports| ReferralReport[]  
action_events| [ReferralActionEvent](/sdk/data-fax/#referralactionevent)[]  
###  ReferralReport 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
assigned_by| [CanvasUser](/sdk/data-canvasuser)  
review_mode| [DocumentReviewMode](/sdk/data-enumeration-types/#documentreviewmode)  
junked| Boolean  
requires_signature| Boolean  
assigned_date| DateTime  
team_assigned_date| DateTime  
team| [Team](/sdk/data-team/#team)  
reviewers| [Staff](/sdk/data-staff/#staff)[]  
patient| [Patient](/sdk/data-patient/#patient)  
referral| Referral  
specialty| String  
comment| String  
priority| Boolean  
original_date| Date  
review| ReferralReview  
codings| ReferralReportCoding[]  
###  ReferralReview 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
internal_comment| String  
message_to_patient| String  
status| String  
note| [Note](/sdk/data-note/#note)  
patient| [Patient](/sdk/data-patient/#patient)  
patient_communication_method| String  
reports| ReferralReport[]  
###  ReferralReportCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
report| ReferralReport  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  
value| String  

---

# RefillRequest

Source: https://docs.canvasmedical.com/sdk/data-refill-request/

##  Introduction 
The `RefillRequest` model represents an incoming request to refill a patient's medication — for example, a renewal request received electronically from a pharmacy. Each request carries the raw request payload in its `content` attribute, the associated patient and staff member, the medication codings that describe the requested drug (`RefillRequestCoding`), and the prescription(s) written in response.
An incoming `RefillRequest` is routed to a [staff](/sdk/data-staff/#staff) member — the provider expected to respond to it, who becomes the `prescriber` of the responding prescription, not the original requester — and can be marked as `ignored` to drop it from the active refill worklist. Once acted on, the request links to the responding prescription(s) through its `response` attribute, and each [Prescription](/sdk/data-prescription/#prescription) points back to the request through its `refill_request` field. Because the request originates from the pharmacy, and a pharmacy may route it to a provider other than the original prescriber, `staff` is not the requester; it is also nullable, so it may be unset.
##  Basic usage 
To get a refill request by identifier, use the `get` method on the `RefillRequest` model manager:
    ```python
    from canvas_sdk.v1.data.refill_request import RefillRequest
    refill_request = RefillRequest.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    ```
If you have a patient object, the refill requests for a patient can be accessed with the `refill_requests` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    refill_requests = patient.refill_requests.all()
    ```
If you have a patient ID, you can get the refill requests for the patient with the `for_patient` method on the `RefillRequest` model manager:
    ```python
    from canvas_sdk.v1.data.refill_request import RefillRequest
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    refill_requests = RefillRequest.objects.for_patient(patient_id)
    ```
##  Filtering 
Refill requests can be filtered by any attribute that exists on the model.
Filtering is done with the `filter` method on the `RefillRequest` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.refill_request import RefillRequest
    outstanding_requests = RefillRequest.objects.filter(ignored=False)
    ```
The `ignored` attribute is a boolean dismiss flag (default `False`). Marking a request ignored removes it from the active refill worklist and is used to suppress duplicates — for example, a pharmacy re-sending a request. Requests that have already been responded to are excluded from the worklist separately, through their linked `response`. A plugin can filter on `ignored`, but setting it is not available through the data module. The example above returns the active (non-dismissed) requests.
##  Related data 
A refill request's medication codings are available through the `codings` reverse relation, and the prescriptions written in response are available through the `response` reverse relation:
    ```python
    from canvas_sdk.v1.data.refill_request import RefillRequest
    from logger import log
    refill_request = RefillRequest.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    for coding in refill_request.codings.all():
        log.info(f"system:  {coding.system}")
        log.info(f"code:    {coding.code}")
        log.info(f"display: {coding.display}")
    responding_prescriptions = refill_request.response.all()
    ```
The `RefillRequestCoding` entries represent the coding of the requested drug (for example, FDB or RxNorm), with an unstructured fallback whose `display` carries the drug description text when no structured code is available.
##  Message content 
The `message_id` and `content` attributes carry the details of the inbound eRx message.
`message_id` is the eRx (NCPDP SCRIPT / Surescripts) message identifier of the inbound refill-renewal request itself.
`content` is a JSON field holding the parsed inbound NCPDP SCRIPT refill-renewal request payload. It is a free-form, unstructured representation whose exact shape can vary between messages. The information typically available includes:
  - the pharmacy (name, NCPDP ID, phone, address)
  - the prescriber as reported by the sender (name, NPI, SPI, and a sender-supplied identifier)
  - the dispensed and prescribed medication details (drug description, NDC, quantity, days supply, directions, number of refills, substitution allowance, written date, and similar)
  - reference identifiers such as the Rx reference number and the message ID of the original prescription it renews — distinct from this request's own `message_id`
`content` is always a JSON object — it defaults to an empty object (`{}`) when no data was captured — so it is safe to call `.get()` on, but individual keys may be absent. Because the shape is not guaranteed, plugins should access `content` defensively, checking that a key is present before relying on it.
##  Attributes 
###  RefillRequest 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
staff| [Staff](/sdk/data-staff/#staff)  
message_id| String  
ignored| Boolean  
content| JSON  
codings| RefillRequestCoding[]  
response| [Prescription](/sdk/data-prescription/#prescription)[]  
###  RefillRequestCoding 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
refill_request| RefillRequest  
system| String  
version| String  
code| String  
display| String  
user_selected| Boolean  

---

# Remove Allergy Event

Source: https://docs.canvasmedical.com/sdk/data-remove-allergy-event/

##  Introduction 
The `RemoveAllergyEvent` model represents a record of an allergy being removed from a patient's allergy list — the anchor for the [Remove Allergy](/sdk/commands/#removeallergy) command.
##  Basic usage 
To get a remove allergy event by identifier, use the `get` method on the `RemoveAllergyEvent` model manager:
    ```python
    from canvas_sdk.v1.data import RemoveAllergyEvent
    removal = RemoveAllergyEvent.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    ```
If you have a patient object, the remove allergy events for a patient can be accessed with the `removed_allergies` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    removals = patient.removed_allergies.all()
    ```
The same records are reachable from the note they were recorded on, with the `removed_allergies` attribute on a `Note` object:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    removals = note.removed_allergies.all()
    ```
You can also access the removed allergy with the `allergy` attribute:
    ```python
    from canvas_sdk.v1.data import RemoveAllergyEvent
    removal = RemoveAllergyEvent.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    allergy = removal.allergy
    ```
Or for a given allergy, you can access all of its removal events with the `remove_allergy_events` attribute:
    ```python
    from canvas_sdk.v1.data import AllergyIntolerance
    allergy = AllergyIntolerance.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    removals = allergy.remove_allergy_events.all()
    ```
##  Committed records 
The `committed` method returns remove allergy events that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import RemoveAllergyEvent
    committed_removals = RemoveAllergyEvent.objects.committed()
    ```
##  Attributes 
###  RemoveAllergyEvent 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
allergy| [AllergyIntolerance](/sdk/data-allergy-intolerance)  
rationale| String  

---

# Remove Past Medical History Event

Source: https://docs.canvasmedical.com/sdk/data-remove-past-medical-history-event/

##  Introduction 
The `RemovePastMedicalHistoryEvent` model records an entry being removed from a patient's past medical history. It is the anchor for the [Remove Past Medical History](/sdk/commands/#remove-past-medical-history) command. Use it to find which past medical history entries were removed, on which note, and why.
##  Basic usage 
To get a remove past medical history event by identifier, use the `get` method on the `RemovePastMedicalHistoryEvent` model manager:
    ```python
    from canvas_sdk.v1.data import RemovePastMedicalHistoryEvent
    removal = RemovePastMedicalHistoryEvent.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    ```
If you have a patient object, the remove past medical history events for a patient can be accessed with the `removed_past_medical_history` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    removals = patient.removed_past_medical_history.all()
    ```
The same records are reachable from the note they were recorded on, with the `removed_past_medical_history` attribute on a `Note` object:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    removals = note.removed_past_medical_history.all()
    ```
You can also access the removed entry with the `condition` attribute:
    ```python
    from canvas_sdk.v1.data import RemovePastMedicalHistoryEvent
    removal = RemovePastMedicalHistoryEvent.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    condition = removal.condition
    ```
Or for a given condition, you can access all of its removal events with the `past_medical_history_removals` attribute:
    ```python
    from canvas_sdk.v1.data import Condition
    condition = Condition.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    removals = condition.past_medical_history_removals.all()
    ```
##  Filtering 
The `committed` method returns remove past medical history events that have been committed and not entered in error. The `for_patient` method returns the events for one patient. You can chain them:
    ```python
    from canvas_sdk.v1.data import RemovePastMedicalHistoryEvent
    committed_removals = RemovePastMedicalHistoryEvent.objects.committed()
    patient_removals = RemovePastMedicalHistoryEvent.objects.for_patient(
        "1eed3ea2a8d546a1b681a2a45de1d790"
    ).committed()
    ```
##  Attributes 
###  RemovePastMedicalHistoryEvent 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
originator| [CanvasUser](/sdk/data-canvasuser)|   
committer| [CanvasUser](/sdk/data-canvasuser)|   
entered_in_error| [CanvasUser](/sdk/data-canvasuser)|   
patient| [Patient](/sdk/data-patient/#patient)|   
note| [Note](/sdk/data-note)|   
condition| [Condition](/sdk/data-condition)| The removed past medical history entry.  
rationale| String| The reason for the removal, up to 512 characters. Empty when none was given.  

---

# Resolve Condition Event

Source: https://docs.canvasmedical.com/sdk/data-resolve-condition-event/

##  Introduction 
The `ResolveConditionEvent` model represents a record of a condition being resolved — the anchor for the [Resolve Condition](/sdk/commands/#resolve-condition) command.
##  Basic usage 
To get a resolve condition event by identifier, use the `get` method on the `ResolveConditionEvent` model manager:
    ```python
    from canvas_sdk.v1.data import ResolveConditionEvent
    resolution = ResolveConditionEvent.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    ```
If you have a patient object, the resolve condition events for a patient can be accessed with the `resolved_conditions` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    resolutions = patient.resolved_conditions.all()
    ```
The same records are reachable from the note they were recorded on, with the `resolved_conditions` attribute on a `Note` object:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    resolutions = note.resolved_conditions.all()
    ```
You can also access the resolved condition with the `condition` attribute:
    ```python
    from canvas_sdk.v1.data import ResolveConditionEvent
    resolution = ResolveConditionEvent.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    condition = resolution.condition
    ```
Or for a given condition, you can access all of its resolutions with the `resolutions` attribute:
    ```python
    from canvas_sdk.v1.data import Condition
    condition = Condition.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    resolutions = condition.resolutions.all()
    ```
##  Committed records 
The `committed` method returns resolve condition events that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import ResolveConditionEvent
    committed_resolutions = ResolveConditionEvent.objects.committed()
    ```
##  Attributes 
###  ResolveConditionEvent 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
condition| [Condition](/sdk/data-condition)  
rationale| String  
show_in_condition_list| Boolean  

---

# ServiceProvider

Source: https://docs.canvasmedical.com/sdk/data-serviceprovider/

##  Introduction 
A `ServiceProvider` is an external provider or organization — someone outside your practice that a patient's care touches. The same record backs every surface in Canvas where an outside provider gets picked:
  - The contact selected as the recipient of a [Refer](/sdk/commands/#refer) command.
  - The imaging center selected on an [Imaging Order](/sdk/commands/#imagingorder) command.
  - The supplier selected in **Send to** on an Order DME command.
  - An external care team member added to a patient's profile.
  - The recipient of an outbound fax, and the matched sender of an inbound one — Data Integration looks up the sending fax number in the contact directory and links the resulting provider to the incoming document, which is what the `integration_tasks` relation below exposes.
Service providers come from two places. Most are drawn from the shared external contact directory, which is what those surfaces search by default and which you can query yourself with [`GET /contacts/`](/sdk/utils/#searching-for-contacts-and-service-providers). You can also build your own directory: providers created through the [ServiceProvider effect](/sdk/effect-service-provider/) belong to your instance and are flagged with `is_customer_managed`.
Your own providers are not searched automatically. To offer them in one of the surfaces above, handle that surface's search event and return them yourself — see the helpers under Search results below, and [Offering your own providers alongside the directory](/guides/customize-search-results/#offering-your-own-providers-alongside-the-directory) for a worked handler covering all five surfaces.
##  Basic usage 
To retrieve a `ServiceProvider` by identifier, use the `get` method on the model manager:
    ```python
    from canvas_sdk.v1.data.service_provider import ServiceProvider
    service_provider = ServiceProvider.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    ```
To retrieve a service provider from an `ImagingOrder` or a `Referral`
    ```python
    from canvas_sdk.v1.data.imaging import ImagingOrder
    from canvas_sdk.v1.data.referral import Referral
    imaging_order = ImagingOrder.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130003")
    imaging_order_service_provider = imaging_order.imaging_center
    referral = Referral.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130004")
    referral_service_provider = referral.service_provider
    ```
To show a `ServiceProvider` full name or full name with specialty use the properties `full_name` or `full_name_and_specialty`
    ```python
    from canvas_sdk.v1.data.service_provider import ServiceProvider
    service_provider = ServiceProvider.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    full_name = service_provider.full_name
    full_name_and_specialty = service_provider.full_name_and_specialty
    ```
##  Service Provider 
###  Fields 
Name| Type| Description  
---|---|---  
id| UUID| Unique identifier  
dbid| Integer| Internal database identifier  
created| DateTime| When the record was created  
modified| DateTime| When the record was last changed  
first_name| String| Provider name, or the organization name  
last_name| String| Empty for organizations  
business_fax| String|   
business_phone| String|   
business_address| String|   
specialty| String| Free text  
practice_name| String|   
notes| String|   
is_active| Boolean| `False` once deactivated; the provider is kept, not deleted  
npi| String| 10 digits  
direct_address| String| Direct address  
is_customer_managed| Boolean| `True` for providers created through the SDK — see below  
science_contact_id| Integer| The shared directory contact this provider came from, or `None` if it came from none. Not a reliable provenance signal on its own — providers that predate this tracking have no value — so use `is_customer_managed` to identify a customer's own providers.  
imaging_orders| QuerySet[[ImagingOrder](/sdk/data-imaging/#imagingorder)]| Imaging orders sent to this provider  
dme_orders| QuerySet[[DmeOrder](/sdk/data-dme/#dmeorder)]| DME orders sent to this provider  
referrals| QuerySet[[Referral](/sdk/data-referral/#referral)]| Referrals sent to this provider  
integration_tasks| QuerySet[[IntegrationTask](/sdk/data-integration-task/#integrationtask)]| Integration tasks associated with this provider  
##  Customer-managed providers 
`is_customer_managed` is `True` for providers created with the [Service Provider effects](/sdk/effect-service-provider/), and `False` for everything else.
    ```python
    from canvas_sdk.v1.data.service_provider import ServiceProvider
    ServiceProvider.objects.filter(is_customer_managed=True, is_active=True)
    ```
This is also how you find an existing customer-managed provider — to get its `id` — before updating or deactivating it with the [Service Provider effects](/sdk/effect-service-provider/).
##  Search results 
Two helpers shape a provider for the provider-search surfaces, so you do not have to build the payloads yourself. Both take an optional list of annotations, shown next to the result.
Method| Use it for  
---|---  
`as_search_result(annotations=None)`| A command's provider search — `Refer to` on Refer, `Imaging center` on Imaging Order, `Send to` on Order DME  
`as_search_contact(annotations=None)`| The fax recipient and external care team dropdowns  
Both identify the provider, so selecting one attaches to that exact record.
The two helpers return different shapes, and the key casing below matches the serialized payload exactly:
  - `as_search_result(annotations=None)` returns `text`, `value`, `description`, and `annotations` at the top level, plus an `extra.contact` object containing `service_provider_id`, `science_contact_id`, `firstName`, `lastName`, `businessFax`, `businessPhone`, `businessAddress`, `specialty`, `practiceName`, and `notes`.
  - `as_search_contact(annotations=None)` returns a flat object: `id`, `serviceProviderId`, `firstName`, `lastName`, `practiceName`, `specialty`, `businessAddress`, `businessPhone`, `businessFax`, and `annotations`.
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.service_provider import ServiceProvider
    class OwnDirectoryFirst(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.FAX__RECIPIENT__PRE_SEARCH), EventType.Name(EventType.PATIENT_PROFILE__EXTERNAL_CARE_TEAM__PRE_SEARCH)]
        def compute(self):
            term = self.event.context.get("search_term", "").strip()
            if not term:
                return []
            providers = ServiceProvider.objects.filter(
                is_customer_managed=True, first_name__icontains=term
            )
            if not providers:
                return []
            return [
                Effect(
                    type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS,
                    payload=json.dumps(
                        [
                            provider.as_search_contact(
                                [] if provider.is_active else ["Inactive"]
                            )
                            for provider in providers
                        ]
                    ),
                )
            ]
    ```
Both surfaces reply with the same `AUTOCOMPLETE_SEARCH_RESULTS` effect. Only the event you subscribe to and the helper you call differ.
What you return means different things on each surface:
  - **Contact dropdowns, pre-search** — results replace the search; returning nothing runs the normal search instead.
  - **Command searches, post-search** — an empty list clears the results, so return no effect at all when you have nothing to add.

---

# Snapshot

Source: https://docs.canvasmedical.com/sdk/data-snapshot/

#  Snapshot Models 
The `Snapshot` and `SnapshotImage` models represent images captured via the Canvas iOS application or uploaded directly through the coverages modal. A `Snapshot` groups related images together, while each `SnapshotImage` represents an individual image with presigned URL support for secure access.
Snapshots are primarily used for storing coverage card images. You can navigate from a `Coverage` to its `Snapshot` via the `snapshot` field, and from a `Snapshot` back to its `Coverage` via the `coverage` reverse relation.
##  Basic Usage 
    ```python
    from canvas_sdk.v1.data import Snapshot, SnapshotImage
    # Get all snapshots
    snapshots = Snapshot.objects.all()
    # Get a specific snapshot
    snapshot = Snapshot.objects.get(dbid=42)
    # Get images for a snapshot
    images = snapshot.images.all()
    # Get all snapshot images
    all_images = SnapshotImage.objects.all()
    # Get all snapshot images for a specific coverage
    from canvas_sdk.v1.data.coverage import Coverage
    coverage = Coverage.objects.get(id="a74592ae8a6c4d0ebe0799d3fb3713d1")
    if coverage.snapshot:
        images = coverage.snapshot.images.all()
        for image in images:
            print(image.image_url)
    ```
##  Accessing Image Files 
The `image_url` property on `SnapshotImage` returns a presigned S3 URL for securely accessing the image file.
    ```python
    from canvas_sdk.v1.data import SnapshotImage
    image = SnapshotImage.objects.exclude(image="").first()
    # Returns a presigned S3 URL (valid for 1 hour)
    url = image.image_url
    ```
##  Attributes 
###  Snapshot 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
title| String  
description| String  
coverage| [Coverage](/sdk/data-coverage/#coverage)  
images| SnapshotImage[]  
###  SnapshotImage 
Field Name| Type| Description  
---|---|---  
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
snapshot| Snapshot|   
image| String|   
title| String|   
instruction| String|   
tag| String|   
image_url| String (computed)| Presigned S3 URL

---

# Specialty Report Template

Source: https://docs.canvasmedical.com/sdk/data-specialty-report-template/

##  Introduction 
The `SpecialtyReportTemplate`, `SpecialtyReportTemplateField`, and `SpecialtyReportTemplateFieldOption` models represent the templates used for specialty and referral reports. Templates define the structure of a specialty report, including what fields need to be filled in and what options are available for each field. Each template can be associated with a medical specialty via taxonomy codes.
##  Basic Usage 
To retrieve a `SpecialtyReportTemplate` by identifier, use the `get` method on the model manager:
    ```python
    from canvas_sdk.v1.data.specialty_report_template import SpecialtyReportTemplate
    template = SpecialtyReportTemplate.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    ```
To access the fields defined in a template:
    ```python
    from canvas_sdk.v1.data.specialty_report_template import SpecialtyReportTemplate
    template = SpecialtyReportTemplate.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    fields = template.fields.all()
    ```
##  Filtering 
Templates can be filtered by any attribute on the models.
###  By active status 
    ```python
    from canvas_sdk.v1.data.specialty_report_template import SpecialtyReportTemplate
    active_templates = SpecialtyReportTemplate.objects.active()
    ```
###  By type 
    ```python
    from canvas_sdk.v1.data.specialty_report_template import SpecialtyReportTemplate
    # Get custom (user-created) templates
    custom = SpecialtyReportTemplate.objects.custom()
    # Get built-in (system) templates
    builtin = SpecialtyReportTemplate.objects.builtin()
    ```
###  By specialty 
    ```python
    from canvas_sdk.v1.data.specialty_report_template import SpecialtyReportTemplate
    # Filter by specialty taxonomy code
    cardiology = SpecialtyReportTemplate.objects.by_specialty("207RC0000X")
    ```
###  By search 
    ```python
    from canvas_sdk.v1.data.specialty_report_template import SpecialtyReportTemplate
    results = SpecialtyReportTemplate.objects.search("cardiology")
    ```
##  Attributes 
###  SpecialtyReportTemplate 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
name| String  
code| String  
code_system| String  
search_keywords| String  
active| Boolean  
custom| Boolean  
search_as| String  
specialty_name| String  
specialty_code| String  
specialty_code_system| String  
fields| SpecialtyReportTemplateField[]  
###  SpecialtyReportTemplateField 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
report_template| SpecialtyReportTemplate  
sequence| Integer  
code| String  
code_system| String  
label| String  
units| String  
type| String  
required| Boolean  
options| SpecialtyReportTemplateFieldOption[]  
###  SpecialtyReportTemplateFieldOption 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
field| SpecialtyReportTemplateField  
label| String  
key| String  

---

# Staff

Source: https://docs.canvasmedical.com/sdk/data-staff/

##  Introduction 
The `Staff` model represents a staff member in a Canvas instance.
To get a `Staff` object by it's identifier, use the `get` method:
    ```python
    from canvas_sdk.v1.data.staff import Staff
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    ```
To list every staff member, use `Staff.objects.all()`. When you need a stable cross-system mapping, prefer the immutable `dbid` (integer) and `id` (UUID) attributes over names, which can change:
    ```python
    from canvas_sdk.v1.data.staff import Staff
    staff = Staff.objects.all()
    staff_dbids = [s.dbid for s in staff]
    staff_ids = [s.id for s in staff]
    ```
A command's `committer` is a [`CanvasUser`](/sdk/data-canvasuser), not a `Staff` record, so its `dbid` is the user's `dbid` — not the staff `dbid`. To resolve a committer back to the `Staff` record, look it up by `user`, not `dbid`:
    ```python
    from canvas_sdk.v1.data.staff import Staff
    # command_instance.committer is a CanvasUser
    staff = Staff.objects.get(user=command_instance.committer)
    ```
`Staff` objects are commonly used in related models, for example the `Task` model. To see all of a staff member's assigned or created tasks, the following code can be used:
    ```python
    from canvas_sdk.v1.data.staff import Staff
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    staff.assignee_tasks.all()
    # <QuerySet [<Task: Task object (3)>]>
    staff.creator_tasks.all()
    # <QuerySet [<Task: Task object (7)>]>
    ```
To show a Staff member's contact points (email, phone, etc.), the `telecom` attribute can be used. For example:
    ```python
    from canvas_sdk.v1.data.staff import Staff
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    [(t.system, t.value,) for t in staff.telecom.all()]
    # [('phone', '8005551416'), ('email', 'support@canvasmedical.com')]
    ```
To show a `Staff` full name, credentialed name, the topmost clinical role or top role abbreviation use the properties `full_name`, `credentialed_name`, `top_clinical_role` or `top_role_abbreviation`.
    ```python
    from canvas_sdk.v1.data.staff import Staff
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    staff.full_name
    # Larry Weed
    staff.credentialed_name
    # Larry Weed MD
    staff.top_clinical_role.name
    # Physician
    staff.top_role_abbreviation
    # MD
    ```
When a staff member holds more than one role, `top_clinical_role` looks only at roles in a clinical domain — those whose `domain` is `CLINICAL` or `HYBRID` — and returns the one with the highest `domain_privilege_level`. Administrative roles are never selected, even if they carry a higher privilege level. If the staff member has no clinical or hybrid roles, both `top_clinical_role` and `top_role_abbreviation` are `None`. Because `credentialed_name` appends `top_role_abbreviation`, it reflects the same highest-privilege clinical role.
To get `Staff` licenses.
    ```python
    from canvas_sdk.v1.data.staff import Staff
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    staff.licenses.all()
    # <QuerySet [<StaffLicense: CA License for Larry Weed>]>
    ```
##  Accessing the staff signature 
The `signature_url` property returns a presigned S3 URL for securely accessing the staff member's signature file, when one is on file. If no signature has been uploaded, the property returns `None`.
    ```python
    from canvas_sdk.v1.data.staff import Staff
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    # Returns a presigned S3 URL (valid for 1 hour) or None
    url = staff.signature_url
    ```
##  Attributes 
###  Staff 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
prefix| String|   
suffix| String|   
first_name| String|   
middle_name| String|   
last_name| String|   
maiden_name| String|   
nickname| String|   
previous_names| JSON|   
birth_date| Date|   
sex_at_birth| [PersonSex](/sdk/data-enumeration-types/#personsex)|   
sexual_orientation_term| String|   
sexual_orientation_code| String|   
gender_identity_term| String|   
gender_identity_code| String|   
preferred_pronouns| String|   
biological_race_codes| Array[String]|   
biological_race_terms| Array[String]|   
cultural_ethnicity_codes| Array[String]|   
cultural_ethnicity_terms| Array[String]|   
last_known_timezone| TimeZone|   
active| Boolean|   
primary_practice_location| [PracticeLocation](/sdk/data-practicelocation/)|   
npi_number| String|   
nadean_number| String|   
group_npi_number| String|   
bill_through_organization| Boolean|   
tax_id| String|   
tax_id_type| [TaxIDType](/sdk/data-enumeration-types/#taxidtype)|   
spi_number| String|   
personal_meeting_room_link| URL|   
language| Language|   
language_secondary| Language|   
schedule_column_ordering| Integer|   
state| JSON|   
user| [CanvasUser](/sdk/data-canvasuser)|   
signature| File (S3 key)|   
supervising_team| Staff[]|   
default_supervising_provider| Staff|   
notes| Note[]|   
supervised_notes| Note[]|   
creator_tasks| [Task](/sdk/data-task/#task)[]|   
assignee_tasks| [Task](/sdk/data-task/#task)[]|   
comments| [TaskComment](/sdk/data-task/#taskcomment)[]|   
care_team_memberships| [CareTeamMembership](/sdk/data-care-team/#careteammembership)[]|   
teams| [Team](/sdk/data-team/#team)[]|   
telecom| StaffContactPoint[]|   
external_identifiers| StaffExternalIdentifier[]|   
metadata| StaffMetadata[]|   
addresses| StaffAddress[]|   
photos| StaffPhoto[]|   
roles| StaffRole[]|   
licenses| StaffLicense[]|   
letters| [Letter](/sdk/data-letter/#letter)[]|   
imaging_orders| [ImagingOrder](/sdk/data-imaging/#imagingorder)[]|   
dme_orders| [DmeOrder](/sdk/data-dme/#dmeorder)[]|   
immunizations_given| [Immunization](/sdk/data-immunization/#immunization)[]|   
supervising_prescriptions| [Prescription](/sdk/data-prescription/#prescription)[]|   
refill_requests| [RefillRequest](/sdk/data-refill-request/#refillrequest)[]|   
default_patients| [Patient](/sdk/data-patient/#patient)[]|   
medication_history_responses| [MedicationHistoryResponse](/sdk/data-medication-history/#medicationhistoryresponse)[]|   
transmissions_delivered| [MessageTransmission](/sdk/data-message/#messagetransmission)[]|   
integration_task_reviews| [IntegrationTaskReview](/sdk/data-integration-task/#integrationtaskreview)[]|   
assignee_note_tasks| [NoteTask](/sdk/data-task/#notetask)[]|   
appointment_set| [Appointment](/sdk/data-appointment/#appointment)[]|   
prescription_set| [Prescription](/sdk/data-prescription/#prescription)[]|   
note_set| [Note](/sdk/data-note/#note)[]|   
prescription_change_requests| [PrescriptionChangeRequest](/sdk/data-prescription-change-request/#prescriptionchangerequest)[]|   
google_calendar_busy_blocks| [GoogleCalendarBusyBlock](/sdk/data-google-calendar/#googlecalendarbusyblock)[]|   
google_calendar_connection| [GoogleCalendarConnection](/sdk/data-google-calendar/#googlecalendarconnection)|   
full_name| String (computed)| The staff member's first and last name, for example `Larry Weed`  
credentialed_name| String (computed)| The staff member's full name suffixed with their topmost credential abbreviation, for example `Larry Weed MD`  
top_clinical_role| StaffRole (computed)| The staff member's highest-ranking clinical role, selected by privilege level when they hold more than one, or `None` if they have no clinical role  
top_role_abbreviation| String (computed)| The public credential abbreviation of `top_clinical_role`, for example `MD`, or `None` if there is no clinical role  
photo_url| String (computed)| The URL of the staff member's photo, or a placeholder image URL  
signature_url| String (computed)| A presigned S3 URL for the staff member's signature file, valid for 1 hour, or `None` if no signature is on file  
###  StaffContactPoint 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| [ContactPointSystem](/sdk/data-enumeration-types/#contactpointsystem)  
value| String  
use| String  
use_notes| String  
rank| Integer  
state| [ContactPointState](/sdk/data-enumeration-types/#contactpointstate)  
staff| Staff  
###  StaffAddress 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
line1| String  
line2| String  
city| String  
district| String  
state_code| String  
postal_code| String  
use| [AddressUse](/sdk/data-enumeration-types/#addressuse)  
type| [AddressType](/sdk/data-enumeration-types/#addresstype)  
longitude| Float  
latitude| Float  
start| Date  
end| Date  
country| String  
state| String  
staff| Staff  
###  StaffLicense 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
staff| Staff  
issuing_authority_long_name| String  
issuing_authority_url| URL  
license_or_certification_identifier| String  
issuance_date| Date  
expiration_date| Date  
license_type| LicenseType  
primary| Boolean  
state| String  
###  StaffPhoto 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
staff| Staff  
url| String  
title| String  
###  StaffRole 
Field Name| Type  
---|---  
dbid| Integer  
created| DateTime  
modified| DateTime  
staff| Staff  
internal_code| String  
public_abbreviation| String  
domain| RoleDomain  
name| String  
domain_privilege_level| Integer  
permissions| JSON  
role_type| RoleType  
###  StaffExternalIdentifier 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
staff| Staff  
use| String  
identifier_type| String  
system| String  
value| String  
issued_date| Date  
expiration_date| Date  
    ```python
    from canvas_sdk.v1.data.staff import Staff
    from logger import log
    staff_id = "4150cd20de8a470aa570a852859ac87e"
    staff = Staff.objects.get(id=staff_id)
    for identifier in staff.external_identifiers.all():
        log.info(f"Staff external identifier: {identifier.system}, {identifier.value}")
        # https://www.example.com - employee-001
    ```
`StaffExternalIdentifier` is the supported way to store and read an external system's ID on a Staff/Practitioner record (the equivalent of `PatientExternalIdentifier` for staff). Plugins read it from this data module and write to it with the [`CreateStaffExternalIdentifier`](/sdk/effect-staff-external-identifier/) effect. The FHIR `Practitioner.identifier` field carries only the NPI: Canvas stores the first identifier's value as the practitioner's NPI and ignores the rest, so an external ID sent there would replace the NPI. Use `StaffExternalIdentifier` instead.
###  StaffMetadata 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
staff| Staff  
key| String  
value| String  
    ```python
    from canvas_sdk.v1.data.staff import Staff
    from logger import log
    staff_id = "4150cd20de8a470aa570a852859ac87e"
    staff = Staff.objects.get(id=staff_id)
    for metadata in staff.metadata.all():
        log.info(f"{metadata.key}={metadata.value}")
    ```
`StaffMetadata` is a free-form key/value store on a staff member, mirroring `PatientMetadata`. The `(staff, key)` pair is unique, so a given key has at most one value per staff member; use the [`StaffMetadata` effect](/sdk/effect-staff-metadata/) to upsert it from a plugin.
##  Enumeration types 
###  License Type 
Value| Description  
---|---  
CLIA| CLIA  
DEA| DEA  
PTAN| PTAN  
STATE_LICENSE| State License  
TAXONOMY| Taxonomy  
SPI| SPI  
OTHER| Other  
###  Role Domain 
Value| Abbreviation| Description  
---|---|---  
CLINICAL| CLI| Clinical  
ADMINISTRATIVE| ADM| Administrative  
HYBRID| HYB| Hybrid  
###  Role Type 
Value| Description  
---|---  
NON_LICENSED| Non-Licensed  
LICENSED| Licensed  
PROVIDER| Provider  

---

# Stop Medication Event

Source: https://docs.canvasmedical.com/sdk/data-stop-medication-event/

##  Introduction 
The `StopMedicationEvent` model represents a record of a Stop Medication Event, when a medication is removed from a patient's medication list.
##  Basic usage 
To get a stop medication event by identifier, use the `get` method on the `StopMedicationEvent` model manager:
    ```python
    from canvas_sdk.v1.data import StopMedicationEvent
    stopped_medication = StopMedicationEvent.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    ```
If you have a patient object, the stop medication events for a patient can be accessed with the `stopped_medications` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    stopped_medications = patient.stopped_medications.all()
    ```
You can also access the referenced medication with the `medication` attribute:
    ```python
    from canvas_sdk.v1.data import StopMedicationEvent
    stopped_medication = StopMedicationEvent.objects.get(id="61a1853f-168f-4ed3-80d2-44e5d144bcf3")
    medication = stopped_medication.medication
    ```
Or for a given medication, you can access all stop events:
    ```python
    from canvas_sdk.v1.data import Medication
    medication = Medication.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    stopped_medication_events = medication.stopmedicationevent_set.all()
    ```
##  Committed records 
The `committed` method returns stop medication events that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data import StopMedicationEvent
    committed_stop_medication_events = StopMedicationEvent.objects.committed()
    ```
##  Attributes 
###  StopMedicationEvent 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
medication| [Medication](/sdk/data-medication)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
originator| [CanvasUser](/sdk/data-canvasuser)  
created| DateTime  
modified| DateTime  
rationale| String  

---

# Task

Source: https://docs.canvasmedical.com/sdk/data-task/

##  Introduction 
A `Task` represents a to-do item to be addressed. Tasks can be assigned to individual staff members and can also have associated comments and labels.
##  Basic usage 
To get a task by it's identifier, use the `get` method on the `Task` model manager:
    ```python
    from canvas_sdk.v1.data.task import Task
    task = Task.objects.get(id="7895e1db-f8de-4660-a0a3-9e5b43a475c6")
    ```
From a `Patient` object, tasks for the patient can be accessed with the `tasks` attribute:
    ```python
    import arrow
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.v1.data.task import TaskStatus
    patient = Patient.objects.get(id="36950971cb3e4174ad8b9d365abfd6d0")
    # All tasks for the patient
    tasks_for_patient = patient.tasks.all()
    # Tasks for the patient that are overdue
    tasks_for_patient_overdue = patient.tasks.filter(due__lte=arrow.utcnow().datetime, status=TaskStatus.OPEN)
    ```
`Task` objects are also able to have associated `TaskLabel` objects.
    ```python
    from canvas_sdk.v1.data.task import Task
    task = Task.objects.get(id="7895e1db-f8de-4660-a0a3-9e5b43a475c6")
    [(label.name, label.color,) for label in task.labels.all()]
    # [('Emergent', 'red')]
    ```
`Staff` members are able to leave comments on tasks. These are stored as associated `TaskComment` objects. For example:
    ```python
    from canvas_sdk.v1.data.task import Task
    task = Task.objects.get(id="7895e1db-f8de-4660-a0a3-9e5b43a475c6")
    [(comment.creator, comment.body,) for comment in task.comments.all()]
    # [(<Staff: Sam Jones>, "Please call patient.")]
    ```
###  Note Tasks and Initial Comments 
A `NoteTask` represents the link between a Task command and the `Task` it generates. When a task is created via a Task command, a `NoteTask` record is created that stores the original values entered in the command. Of importance is the **initial comment** that is provided during task creation in the `internal_comment` field.
This is important because `task.comments.all()` only returns manual comments added after the task is created through the interface—it does not include the original comment entered during task creation. To access that initial comment, you need to use the `NoteTask` model.
To get a note task by its identifier:
    ```python
    from canvas_sdk.v1.data.task import NoteTask
    note_task = NoteTask.objects.get(id="a1b2c3d4-e5f6-7890-abcd-ef1234567890")
    print(f"Initial comment: {note_task.internal_comment}")
    ```
From a `Task` object, you can access the associated `NoteTask` to retrieve the initial comment:
    ```python
    from canvas_sdk.v1.data.task import Task
    task = Task.objects.get(id="7895e1db-f8de-4660-a0a3-9e5b43a475c6")
    # Access the NoteTask to get the initial comment
    note_task = task.note_tasks.first()
    if note_task:
        print(f"Initial comment: {note_task.internal_comment}")
        print(f"Original title: {note_task.original_title}")
        print(f"Original assignee: {note_task.original_assignee}")
    ```
Common workflow pattern: handling a TASK_CREATED event and accessing the initial comment:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.task import Task
    class TaskCreatedHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.TASK_CREATED)]
        def compute(self):
            task_id = self.target
            task = Task.objects.get(id=task_id)
            # Get the initial comment from the NoteTask
            note_task = task.note_tasks.first()
            if note_task:
                initial_comment = note_task.internal_comment
                # Use the initial comment for your logic
                self.log(f"Task created with initial comment: {initial_comment}")
    ```
From a `Note` object, note tasks can be accessed with the `note_tasks` attribute:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    note_tasks = note.note_tasks.all()
    for note_task in note_tasks:
        print(f"Task: {note_task.original_title}")
        print(f"Initial comment: {note_task.internal_comment}")
    ```
##  Committed note tasks 
The `committed` method on the `NoteTask` model manager returns note tasks whose underlying Task command has been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.task import NoteTask
    committed_note_tasks = NoteTask.objects.committed()
    ```
##  Attributes 
###  Task 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
creator| [Staff](/sdk/data-staff/#staff)  
assignee| [Staff](/sdk/data-staff/#staff)  
patient| [Patient](/sdk/data-patient/#patient)  
team| [Team](/sdk/data-team/)  
task_type| TaskType  
tag| String  
title| String  
due| DateTime  
due_event| EventType  
status| TaskStatus  
priority| TaskPriority  
comments| TaskComment[]  
labels| TaskLabel[]  
metadata| TaskMetadata[]  
note_tasks| NoteTask[]  
###  NoteTask 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser/)  
committer| [CanvasUser](/sdk/data-canvasuser/)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser/)  
note| [Note](/sdk/data-note/#note)  
assessment| [Assessment](/sdk/data-assessment/#assessment)  
task| Task  
patient| [Patient](/sdk/data-patient/#patient)  
original_title| String  
original_assignee| [Staff](/sdk/data-staff/#staff)  
original_team| [Team](/sdk/data-team/)  
original_role| [CareTeamRole](/sdk/data-care-team/#careteamrole)  
original_due| DateTime  
internal_comment| String  
###  TaskComment 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
creator| [Staff](/sdk/data-staff/#staff)  
task| [Task](/sdk/data-task/#task)  
body| String  
referral| [Referral](/sdk/data-referral/)  
###  TaskLabel 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
tasks| M2M  
position| Integer  
color| [ColorEnum](/sdk/data-enumeration-types/#colorenum)  
task_association| [Origin](/sdk/data-enumeration-types/#origin)  
name| String  
active| Boolean  
modules| TaskLabelModule  
claims| [Claim](/sdk/data-claim)[]  
appointments| [Appointment](/sdk/data-appointment/)[]  
###  TaskTaskLabel 
The join between a task and a TaskLabel. Reach the labels on a task through its `labels` attribute rather than querying this model.
Field Name| Type  
---|---  
dbid| Integer  
task| Task  
task_label| TaskLabel  
###  TaskMetadata 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
task| Task  
key| String  
value| String  
    ```python
    from canvas_sdk.v1.data.task import Task
    from logger import log
    task_id = "7895e1db-f8de-4660-a0a3-9e5b43a475c6"
    task = Task.objects.get(id=task_id)
    task_metadata = task.metadata.all()
    for metadata in task_metadata:
       log.info(f"Task metadata: {metadata.key}, {metadata.value}") # external_system_id - EXT-12345
    ```
##  Enumeration types 
###  TaskType 
Value| Label  
---|---  
Task| Task  
Reminder| Reminder  
###  EventType 
Value| Label  
---|---  
Chart Open| Chart Open  
###  TaskStatus 
Value| Label  
---|---  
COMPLETED| Completed  
CLOSED| Closed  
OPEN| Open  
###  TaskPriority 
Value| Label  
---|---  
STAT| STAT  
URGENT| Urgent  
ROUTINE| Routine  
###  TaskLabelModule 
Value| Label  
---|---  
claims| Claims  
tasks| Tasks  
appointments| Appointments  

---

# Team

Source: https://docs.canvasmedical.com/sdk/data-team/

##  Introduction 
The `Team` model represents a team of staff members in a Canvas instance.
##  Basic usage 
To get an team by identifier, use the `get` method on the `Team` model manager:
    ```python
    from canvas_sdk.v1.data.team import Team
    team = Team.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a staff object, the teams that a staff is a member of can be accessed with the `teams` attribute on a `Staff` object:
    ```python
    from canvas_sdk.v1.data.staff import Staff
    staff = Staff.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    teams = staff.teams.all()
    ```
##  Team Members 
The members of a team can be access with the `members` attribute on a `Team` object:
    ```python
    from canvas_sdk.v1.data.team import Team
    from logger import log
    team = Team.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for member in team.members.all():
        log.info(f"first_name: {member.first_name}")
        log.info(f"last_name: {member.last_name}")
    ```
##  Reconciling with FHIR 
A team's `group_id` is the same identifier used to represent the team in the [FHIR Group endpoint](/api/group/). Use it to cross-reference a `Team` between the SDK and FHIR.
Given a `Team`, you can use its `group_id` with the [Canvas FHIR client](/sdk/clients-canvas-fhir/) to fetch the corresponding FHIR `Group` payload:
    ```python
    from canvas_sdk.clients.canvas_fhir import CanvasFhir
    from canvas_sdk.v1.data.team import Team
    team = Team.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    # Declare these secrets in the CANVAS_MANIFEST.json and set the values on the
    # plugin configuration page.
    client = CanvasFhir(
        self.secrets["CANVAS_FHIR_CLIENT_ID"],
        self.secrets["CANVAS_FHIR_CLIENT_SECRET"],
    )
    # Use the team's group_id to read the corresponding FHIR Group resource.
    group = client.read("Group", str(team.group_id))
    ```
##  Filtering 
Teams can be filtered by any attribute that exists on the model.
Filtering for teams is done with the `filter` method on the `Team` model manager.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.team import Team
    teams = Team.objects.filter(created__gt="2025-01-01")
    ```
##  Attributes 
###  Team 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
name| String  
responsibilities| Array[TeamResponsibility]  
members| [Staff](/sdk/data-staff/#staff)[]  
group_id| UUID  
telecom| TeamContactPoint[]  
tasks| [Task](/sdk/data-task/#task)[]  
document_references| [DocumentReference](/sdk/data-document-reference/#documentreference)[]  
integration_task_team_reviews| [IntegrationTaskReview](/sdk/data-integration-task/#integrationtaskreview)[]  
uncategorizedclinicaldocument_set| [UncategorizedClinicalDocument](/sdk/data-uncategorized-clinical-document/#uncategorizedclinicaldocument)[]  
referralreport_set| [ReferralReport](/sdk/data-referral/#referralreport)[]  
assigned_messages| [Message](/sdk/data-message/#message)[]  
labreport_set| [LabReport](/sdk/data-labs/#labreport)[]  
imagingreport_set| [ImagingReport](/sdk/data-imaging/#imagingreport)[]  
patientadministrativedocument_set| [PatientAdministrativeDocument](/sdk/data-patient-administrative-document/#patientadministrativedocument)[]  
###  TeamContactPoint 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
system| [ContactPointSystem](/sdk/data-enumeration-types/#contactpointsystem)  
value| String  
use| [ContactPointUse](/sdk/data-enumeration-types/#contactpointuse)  
use_notes| String  
rank| Integer  
state| [ContactPointState](/sdk/data-enumeration-types/#contactpointstate)  
team| Team  
##  Enumeration types 
###  TeamResponsibility 
Field Name| Type  
---|---  
COLLECT_SPECIMENS_FROM_PATIENT| Collect specimens from a patient  
COMMUNICATE_DIAGNOSTIC_RESULTS_TO_PATIENT| Communicate diagnostic results to patient  
COORDINATE_REFERRALS_FOR_PATIENT| Coordinate referrals for a patient  
PROCESS_REFILL_REQUESTS| Process refill requests from a pharmacy  
PROCESS_CHANGE_REQUESTS| Process change requests from a pharmacy  
SCHEDULE_LAB_VISITS_FOR_PATIENT| Schedule lab visits for a patient  
POPULATION_HEALTH_CAMPAIGN_OUTREACH| Population health campaign outreach  
COLLECT_PATIENT_PAYMENTS| Collect patient payments  
COMPLETE_OPEN_LAB_ORDERS| Complete open lab orders  
REVIEW_ERA_POSTING_EXCEPTIONS| Review electronic remittance posting exceptions  
REVIEW_COVERAGES| Review incomplete patient coverages  

---

# Uncategorized Clinical Document

Source: https://docs.canvasmedical.com/sdk/data-uncategorized-clinical-document/

##  Introduction 
The `UncategorizedClinicalDocument` and `UncategorizedClinicalDocumentReview` models represent uncategorized clinical documents and their reviews.
##  Basic Usage 
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocument, UncategorizedClinicalDocumentReview
    document = UncategorizedClinicalDocument.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    review = UncategorizedClinicalDocumentReview.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    ```
##  Filtering 
Uncategorized clinical documents and reviews can be filtered by any attribute that exists on the models.
###  By review mode 
Filter documents by their review mode:
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocument
    from canvas_sdk.commands.commands.review import ReviewMode
    documents_to_review = UncategorizedClinicalDocument.objects.filter(review_mode=ReviewMode.REVIEW_REQUIRED)
    ```
###  Unreviewed documents 
To get uncategorized documents that have not been reviewed yet and require a review:
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocument
    from canvas_sdk.commands.commands.review import ReviewMode
    from django.db.models import Q
    unreviewed_documents = UncategorizedClinicalDocument.objects.filter(Q(review_mode=ReviewMode.REVIEW_REQUIRED), (Q(review__committer__isnull=True) | Q(review__entered_in_error__isnull=False)))
    ```
##  Review assignment 
A document is assigned for review to staff members or to a team. `reviewers` holds the assigned staff members, and `team` holds the assigned team, or `None` when no team is assigned. When the review is delegated to another staff member, `reviewers` lists the delegate in place of the original reviewer.
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocument, Staff
    document = UncategorizedClinicalDocument.objects.get(id="c1a5a35a-4ee2-4a0e-85c0-21739dc8c4a8")
    # The staff members and the team the document is assigned to
    reviewers = document.reviewers.all()
    team = document.team
    # Every document assigned to this staff member
    staff = Staff.objects.get(id="4150cd20de8a470aa570a852859ac87e")
    assigned = UncategorizedClinicalDocument.objects.filter(reviewers__id=staff.id)
    ```
##  Delegations 
A document review can be delegated to another staff member or team. The delegations for a document are available through two accessors:
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocument
    document = UncategorizedClinicalDocument.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
    # The full delegation history, oldest first.
    history = document.delegations
    # The current active delegation, or None when the document is with its owner.
    current = document.active_delegation
    ```
See [DocumentReviewDelegation](/sdk/data-document-review-delegation/) for the delegation model and the `DOCUMENT_DELEGATED` event.
##  Document codings 
The `code` field comes from the document's type, which is drawn from a fixed list rather than set freely — either the type selected in Data Integration, or, when a document is created through the FHIR [DocumentReference](/api/documentreference/) endpoint, the LOINC code supplied in `type.coding`, which must match one of the codes below. Every coding uses the LOINC system (`http://loinc.org`). The document types stored as uncategorized clinical documents are:
Document type| Code| Display  
---|---|---  
Care Management Documents| 91983-7| Care management note  
Clinical Patient Intake Form| 64285-0| Medical history screening form  
Emergency Department Report| 96335-5| Emergency department Summary note  
External Medical Records| 11503-0| Medical records  
Home Care Report| 75503-3| Patient's home Note  
Hospital Discharge Summary| 34105-7| Hospital Discharge summary  
Hospital History and Physical| 47039-3| Hospital Admission history and physical note  
Nursing Home| 34113-1| Nursing facility Note  
Operative Report| 11504-8| Surgical operation note  
Physical Exam Documents| 51848-0| Evaluation note  
Prescription Refill Request| 57833-6| Prescription for medication  
Rehabilitation Report| 34823-5| Physical medicine and rehab Note  
Uncategorized Clinical Document| 34109-9| Note  
In Office Testing Documents| —| none  
> **Warning:** In Office Testing Documents have no coding assigned, so their `code` is `None`. Filtering on `code` silently excludes them, and because the FHIR endpoint identifies a document's type by its LOINC code, they can only be created through Data Integration.
Administrative document types are stored as [PatientAdministrativeDocument](/sdk/data-patient-administrative-document/) instead. Lab reports, imaging reports and specialist consult reports have their own models, so their codings never appear here.
##  Accessing the document file 
The `document_url` property returns a presigned S3 URL for the document file, or `None` when no file is present. The URL is valid for one hour, so generate it when you need it rather than storing it.
    ```python
    from canvas_sdk.v1.data import UncategorizedClinicalDocument
    record = UncategorizedClinicalDocument.objects.get(
        id="d2194110-5c9a-4842-8733-ef09ea5ead11"
    )
    # Presigned S3 URL to the document file, or None
    url = record.document_url
    ```
##  The document reference 
Each record also has a [DocumentReference](/sdk/data-document-reference/#the-related-object) pointing back at it. The document reference carries the document's coding, category, and status, and represents the document in the FHIR API. Use `document_url` to get the file itself, and the document reference when you want that metadata.
To find it, resolve the [ContentType](/sdk/data-content-type/) at runtime from its stable `app_label` and `model` — never hardcode the per-environment `dbid` — and match `object_id` against the record's `dbid`:
    ```python
    from canvas_sdk.v1.data import ContentType, DocumentReference, UncategorizedClinicalDocument
    record = UncategorizedClinicalDocument.objects.get(
        id="d2194110-5c9a-4842-8733-ef09ea5ead11"
    )
    content_type = ContentType.objects.filter(
        app_label="api", model="uncategorizedclinicaldocument"
    ).first()
    document = DocumentReference.objects.filter(
        content_type=content_type, object_id=record.dbid
    ).first()
    url = document.document_url if document else None
    ```
> **Info:** `object_id` holds the related record's integer `dbid`, not its UUID `id`. A document marked entered-in-error keeps its document reference, with the status carried across, so check `status` if that matters to you.
##  Attributes 
###  UncategorizedClinicalDocument 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
patient| [Patient](/sdk/data-patient/#patient)  
originator| [CanvasUser](/sdk/data-canvasuser)  
assigned_by| [CanvasUser](/sdk/data-canvasuser)  
review| UncategorizedClinicalDocumentReview  
team| [Team](/sdk/data-team/#team)  
reviewers| [Staff](/sdk/data-staff/#staff)[]  
code| [DocumentCoding](/sdk/data-patient-administrative-document/#documentcoding)  
name| String  
review_mode| [DocumentReviewMode](/sdk/data-enumeration-types/#documentreviewmode)  
junked| Boolean  
requires_signature| Boolean  
assigned_date| DateTime  
team_assigned_date| DateTime  
original_date| Date  
comment| String  
priority| Boolean  
document| File (S3 key)  
document_url| String (computed)  
###  UncategorizedClinicalDocumentReview 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
internal_comment| String  
message_to_patient| String  
status| String  
patient| [Patient](/sdk/data-patient/#patient)  
patient_communication_method| String  
reports| QuerySet[UncategorizedClinicalDocument]

---

# Vaccine

Source: https://docs.canvasmedical.com/sdk/data-vaccine/

##  Introduction 
The `Vaccine` model represents an entry in a Canvas instance's vaccine catalog — what a provider can choose when documenting an [Immunize](/sdk/commands/#immunize) command. `VaccineLot` represents a physical lot of one of those vaccines, along with how many doses remain on hand.
##  Basic usage 
A vaccine carries the CPT and CVX codes that identify it. The CVX code is on the vaccine; the CPT codes come from its charges, and those charges are what produce the billing line item when an [Immunize](/sdk/commands/#immunize) command is committed.
    ```python
    from canvas_sdk.v1.data import Vaccine
    vaccine = Vaccine.objects.filter(active=True, cvx_code="135").first()
    print(vaccine.cvx_code, [charge.cpt_code for charge in vaccine.charges.all()])
    # 135 ["90662"]
    ```
Each physical lot of a vaccine tracks how many doses remain, and committing an Immunize command decrements that count:
    ```python
    from canvas_sdk.v1.data import VaccineLot
    lot = VaccineLot.objects.filter(lot_number="LOT-135-001").first()
    print(lot.vaccine.short_name, lot.on_hand_inventory, lot.expiration_date)
    # Fluzone High-Dose 25 2027-06-30
    ```
`mvx_code` holds a CDC MVX manufacturer code. The codes are declared as the field's choices, so Django's display helper resolves the manufacturer name:
    ```python
    from canvas_sdk.v1.data import VaccineLot
    lot = VaccineLot.objects.filter(lot_number="LOT-135-001").first()
    print(lot.mvx_code, "->", lot.get_mvx_code_display())
    # ASZ -> AstraZeneca
    ```
Some instances record a single stock figure on the vaccine itself rather than tracking lots. That value lives in `Vaccine.inventory` as free text and is independent of `VaccineLot.on_hand_inventory`.
##  Filtering 
A vaccine is selectable on a note when it is active **and** carries an active CPT charge. Filtering the same way keeps a plugin in step with what a provider would see:
    ```python
    from datetime import date
    from django.db.models import Q
    from canvas_sdk.v1.data import Vaccine
    today = date.today()
    selectable = Vaccine.objects.filter(
        Q(active=True),
        Q(charges__effective_date__lte=today),
        Q(charges__end_date__isnull=True) | Q(charges__end_date__gte=today),
    ).distinct()
    print([vaccine.short_name for vaccine in selectable])
    # ["Fluzone High-Dose", "Trumenba", "Prevnar 13™"]
    ```
Lots are administrable while they have doses on hand:
    ```python
    from canvas_sdk.v1.data import VaccineLot
    in_stock = VaccineLot.objects.filter(vaccine__cvx_code="135", on_hand_inventory__gt=0)
    print([(lot.lot_number, lot.on_hand_inventory) for lot in in_stock])
    # [("LOT-135-001", 25)]
    ```
##  Attributes 
###  Vaccine 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
payer| [Transactor](/sdk/data-coverage/#transactor)  
charges| QuerySet[[ChargeDescriptionMaster](/sdk/data-charge-description-master/#chargedescriptionmaster)]  
cvx_code| String  
name| String  
short_name| String  
inventory| String  
ndc_code| String  
mvx_code| VaccineManufacturer  
route| String  
active| Boolean  
units| Integer  
lots| QuerySet[VaccineLot]  
A vaccine may appear more than once for the same `cvx_code` — instances commonly carry a payer-specific entry alongside a general one. Use `payer` to tell them apart.
###  VaccineLot 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
vaccine| Vaccine  
lot_number| String  
ndc_code| String  
mvx_code| VaccineManufacturer  
expiration_date| Date  
diluent_lot_number| String  
diluent_expiration_date| Date  
starting_inventory| Integer  
quantity_adjustment| Integer  
adjustment_notes| String  
on_hand_inventory| Integer  
used_inventory| Integer  
`on_hand_inventory` is derived from `starting_inventory + quantity_adjustment - used_inventory`.
##  Enumeration types 
###  VaccineManufacturer 
CDC MVX manufacturer codes. Prefer `get_mvx_code_display()` over mapping these yourself.
Value| Label  
---|---  
ASZ| AstraZeneca  
BBI| Bharat Biotech International Limited  
BN| Bavarian Nordic A/S  
BTP| Biotest Pharmaceuticals Corporation  
CAN| CanSino Biologics, Inc  
DVC| DynPort Vaccine Company, LLC  
DVX| Dynavax, Inc  
GEO| GeoVax Labs, Inc  
GRF| Grifols  
IDB| ID Biomedical  
JNJ| Johnson and Johnson  
JSN| Janssen  
KED| Kedrion Biopharma  
KGC| Korea Green Cross Corporation  
MBL| Massachusetts Biologic Laboratories  
MDO| Medicago, Inc  
MED| MedImmune, Inc. (AstraZeneca)  
MIP| Emergent BioSolutions  
MOD| Moderna US, Inc  
MSD| Merck and Co., Inc  
MSP| MSP Vaccine Company - (partnership Merck and Sanofi Pasteur)  
NAB| NABI  
NVX| Novavax, Inc  
OTH| Other manufacturer  
PAX| Emergent Travel Health, Inc (Formerly PaxVax)  
PFR| Pfizer, Inc  
PMC| Sanofi Pasteur  
PSC| Protein Sciences  
SEQ| Seqirus  
SKB| GlaxoSmithKline  
SNV| Sinovac  
SPH| Sinopharm-Biotech  
TVA| TEVA Pharmaceuticals USA  
UNK| Unknown manufacturer  
VAL| Valneva  
VBI| VBI Vaccines, Inc  
WAL| Wyeth

---

# ValueSets

Source: https://docs.canvasmedical.com/sdk/data-value-sets/

##  Introduction 
The Canvas SDK includes a library of built-in Value Sets that can be used within plugins to assist with finding conditions or medications related to Electronic Clinical Quality Measures. Plugin developers can also create their own Value Sets and use them in the same manner as the Canvas built-in `ValueSet` classes.
Built-in Value Sets that can be imported into plugins can be found in the Canvas SDK open source repo [here](https://github.com/canvas-medical/canvas-plugins/tree/main/canvas_sdk/value_set/).
##  Usage 
**Filtering Conditions by Value Set**
Value Set classes can be used directly in the data module to query for conditions that are included within them. For example, to find if a patient has been diagnosed with a condition whose coding falls under a particular Value Set, the `find` method can be used as follows:
    ```python
    from logger import log
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.value_set.v2022.condition import EssentialHypertension
    patient = Patient.objects.get(id="6cbc40b408294a5f9b41f57ba1b2b487")
    patient_essential_hypertension_conditions = patient.conditions.find(EssentialHypertension)
    # The patient has been diagnosed with one or more conditions that match a coding within the EssentialHypertension value set
    if patient_essential_hypertension_conditions:
        for condition in patient_essential_hypertension_conditions:
            log.info(condition.codings.all().values())
    ```
**Filtering Medications by Value Set**
Similar to the `Condition` example above, the `find` method can also utilize Value Set classes to filter `Medication` records that fall under a value set:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.value_set.v2022.medication import DementiaMedications
    from logger import log
    patient = Patient.objects.get(id="6cbc40b408294a5f9b41f57ba1b2b487")
    patient_dementia_medications = patient.medications.find(DementiaMedications)
    if patient_dementia_medications:
        for medication in patient_dementia_medications:
            log.info(medication.codings.all().values())
    ```
**Filtering with more than one Value Set**
Sometimes it may be desirable to filter using more than one Value Set. For example, finding all of a patient's conditions that belong within `EssentialHypertension` _or_ `DiagnosisOfHypertension`. In this case, the `find` supports the pipe (`|`) operator to filter conditions that match the codings in either Value Set:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.value_set.v2022.condition import EssentialHypertension, DiagnosisOfHypertension
    from logger import log
    patient = Patient.objects.get(id="6cbc40b408294a5f9b41f57ba1b2b487")
    patient_hypertension_conditions = patient.conditions.find(EssentialHypertension | DiagnosisOfHypertension)
    if patient_hypertension_conditions:
        for condition in patient_hypertension_conditions:
            log.info(condition.codings.all().values())
    ```
##  Creating Custom Value Sets 
The Canvas SDK allows plugin developers to create their own ValueSet classes that can be used in the same manner as the examples above. To do so, one can import and inherit the base `ValueSet` class:
    ```python
    from canvas_sdk.value_set.value_set import ValueSet
    ```
A new class containing Python sets of coding values can be defined like so:
    ```python
    from canvas_sdk.value_set.value_set import ValueSet
    class MyCustomValueSet(ValueSet):
        VALUE_SET_NAME = "My Custom Value Set"
        ICD10CM = {
            "T2601XA",  # Burn of right eyelid and periocular area, initial encounter
        }
        SNOMEDCT = {
            "284537006",  # Eyelid burn (disorder)
        }
    ```
The valid code system constants that can be used to define sets of codes in Value Sets are:
Name| URL  
---|---  
`CPT`| `http://www.ama-assn.org/go/cpt`  
`HCPCSLEVELII`| `https://coder.aapc.com/hcpcs-codes`  
`CVX`| `http://hl7.org/fhir/sid/cvx`  
`LOINC`| `http://loinc.org`  
`SNOMEDCT`| `http://snomed.info/sct`  
`FDB`| `http://www.fdbhealth.com/`  
`RXNORM`| `http://www.nlm.nih.gov/research/umls/rxnorm`  
`ICD10`| `ICD-10`  
`NUCC`| `http://www.nucc.org/`  
`CANVAS`| `CANVAS`  
`INTERNAL`| `INTERNAL`  
`NDC`| `http://hl7.org/fhir/sid/ndc`  
The following code is an example of a custom `ValueSet` in use within a plugin:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.value_set.value_set import ValueSet
    class MyCustomValueSet(ValueSet):
        VALUE_SET_NAME = "My Custom Value Set"
        ICD10CM = {
            "T2601XA",  # Burn of right eyelid and periocular area, initial encounter
        }
        SNOMEDCT = {
            "284537006",  # Eyelid burn (disorder)
        }
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_UPDATED)
        def compute(self):
            patient = Patient.objects.get(id="6cbc40b408294a5f9b41f57ba1b2b487")
            custom_value_set_conditions = patient.conditions.find(MyCustomValueSet)
            for vs in custom_value_set_conditions:
                log.info(vs)
            return []
    ```

---

# VisualExamFinding

Source: https://docs.canvasmedical.com/sdk/data-visual-exam-finding/

##  Introduction 
The `VisualExamFinding` model represents a visual exam finding captured on a note. Each finding consists of a titled image along with a narrative description of the clinical observation.
To record a finding from a plugin, use the [VisualExamFinding command](/sdk/commands/#visualexamfinding).
##  Basic usage 
To get a visual exam finding by identifier, use the `get` method on the `VisualExamFinding` model manager:
    ```python
    from canvas_sdk.v1.data.visual_exam_finding import VisualExamFinding
    finding = VisualExamFinding.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient object, the visual exam findings for a patient can be accessed with the `visual_exam_findings` attribute on a `Patient` object:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    findings = patient.visual_exam_findings.all()
    ```
If you have a note object, the visual exam findings for that note can be accessed with the `visual_exam_findings` attribute on a `Note` object:
    ```python
    from canvas_sdk.v1.data.note import Note
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    findings = note.visual_exam_findings.all()
    ```
##  Accessing image files 
The `image_url` property returns a presigned S3 URL for securely accessing the image file. The URL is valid for 1 hour.
    ```python
    from canvas_sdk.v1.data.visual_exam_finding import VisualExamFinding
    finding = VisualExamFinding.objects.exclude(image="").first()
    # Returns a presigned S3 URL (valid for 1 hour), or None if no image is set
    url = finding.image_url
    ```
##  Filtering 
Visual exam findings can be filtered by any attribute that exists on the model.
###  By attribute 
Specify an attribute with `filter` to filter by that attribute:
    ```python
    from canvas_sdk.v1.data.visual_exam_finding import VisualExamFinding
    # Get all findings with a specific title
    findings = VisualExamFinding.objects.filter(title="Left forearm")
    ```
###  By patient 
    ```python
    from canvas_sdk.v1.data.visual_exam_finding import VisualExamFinding
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    findings = VisualExamFinding.objects.filter(patient=patient)
    ```
###  Committed findings 
The `committed` method returns visual exam findings that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.visual_exam_finding import VisualExamFinding
    committed_findings = VisualExamFinding.objects.committed()
    ```
##  Attributes 
###  VisualExamFinding 
Field Name| Type| Description  
---|---|---  
id| UUID|   
dbid| Integer|   
created| DateTime|   
modified| DateTime|   
patient| [Patient](/sdk/data-patient/#patient)|   
note| [Note](/sdk/data-note/#note)|   
image| File (S3 key)|   
title| String|   
narrative| String|   
originator| [CanvasUser](/sdk/data-canvasuser)|   
committer| [CanvasUser](/sdk/data-canvasuser)|   
entered_in_error| [CanvasUser](/sdk/data-canvasuser)|   
image_url| String (computed)| Presigned S3 URL

---

# VitalSignReading

Source: https://docs.canvasmedical.com/sdk/data-vital-sign-reading/

##  Introduction 
The `VitalSignReading` model is the anchor for the [Vitals](/sdk/commands/#vitals) command — a set of vital-sign readings recorded on a Note for a Patient. The individual measurements (blood pressure, heart rate, temperature, weight, etc.) are stored as related `VitalSign` records, reachable via the `signs` attribute.
##  Basic usage 
To get a vital sign reading by identifier, use the `get` method on the `VitalSignReading` model manager:
    ```python
    from canvas_sdk.v1.data.vitals import VitalSignReading
    reading = VitalSignReading.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    ```
If you have a patient or note object, the readings can be accessed with the `vital_sign_readings` attribute:
    ```python
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.v1.data.note import Note
    patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
    readings = patient.vital_sign_readings.all()
    note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
    readings = note.vital_sign_readings.all()
    ```
If you have a patient ID, you can get the readings for the patient with the `for_patient` method:
    ```python
    from canvas_sdk.v1.data.vitals import VitalSignReading
    patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
    readings = VitalSignReading.objects.for_patient(patient_id)
    ```
##  Reading the individual measurements 
Each `VitalSignReading` has one or more `VitalSign` measurements, accessed with the `signs` attribute. Each `VitalSign` carries the measurement's LOINC code, name, value, and units:
    ```python
    from canvas_sdk.v1.data.vitals import VitalSignReading
    from logger import log
    reading = VitalSignReading.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for sign in reading.signs.all():
        log.info(f"{sign.sign}: {sign.value} {sign.units} (LOINC {sign.loinc_num})")
    ```
`signs` includes the parts of a composite measurement as well as the measurement itself, so a blood pressure appears three times in the loop above. See Composite measurements to walk only the top-level readings.
##  Filtering 
Vital sign readings can be filtered by any attribute that exists on the model.
###  Committed readings 
The `committed` method returns readings that have been committed and not entered in error:
    ```python
    from canvas_sdk.v1.data.vitals import VitalSignReading
    committed_readings = VitalSignReading.objects.committed()
    ```
##  Attributes 
###  VitalSignReading 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
originator| [CanvasUser](/sdk/data-canvasuser)  
committer| [CanvasUser](/sdk/data-canvasuser)  
entered_in_error| [CanvasUser](/sdk/data-canvasuser)  
patient| [Patient](/sdk/data-patient/#patient)  
note| [Note](/sdk/data-note)  
date_recorded| DateTime  
signs| VitalSign[]  
###  VitalSign 
Field Name| Type  
---|---  
id| UUID  
dbid| Integer  
created| DateTime  
modified| DateTime  
reading| VitalSignReading  
date_recorded| DateTime  
loinc_num| String  
sign| String — one of the sign values  
sign_description| String  
value| String  
units| String  
source| String  
parent| VitalSign — the composite measurement this one is a part of, if any  
children| VitalSign[] — the parts of this measurement, if it is a composite  
##  Composite measurements 
Some measurements are recorded as a whole _and_ as their parts. The whole is stored as one `VitalSign` and each part as another, linked to it by `parent`; the reverse accessor is `children`. A measurement that stands on its own has `parent` set to `None` and no `children`.
The [Vitals](/sdk/commands/#vitals) command produces two of these:
  - `blood_pressure` — the combined reading, parent of the `systole` and `diastole` signs taken from it.
  - `oxygen_saturation` — parent of `inhaled_oxygen_concentration` and `inhaled_oxygen_flow_rate`.
Because the parts sit alongside the whole in `reading.signs`, iterating a reading naively counts a blood pressure three times. Filter on `parent` to walk only the top-level measurements:
    ```python
    from canvas_sdk.v1.data.vitals import VitalSignReading
    from logger import log
    reading = VitalSignReading.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    for sign in reading.signs.filter(parent__isnull=True):
        parts = ", ".join(f"{part.sign}={part.value}" for part in sign.children.all())
        log.info(f"{sign.sign}: {sign.value} {sign.units}" + (f" ({parts})" if parts else ""))
    ```
##  Sign values 
`VitalSign.sign` holds one of a fixed set of values — the ones below are those a Canvas workflow records. Canvas declares them as a `VitalSignChoices` enumeration internally, but that enumeration is **not** exported to plugins, so compare against the string value directly:
    ```python
    from canvas_sdk.v1.data.vitals import VitalSignReading
    reading = VitalSignReading.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
    weights = [sign for sign in reading.signs.all() if sign.sign == "weight"]
    ```
`sign_description` carries a human-readable label for the same measurement, so prefer it for display and reserve `sign` for matching.
###  Where each value comes from 
Not every value is produced by every workflow, so which ones you see depends on how the vitals were recorded:
  - **The[Vitals](/sdk/commands/#vitals) command** writes `height`, `weight`, `waist_circumference`, `body_temperature`, `blood_pressure`, `systole`, `diastole`, `pulse`, `pulse_rhythm`, `respiration_rate`, `oxygen_saturation`, `inhaled_oxygen_concentration`, `inhaled_oxygen_flow_rate`, `supplemental_oxygen` and `note`. Blood pressure is stored three times over — once as the combined `blood_pressure` reading and once each as `systole` and `diastole`.
  - **A committed pediatric physical exam questionnaire** records `length` and `head_circumference_tape_measure`, taken from the answers carrying those LOINC codes.
Derived measurements are **not** `VitalSign` records. When a height, weight or length is recorded, Canvas calculates BMI from the height and weight and stores the results — the BMI-for-age, head-circumference and weight-for-height percentiles — as [Observation](/sdk/data-observation/) records attached to the reading, because each is computed from more than one measurement. Read them there rather than looking for a `sign`.
Value| Label  
---|---  
blood_pressure| Blood Pressure  
systole| Systole  
diastole| Diastole  
pulse| Pulse  
pulse_rhythm| Pulse Rhythm  
respiration_rate| Respiration Rate  
body_temperature| Body Temperature  
oxygen_saturation| Oxygen Saturation  
supplemental_oxygen| Supplemental Oxygen  
inhaled_oxygen_concentration| Inhaled Oxygen Concentration  
inhaled_oxygen_flow_rate| Inhaled Oxygen Flow Rate  
weight| Weight  
height| Height  
length| Length  
head_circumference_tape_measure| Head Circumference by Tape Measure  
waist_circumference| Waist Circumference  
note| Note  

---

# Data

Source: https://docs.canvasmedical.com/sdk/data/

The data module provides you with data to compute on. It provides curated, secure access to both PHI (e.g. patient data) and non-PHI (e.g. staff and practice-level data), representing the current state of your target Canvas instance. The module's classes offer convenience methods and operators that make business logic and clinical logic easy to express with standard terminologies like ICD-10, SNOMED-CT, CPT, and the like.
Data module classes are Django ORM models, which allow easy retrieval of data at runtime through Django's expressive [QuerySet API](https://docs.djangoproject.com/en/5.1/ref/models/querysets/).
Access to these models is **read-only** , and mutations to them are allowed only via use of [Effects](/sdk/effects/) and the FHIR API.
Use the [Custom Data](/sdk/custom-data/) features for creating and maintaining your plugin's own data.
The pages below provide listings of the models, their attributes, and examples of usage.
[ AllergyIntoleranceHarmful or undesired physiological responses associated with exposure to a substance. ](/sdk/data-allergy-intolerance/)[ ApplicationA plugin application. ](/sdk/data-application/)[ AppointmentA scheduled meeting between a patient and a provider. ](/sdk/data-appointment/)[ AssessCodingGapEventA record of a coding gap being assessed, with the conditions it was assessed against. ](/sdk/data-coding-gap-event/#assesscodinggapevent)[ AssessmentClinical assessment of a patient's condition. ](/sdk/data-assessment/)[ BannerAlertAn alert notification linked to a patient. ](/sdk/data-banner-alert/)[ BillingLineItemA billable code linked to a patient note. ](/sdk/data-billing-line-item/)[ BusinessLineA group of patients that share a common brand under an organization. ](/sdk/data-business-line/)[ CalendarCalendars associated with providers. ](/sdk/data-calendar/)[ CancelPrescriptionA request to cancel a patient's prescription (the CancelPrescription command). ](/sdk/data-cancel-prescription/)[ CancelPrescriptionResponseThe response to a CancelPrescription request. ](/sdk/data-cancel-prescription-response/)[ CanvasUserUser accounts associated with other records. ](/sdk/data-canvasuser/)[ CareTeamTeams assigned for patient care. ](/sdk/data-care-team/)[ Change MedicationA record of a Change Medication command, used to update a medication's directions (sig) without issuing a new prescription. ](/sdk/data-change-medication/)[ ChargeDescriptionMasterBilling charges in Canvas that can be added to the note footer. ](/sdk/data-charge-description-master/)[ ChartSectionReviewReviewed chart sections captured on a note, with their pre-rendered title and narrative content. ](/sdk/data-chart-section-review/)[ ClaimA healthcare claim. ](/sdk/data-claim/)[ ClipboardFree-text content staged on a note by a clipboard command. ](/sdk/data-clipboard/)[ CommandStructured units of documentation in a patient's chart. ](/sdk/data-command/)[ CommandTypeSettingWhether each command type is turned on for the instance. ](/sdk/data-command-type-setting/)[ CommonEnumerationTypesCommon choice classes used in multiple models. ](/sdk/data-enumeration-types/)[ CompoundMedicationCompound medications, which are custom-made medications tailored to a patient's specific needs. ](/sdk/data-compound-medication/)[ ConditionCondition, diagnosis, or reason for seeking medical attention. ](/sdk/data-condition/)[ ContentTypeDjango content type ids used for generic relations and permalink generation. ](/sdk/data-content-type/)[ CoveragePatient insurance coverage. ](/sdk/data-coverage/)[ CreateCodingGapEventA record of a coding gap being created. ](/sdk/data-coding-gap-event/#createcodinggapevent)[ CustomCommandA plugin-defined read-only command recorded on a note (the custom command). ](/sdk/data-custom-command/)[ DeferCodingGapEventA record of a coding gap being deferred. ](/sdk/data-coding-gap-event/#defercodinggapevent)[ DetectedIssueActual or potential clinical issue with or between one or more active or proposed clinical actions for a patient. ](/sdk/data-detected-issue/)[ DeviceType of a manufactured item that is used in the provision of healthcare. ](/sdk/data-device/)[ DiagnosticViewA saved set of lab tests and questionnaire codes whose timeseries can be embedded in a note with the Reference command. ](/sdk/data-diagnostic-view/)[ DMEDurable medical equipment formulary products and the signed orders placed for them with the Order DME command. ](/sdk/data-dme/)[ DocumentReferenceReferences to documents stored in Canvas, with presigned URL support. ](/sdk/data-document-reference/)[ DocumentReviewDelegationA hand-off of a document review from one staff member (or team) to another, with signature consent. ](/sdk/data-document-review-delegation/)[ EducationalMaterialPatient educational material shared from a note via the Educational Material command. ](/sdk/data-educational-material/)[ EligibilityResponseA coverage eligibility (270/271) request and response, with the derived check status. ](/sdk/data-eligibility-response/)[ EligibilitySummarySummary of copay and coinsurance for a Coverage. ](/sdk/data-coverage/#eligibilitysummary)[ EncounterA patient Encounter connected to a Note in Canvas. ](/sdk/data-encounter/)[ ExternalEventExternal clinical events from ADT feeds such as admissions, discharges, and transfers. ](/sdk/data-external-event/)[ FacilityA location where healthcare services are provided. ](/sdk/data-facility/)[ FamilyHistoryA patient's family medical history — conditions recorded for a relative. ](/sdk/data-family-history/)[ FaxFaxes sent or received through Canvas, and the action events that record a document's fax delivery status. ](/sdk/data-fax/)[ FaxStatusModelThe status recorded when Canvas receives a fax. ](/sdk/data-fax/#faxstatusmodel)[ FollowUpA requested follow-up (recall) recorded on a note via the follow_up command. ](/sdk/data-follow-up/)[ GoalA goal for a patient. ](/sdk/data-goal/)[ Google CalendarProvider busy time and connection status from native Google Calendar sync. ](/sdk/data-google-calendar/)[ GroupA stable external identifier linking a Team or PatientGroup, as surfaced by the FHIR Group resource. ](/sdk/data-group/)[ HistoryOfPresentIllnessThe History of Present Illness (HPI) narrative recorded on a note. ](/sdk/data-history-present-illness/)[ ImagingAnalysis of imaging tests to obtain information about the health of a patient. ](/sdk/data-imaging/)[ ImagingOrderActionEventFaxes of an imaging order, with their delivery status. ](/sdk/data-fax/#imagingorderactionevent)[ ImagingReportTemplateTemplates used for imaging reports, defining fields and options. ](/sdk/data-imaging-report-template/)[ ImmunizationA record of a vaccination that is being administered to a patient, either now, in the past, or in the future. ](/sdk/data-immunization/)[ InstructionAn Instruct command committed in a patient's note — clinical guidance such as cessation counseling or dietary instructions. ](/sdk/data-instruction/)[ IntegrationTaskIncoming documents that need processing, including faxes, uploads, and portal submissions. ](/sdk/data-integration-task/)[ IntegrationTaskActionEventFaxes of an integration task, with their delivery status. ](/sdk/data-fax/#integrationtaskactionevent)[ InvoiceA patient statement generated for a patient or guarantor, with its total, delivery method, and status. ](/sdk/data-invoice/)[ LabOrderActionEventFaxes of a lab order, with their delivery status. ](/sdk/data-fax/#laborderactionevent)[ LabPartnerLab partners and the tests they offer within Canvas. ](/sdk/data-lab-partner-and-test/)[ LabReportTemplateTemplates for point-of-care labs and custom lab reports, defining fields and options. ](/sdk/data-lab-report-template/)[ LabsAnalysis of clinical specimens to obtain information about the health of a patient. ](/sdk/data-labs/)[ LetterPatient correspondence letters created within Canvas. ](/sdk/data-letter/)[ LetterActionEventActions taken on a letter, such as printing or faxing. ](/sdk/data-letter-action-event/)[ MedicationA record of a medication that is being consumed by a patient, either now, in the past, or in the future. ](/sdk/data-medication/)[ Medication HistoryA record of a patient's medication history, including medications that were taken in the past but are no longer active. ](/sdk/data-medication-history/)[ Medication StatementA record of a medication statement by a patient from the past. ](/sdk/data-medication-statement/)[ MessageMessages sent to and from Canvas. ](/sdk/data-message/)[ NoteClinical notes on patient charts. ](/sdk/data-note/)[ NoteActionEventFaxes of a note, with their delivery status. ](/sdk/data-fax/#noteactionevent)[ ObservationMeasurements and simple assertions made about a patient. ](/sdk/data-observation/)[ OrganizationThe clinical organization present in the Canvas EMR. ](/sdk/data-organization/)[ OrganizationalEntityExternal entities, such as service providers, referenced by a patient's external care team members. ](/sdk/data-organizational-entity/)[ PatientData used to categorize individuals for identification, records matching, and other purposes. ](/sdk/data-patient/)[ PatientAdministrativeDocumentPatient-facing administrative documents, such as signed consent forms and statements. ](/sdk/data-patient-administrative-document/)[ PatientConsentDocumented patient consents that ensure legal compliance and protect patient rights. ](/sdk/data-patient-consent/)[ PatientGroupA collection of patients. ](/sdk/data-patient-group/)[ PaymentCardA patient's stored payment card on file. ](/sdk/data-payment-card/)[ PayorSpecificChargeA billing charge specific to a certain transactor in Canvas. ](/sdk/data-payor-specific-charge/)[ PlanA Plan (plan of care) narrative recorded on a note. ](/sdk/data-plan/)[ PluginCommandCustom commands registered by plugins via the manifest configuration. ](/sdk/data-plugin-command/)[ PostingPayments and postings associated with healthcare claims. ](/sdk/data-posting/)[ PracticeLocationThe practice locations present in the Canvas EMR. ](/sdk/data-practicelocation/)[ PrescriptionThe practice locations present in the Canvas EMR. ](/sdk/data-prescription/)[ PrescriptionChangeRequestAn incoming Surescripts request to change a prescription, with its medication codings. ](/sdk/data-prescription-change-request/)[ PrescriptionChangeResponseA response (approve/deny) to a Surescripts prescription change request. ](/sdk/data-prescription-change-response/)[ ProcedureA procedure performed on or ordered for a patient, with its CPT codings. ](/sdk/data-procedure/)[ ProtocolCurrentThe current state of clinical protocols applied to patients within Canvas. ](/sdk/data-protocol-current/)[ ProtocolOverrideA record of a protocol being snoozed for a patient. ](/sdk/data-protocol-override/)[ QuestionnaireGroups of coded questions and the coded patient responses. ](/sdk/data-questionnaire/)[ ReasonForVisitThe reason for a patient's visit. ](/sdk/data-reason-for-visit/)[ ReceiptA Canvas-generated payment receipt for a payment collection. ](/sdk/data-receipt/)[ ReferenceThe record of a diagnostic view embedded in a note, with a snapshot of its rendered table. ](/sdk/data-reference/)[ ReferralA referral directing a specific patient to another provider or specialist. ](/sdk/data-referral/)[ ReferralActionEventFaxes of a referral, with their delivery status. ](/sdk/data-fax/#referralactionevent)[ RefillRequestAn incoming request to refill a patient's medication and its responding prescriptions. ](/sdk/data-refill-request/)[ RemoveAllergyEventA record of an allergy being removed via the remove_allergy command. ](/sdk/data-remove-allergy-event/)[ RemovePastMedicalHistoryEventA record of a past medical history entry being removed via the remove_past_medical_history command. ](/sdk/data-remove-past-medical-history-event/)[ ResolveConditionEventA record of a condition being resolved via the resolve_condition command. ](/sdk/data-resolve-condition-event/)[ ServiceProviderData associated with Service Providers. ](/sdk/data-serviceprovider/)[ SnapshotImages captured via the Canvas iOS application. ](/sdk/data-snapshot/)[ SpecialtyReportTemplateTemplates for specialty and referral reports, including specialty taxonomy codes. ](/sdk/data-specialty-report-template/)[ StaffData associated with Staff members. ](/sdk/data-staff/)[ Stop Medication EventA record of a Stop Medication Event, when a medication is removed from a patient's medication list. ](/sdk/data-stop-medication-event/)[ TaskData associated with Tasks. ](/sdk/data-task/)[ TeamData associated with Teams. ](/sdk/data-team/)[ Uncategorized Clinical DocumentsData associated with uncategorized clinical documents and their reviews. ](/sdk/data-uncategorized-clinical-document/)[ VaccineA vaccine in the instance's catalog and the lots of it held in inventory. ](/sdk/data-vaccine/)[ ValidateCodingGapEventA record of a coding gap being validated. ](/sdk/data-coding-gap-event/#validatecodinggapevent)[ ValueSetsLists of codes and terms from various clinical coding systems grouped by a defining concept. ](/sdk/data-value-sets/)[ VisualExamFindingVisual exam findings captured on a note — a titled image with a narrative description. ](/sdk/data-visual-exam-finding/)[ VitalSignReadingVital-sign readings recorded via the vitals command — the reading anchor and its individual measurements. ](/sdk/data-vital-sign-reading/)

---

# Default Homepage

Source: https://docs.canvasmedical.com/sdk/default-homepage-effect/

This allows developers to set a provider's default homepage in Canvas. The default homepage is the page that a provider sees when they log in to Canvas. This effect can be used to set the default homepage to a specific page or a plugin application. For more guidance, see "[How to set a default homepage for the provider application](/guides/set-default-homepage/)".
Build a `DefaultHomepageEffect` with a `page` or an `application_identifier`, then return its `apply()` from a `GET_HOMEPAGE_CONFIGURATION` handler.
##  Methods 
###  apply() → Effect 
Sets the default homepage for the user logging in.
  - Either `page` or `application_identifier` is required. If both are set, `application_identifier` takes precedence and the homepage is that application.
  - `application_identifier` must be the identifier of an installed application.
When no plugin returns this effect, the default homepage is the schedule.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`page`| `Pages` `\| None`| The Canvas page to open.| One of `page` or `application_identifier`  
`application_identifier`| `str \| None`| The identifier of the plugin application to open.| One of `page` or `application_identifier`  
##  Pages 
An enumeration of pages that can be set as the default homepage, accessed as `DefaultHomepageEffect.Pages.<value>`:
Value  
---  
`PATIENTS`  
`SCHEDULE`  
`REVENUE`  
`CAMPAIGNS`  
`DATA_INTEGRATION`  
##  Example 
    ```python
    from canvas_sdk.effects.default_homepage import DefaultHomepageEffect
    DefaultHomepageEffect(page=DefaultHomepageEffect.Pages.PATIENTS).apply()
    ```
    ```python
    from canvas_sdk.effects.default_homepage import DefaultHomepageEffect
    DefaultHomepageEffect(application_identifier="app_identifier").apply()
    ```

---

# Application Notification Badge

Source: https://docs.canvasmedical.com/sdk/effect-application-notification-badge/

Notification badges let your plugin show a count on an [application](/sdk/handlers-applications/), such as how many unread items are waiting.
Where the badge appears depends on the application's [scope](/sdk/handlers-applications/#application-scopes):
Scope| Where the badge appears  
---|---  
`global`| On the application's icon in the app drawer.  
`patient_specific`| On the application's icon in the app drawer, or on the panel when the application sets `show_in_panel`.  
`provider_menu_item`| Next to the application's label in the provider menu.  
`portal_menu_item`| Next to the application's label in the patient portal menu, for the patient who is logged in.  
Applications in other scopes, such as `full_chart` and the Provider Companion scopes, do not show badges.
There are two ways a badge is set:
  - **On load** — override `compute_notification_badge()` on your `Application` handler to provide the initial count shown when Canvas loads applications. See [Notification Badges](/sdk/handlers-applications/#notification-badges) on the Applications handler page.
  - **Live updates** — emit an `ApplicationNotificationBadge` effect from any event handler to update the count in real time, without the user reloading the page. This is what the rest of this page covers.
##  Setting a badge 
`ApplicationNotificationBadge` is a fluent builder. Construct it with the target application's identifier, optionally call `.filter(...)` to target patients, then return `.broadcast(...)` from your handler.
###  Methods 
####  filter(*, patient_ids: list[str] | None = None) → ApplicationNotificationBadge 
Scopes the update to the listed patients: their charts, and their own patient portal. Returns the builder, so the call chains into `.broadcast(...)`.
####  broadcast(count: int, staff_ids: list[str] | None = None) → Effect 
Sets the badge to `count` for the staff and patients you target. See Targeting.
  - `count` is required and must be `>= 0`; a count of `0` clears the badge.
  - The `application_identifier` passed to the constructor must match an installed application, or the effect raises a validation error.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`application_identifier`| `str`| Passed to the constructor. Must match the application's `class` string declared in [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#applications), the `<module path>:<ClassName>` value (identical to the handler's `identifier`).| Yes  
`count`| `int`| Passed to `.broadcast()`. The badge value to display.| Yes  
`staff_ids`| `list[str]`| Passed to `.broadcast()`. Ids of the [staff](/sdk/data-staff/) who should see the update.| No  
`patient_ids`| `list[str]`| Passed to `.filter()`. Ids of the [patients](/sdk/data-patient/) the update applies to: their charts, and their own patient portal.| No  
The `application_identifier` is the application's `class` string from `CANVAS_MANIFEST.json` (`<module path>:<ClassName>`). For example, an `InboxApp` defined in `my_plugin/apps/inbox.py` and registered like this:
    ```json
    "applications": [
      {
        "class": "my_plugin.apps.inbox:InboxApp",
        "name": "Inbox",
        "description": "Unread items inbox",
        "icon": "/assets/inbox.png",
        "scope": "global"
      }
    ]
    ```
is targeted by that same `class` string:
    ```python
    from canvas_sdk.effects.application_notification_badge import ApplicationNotificationBadge
    # Set a badge of 3 for a specific staff member.
    ApplicationNotificationBadge("my_plugin.apps.inbox:InboxApp").broadcast(count=3, staff_ids=["staff-id"])
    ```
##  Targeting 
`staff_ids` and `patient_ids` control who sees the update. An empty list means "all" on that axis:
`staff_ids`| `patient_ids`| Who sees the badge  
---|---|---  
set| empty| The listed staff, on any patient (and on global views).  
empty| set| Staff currently viewing the listed patients' charts, and the listed patients in the patient portal.  
set| set| The listed staff, but only while viewing the listed patients' charts.  
empty| empty| All staff, all patients (a system-wide update). The patient portal is not updated.  
The patient portal receives an update only when you set `patient_ids` and leave `staff_ids` empty. Each listed patient sees the new count on the matching `portal_menu_item` application while they're logged in to the portal. Updates that name staff, and system-wide updates, never reach the portal. A patient only ever receives updates sent for their own id.
Because `patient_ids` reaches both audiences, the application's scope decides where the badge appears. A `patient_specific` application shows it to staff on the chart. A `portal_menu_item` application shows it to the patient in the portal.
> **Note on "all patients" (empty`patient_ids`):** the update is delivered **live** only to charts a staff member currently has open. Other patients' charts reflect the new value the next time they're loaded, via `compute_notification_badge()`. So for a badge that should read the same across every patient, have `compute_notification_badge()` return a patient-independent count (ignore the patient in `self.event.context`). A push then keeps the open chart live, and the load-time hook covers the rest.
    ```python
    from canvas_sdk.effects.application_notification_badge import ApplicationNotificationBadge
    # Show a badge to staff viewing a specific patient's chart.
    ApplicationNotificationBadge("my_plugin.apps.patient_labs:PatientLabsApp").filter(
        patient_ids=["patient-id"]
    ).broadcast(count=5)
    # Show a badge to a patient in the patient portal (portal_menu_item application).
    ApplicationNotificationBadge("my_plugin.apps.messages:PortalMessagesApp").filter(
        patient_ids=["patient-id"]
    ).broadcast(count=2)
    # Combine: only the on-call provider, and only on this patient's chart.
    ApplicationNotificationBadge("my_plugin.apps.patient_labs:PatientLabsApp").filter(
        patient_ids=["patient-id"]
    ).broadcast(count=1, staff_ids=["staff-id"])
    ```
##  Reacting to events 
The most common pattern is updating a badge in response to a domain event. Here a handler recomputes a staff member's inbox count whenever a task is created and pushes the new value live:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.application_notification_badge import ApplicationNotificationBadge
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.task import Task, TaskStatus
    class InboxBadgeHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.TASK__CREATED)
        def compute(self) -> list[Effect]:
            task = Task.objects.get(id=self.event.target.id)
            assignee = task.assignee
            if not assignee:
                return []
            open_count = Task.objects.filter(assignee=assignee, status=TaskStatus.OPEN).count()
            return [
                ApplicationNotificationBadge("my_plugin.apps.inbox:InboxApp").broadcast(
                    count=open_count,
                    staff_ids=[assignee.id],
                )
            ]
    ```
##  Clearing a badge 
Broadcast a `count` of `0` to remove the badge from the icon:
    ```python
    from canvas_sdk.effects.application_notification_badge import ApplicationNotificationBadge
    ApplicationNotificationBadge("my_plugin.apps.inbox:InboxApp").broadcast(count=0, staff_ids=["staff-id"])
    ```
> **Note:** To set the badge value shown when applications first load (rather than in response to an event), override `compute_notification_badge()` on your `Application` handler. See [Notification Badges](/sdk/handlers-applications/#notification-badges).

---

# Appointment Labels

Source: https://docs.canvasmedical.com/sdk/effect-appointment-labels/

#  Appointment Label Effects 
The appointment label effects provide programmatic management of labels in Canvas. Labels serve as visual indicators and categorization tools, enabling automated workflows and improved organization for appointments.
##  Overview 
Labels are a powerful way to categorize and track appointments. Canvas supports up to 3 labels per appointment, and these effects allow plugins to automatically manage labels based on business logic.
##  AddAppointmentLabel Effect 
The `AddAppointmentLabel` effect adds one or more labels to an existing appointment.
###  Methods 
####  apply() → Effect 
Adds the specified labels to the appointment.
#####  Returns 
An `Effect` object configured for adding appointment labels.
#####  Behavior 
  - Labels are added to the appointment if the total count doesn't exceed 3
  - Labels are automatically sorted for consistency
  - Duplicate labels are ignored (labels are stored as a set)
  - Validates the appointment exists before adding labels
  - Validates label names are non-empty strings
  - Returns an error if adding labels would exceed the 3-label limit
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`appointment_id`| `str`| ID of the appointment to add labels to| Yes  
`labels`| `set[str]`| Set of label names to add (1-3 labels total per appointment)| Yes  
###  Example 
    ```python
    from canvas_sdk.effects.note.appointment import AddAppointmentLabel
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.APPOINTMENT_CREATED)]
        def compute(self):
            # Add labels to an appointment
            effect = AddAppointmentLabel(
                appointment_id="appointment-uuid",
                labels={"URGENT", "FOLLOW_UP"}
            )
            return [effect.apply()]
    ```
If more than three labels are attempted to be added, a `ValidationError` will be raised.
    ```python
    from canvas_sdk.effects.note.appointment import AddAppointmentLabel
    from canvas_sdk.exceptions import ValidationError
    def handle_validation_errors():
        # Example of handling validation errors
        try:
            effect = AddAppointmentLabel(
                appointment_id="invalid-id",
                labels={"LABEL1", "LABEL2", "LABEL3", "LABEL4"}  # Would exceed limit
            )
            return [effect.apply()]
        except ValidationError as e:
            # Handle validation errors
            return []
    ```
* * *
##  RemoveAppointmentLabel Effect 
The `RemoveAppointmentLabel` effect removes one or more labels from an existing appointment.
###  Methods 
####  apply() → Effect 
Removes the specified labels from the appointment.
#####  Returns 
An `Effect` object configured for removing appointment labels.
#####  Behavior 
  - Removes the specified labels from the appointment
  - Non-existent labels are ignored (no error thrown)
  - Validates the appointment exists before removing labels
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`appointment_id`| `str`| ID of the appointment to remove labels from| Yes  
`labels`| `set[str]`| Set of label names to remove| Yes  
###  Example 
    ```python
    from canvas_sdk.effects.note.appointment import RemoveAppointmentLabel
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.APPOINTMENT_LABEL_REMOVED)]
        def compute(self):
            # Remove labels from an appointment
            effect = RemoveAppointmentLabel(
                appointment_id="appointment-uuid",
                labels={"CANCELLED", "RESCHEDULED"}
            )
            return [effect.apply()]
    ```
* * *
##  Implementation Details 
###  Label Constraints 
  - **Maximum labels** : 3 labels per appointment (enforced by validation)
  - **Label format** : Labels are strings, automatically sorted for consistency
  - **Uniqueness** : Labels are stored as a set, preventing duplicates
  - **Case sensitivity** : Label names are case-sensitive
###  Validation Messages 
The effects provide clear error messages for common issues:
  - `"Appointment {appointment_id} does not exist"` \- When appointment ID is invalid
  - `"Limit reached: Only 3 appointment labels allowed. Attempted to add {count} label(s) to appointment with {existing} existing label(s)."` \- When label limit would be exceeded
These effects work seamlessly with appointment label events:
  - `APPOINTMENT_LABEL_ADDED` \- Fired when labels are added
  - `APPOINTMENT_LABEL_REMOVED` \- Fired when labels are removed
For more information on these events, see [Appointment Events](/sdk/events/#appointments).
##  Related Documentation 
  - [Appointment Events](/sdk/events/#appointments) \- Event documentation
  - [Appointment Coverage Label Example](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/appointment_coverage_label) \- Real-world example plugin

---

# AppointmentMetadata Effect

Source: https://docs.canvasmedical.com/sdk/effect-appointment-metadata/

The `AppointmentMetadata` effect provides a flexible key-value storage system for appointment-specific data within the Canvas system. This effect enables the creation and updating of custom metadata entries associated with appointment records. This allows for extensible appointment information storage beyond standard scheduling fields.
##  Overview 
Appointment metadata serves as a powerful extension mechanism for storing custom appointment-related information that doesn't fit within the standard appointment data model. It uses the `.upsert(value)` method to apply a value to the key attributed with the Metadata effect object.
##  Methods 
###  upsert(value: str) → Effect 
Creates or updates a metadata entry for the specified appointment and key combination.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`value`| `str`| The metadata value to store| Yes  
####  Returns 
An `Effect` object configured for upserting appointment metadata.
####  Behavior 
  - If a metadata entry with the specified key already exists for the appointment, it will be updated with the new value
  - If no entry exists, a new metadata entry will be created
  - The operation is idempotent - repeated calls with the same key and value will not create duplicate entries
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`appointment_id`| `str`| Id of the [Appointment](/sdk/data-appointment/) record to associate metadata with| Yes  
`key`| `str`| Unique identifier for the metadata entry within the appointment context| Yes  
##  Implementation Details 
###  Validation 
The effect performs comprehensive validation before execution:
  1. **Appointment Existence Validation** : Verifies that the referenced appointment exists in the system
  - Queries the appointment database to confirm the `appointment_id` corresponds to an existing appointment record
  - Returns a descriptive error if the appointment is not found
  1. **Field Validation** : Ensures all required fields are provided and properly formatted
  - Both `appointment_id` and `key` must be non-empty strings
  - The `value` parameter in the `upsert` method must be provided
###  Data Structure 
The effect payload is structured as JSON with the following schema:
    ```json
    {
      "data": {
        "appointment_id": "appointment-id",
        "key": "metadata-key",
        "value": "metadata-value"
      }
    }
    ```
##  Example Usage 
###  Basic Usage 
    ```python
    from canvas_sdk.effects.appointments_metadata.base import AppointmentsMetadata
    # Create a metadata entry for appointment state
    metadata = AppointmentsMetadata(
        appointment_id="550e8400e29b41d4a716446655440001",
        key="state"
    )
    # Upsert the metadata value
    effect = metadata.upsert("CA")
    ```
##  Best Practices 
###  Key Naming Conventions 
  1. **Use Descriptive Names** : Choose keys that clearly indicate the purpose of the metadata
  - Good: `external_mrn`, `preferred_pharmacy_id`, `risk_score_diabetes`
  - Avoid: `data1`, `temp`, `misc`
  1. **Namespace Your Keys** : When building integrations or modules, prefix keys to avoid collisions
  - Example: `integration_patient_id`, `module_diabetes_last_a1c_date`
###  Value Storage 
  1. **String Serialization** : All values are stored as strings. For complex data types:
         ```python
         import json
         from canvas_sdk.effects.appointments_metadata.base import AppointmentsMetadata
         metadata = AppointmentsMetadata(
             appointment_id="550e8400e29b41d4a716446655440001",
             key="result"
         )
         complex_data = {"scores": [85, 92, 78], "average": 85.0}
         metadata.upsert(json.dumps(complex_data))
         ```
  2. **Boolean Values** : Store as "true" or "false" strings for consistency
         ```python
         from canvas_sdk.effects.appointments_metadata.base import AppointmentsMetadata
         consented = True
         metadata = AppointmentsMetadata(
             appointment_id="550e8400e29b41d4a716446655440001",
             key="boolean_value"
         )
         metadata.upsert("true" if consented else "false")
         ```
##  Notes 
  - Metadata entries are appointment-specific and isolated - the same key can have different values for different appointments
  - There is no built-in versioning; updating a key overwrites the previous value
  - The system does not enforce any schema on metadata values - validation is the responsibility of the implementing code

---

# Banner Alerts

Source: https://docs.canvasmedical.com/sdk/effect-banner-alerts/

Use banner alerts to show contextual information in a patient's chart.
> **Warning:** A banner alert belongs to the plugin that added it. Disabling the plugin hides its banners, and [uninstalling](/sdk/canvas_cli/#canvas-uninstall) it deletes them.
##  Adding a Banner Alert 
To add a banner alert, build an `AddBannerAlert` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Adds the banner alert.
  - `key`, `narrative`, `placement`, and `intent` are required, along with either `patient_id` or `patient_filter`.
  - `narrative` can be at most 90 characters.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
patient_id| String| The id of the [patient](/sdk/data-patient/) the alert should be associated with.| If `patient_filter` is not provided  
patient_filter| dict| A patient filter that applies the effect to every matching patient. For example, `{"active": True}` applies the effect to all active patients| If `patient_id` is not provided  
key| String| An identifier that categorizes the alert.| Yes  
narrative| String| The content of the alert. Maximum 90 characters.| Yes  
placement| list[Placement]| List of areas the alert should show.| Yes  
intent| Intent| Affects the styling of the alert.| Yes  
href| String| If given, the alert will appear as a link to this URL.| No  
###  Example 
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.banner_alert import AddBannerAlert
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_UPDATED)
        def compute(self):
            banner = AddBannerAlert(
                patient_id=self.target,
                key="test-alert",
                narrative="This is only a test.",
                placement=[
                    AddBannerAlert.Placement.CHART,
                    AddBannerAlert.Placement.APPOINTMENT_CARD,
                    AddBannerAlert.Placement.SCHEDULING_CARD,
                ],
                intent=AddBannerAlert.Intent.INFO,
                href="https://docs.canvasmedical.com",
            )
            return [banner.apply()]
    ```
To apply the effect to all active patients when a plugin is created or updated, include the `PLUGIN_CREATED` and/or `PLUGIN_UPDATED` events in the `RESPONDS_TO` list. Additionally, `patient_filter` can be used (instead of `patient_id`) on the `AddBannerAlert` class.
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.banner_alert import AddBannerAlert
    class MyHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.PATIENT_UPDATED),
            EventType.Name(EventType.PLUGIN_CREATED),
            EventType.Name(EventType.PLUGIN_UPDATED),
        ]
        def compute(self):
            banner = AddBannerAlert(
                key="test-alert",
                narrative="This is only a test.",
                placement=[
                    AddBannerAlert.Placement.CHART,
                    AddBannerAlert.Placement.APPOINTMENT_CARD,
                    AddBannerAlert.Placement.SCHEDULING_CARD,
                ],
                intent=AddBannerAlert.Intent.INFO,
                href="https://docs.canvasmedical.com",
            )
            if self.event.type in [EventType.PLUGIN_CREATED, EventType.PLUGIN_UPDATED]:
                banner.patient_filter = {"active": True}
            else:
                banner.patient_id = self.target
            return [banner.apply()]
    ```
###  Placement 
This determines where the banner alert appears.
####  `Placement.CHART`
This will place the banner under the patient's name on their chart
![](/assets/images/sdk/banner-alerts/banner_alert_placement_chart.png)
####  `Placement.TIMELINE`
This will place the banner on the top of the patient's timeline of notes in their chart
![](/assets/images/sdk/banner-alerts/banner_alert_placement_timeline.png)
####  `Placement.APPOINTMENT_CARD`
This will appear when you click an appointment on the calendar view
![](/assets/images/sdk/banner-alerts/banner_alert_placement_appointment_card.png)
####  `Placement.SCHEDULING_CARD`
This will appear when you select a patient during the scheduling of an appointment on the calendar view
![](/assets/images/sdk/banner-alerts/banner_alert_placement_scheduling_card.png)
####  `Placement.PROFILE`
This will place the banner under the patient's name on their patient registration page
![](/assets/images/sdk/banner-alerts/banner_alert_placement_profile.png)
###  Intent 
The type or severity of an alert. This will change the appearance of the banner alert.
####  `Intent.INFO`
![](/assets/images/sdk/banner-alerts/banner_alert_intent_info.png)
####  `Intent.WARNING`
![](/assets/images/sdk/banner-alerts/banner_alert_intent_warning.png)
####  `Intent.ALERT`
![](/assets/images/sdk/banner-alerts/banner_alert_intent_alert.png)
##  Removing a Banner Alert 
To remove a banner alert, build a `RemoveBannerAlert` identifying the alert's key and patient, and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Removes the banner alert.
  - `key` is required, along with either `patient_id` or `patient_filter`.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
patient_id| String| The id of the [patient](/sdk/data-patient/) whose alert should be removed.| If `patient_filter` is not provided  
patient_filter| dict| A patient filter that removes the alert from every matching patient.| If `patient_id` is not provided  
key| String| The key of the alert to remove.| Yes  
###  Example 
    ```python
    from canvas_sdk.effects.banner_alert import RemoveBannerAlert
    banner_alert = RemoveBannerAlert(
        key='test-alert',
        patient_id="d4c933fe8f6948f6a7d2a42a2641b13b",
    )
    banner_alert.apply()
    ```
##  Patient filters 
A `patient_filter` selects patients by patient field. Each key is a field name, optionally followed by `__` and a lookup, such as `"last_name__istartswith": "Sm"`. These fields are supported:
  - `id`, `key`, and `mrn`
  - `active` and `deceased`
  - `first_name`, `middle_name`, `last_name`, and `nickname`
  - `birth_date` and `sex_at_birth`
  - `external_identifiers__system` and `external_identifiers__value`
These lookups are supported: `exact`, `iexact`, `in`, `lt`, `lte`, `gt`, `gte`, `range`, `isnull`, `startswith`, `istartswith`, `endswith`, `iendswith`, `contains`, and `icontains`.
Each value is a string, number, boolean, `None`, or a list of strings, numbers, or booleans.

---

# Batch Originate Commands

Source: https://docs.canvasmedical.com/sdk/effect-batch-originate/

##  Overview 
The `BatchOriginateCommandEffect` provides an efficient way to insert multiple commands into a note simultaneously. When you need to create many commands at once, using batch originate significantly improves performance compared to individual originate operations.
Build a `BatchOriginateCommandEffect` with the commands to insert, then return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Originates every command in `commands` in a single operation.
  - `commands` is required, and each command needs the fields its own `originate()` requires.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`commands`| `list`| List of command instances to batch originate.| Yes  
`line_number`| `int`| Which note line the commands land on. Defaults to `-1`, which inserts them at the bottom of the note; set a specific line to target that line instead. Combine with `replace_line=True` to also take over (replace the content of) that line.| No  
`replace_line`| `bool`| Replace the content of the target line (the one set by `line_number`) with the originated commands, instead of inserting them as new lines. Defaults to `False`.| No  
##  How It Works 
The batch originate effect processes multiple commands in a single operation:
  1. **Command Preparation** : Each command in the list requires all necessary fields for `originate`
  2. **Note Update** : The note is updated once with all command UUIDs, rather than updating for each command individually
This approach minimizes database round-trips and improves overall performance.
##  Commit behavior 
`BatchOriginateCommandEffect` originates commands in the **uncommitted (draft)** state only. The batch effect has no `commit` option — every command in the batch is inserted into the note body as a draft.
Batch originating commands in a committed state is **not supported** , by design. The performance benefit of batching comes from collapsing the note update for many draft insertions into a single operation, and committing is a separate, per-command action with no equivalent batch saving.
Whenever a plugin needs to originate more than one command — whether you want them left as drafts or committed — batch origination is the right tool. To end up with committed commands, batch originate the drafts first so the note is updated once, then commit each command individually. Assign each command a `command_uuid` up front so it can be committed after it is originated:
    ```python
    from uuid import uuid4
    # Set command_uuid so each draft can be committed after batch origination
    plan1.command_uuid = str(uuid4())
    assess.command_uuid = str(uuid4())
    # One note update for all drafts, followed by a commit per command
    return [
        BatchOriginateCommandEffect(commands=[plan1, assess]).apply(),
        plan1.commit(),
        assess.commit(),
    ]
    ```
For three commands this performs three originates, **one** note update, and three commits. Collapsing the draft insertions into a single note update is where the performance benefit comes from.
##  Note body automations 
A [note body automation](/sdk/handlers-action-buttons/) is an entry a plugin adds to the note body's "/" command list. When a clinician selects the entry, the automation's `handle()` returns a `BatchOriginateCommandEffect` with `replace_line=True`. In this flow Canvas's note body "/" handling supplies the trigger-line position, so Canvas places the originated commands on the line the clinician typed the trigger on and replaces that line, rather than appending them to the note. The automation doesn't set `line_number` itself. If a plugin omits `replace_line`, it keeps its default of `False`, and the batch follows the effect's normal defaults: the originated commands insert at the bottom of the note (the `line_number=-1` default) rather than taking over the trigger line.
    ```python
    return [
        BatchOriginateCommandEffect(
            commands=[plan],
            replace_line=True,
        ).apply()
    ]
    ```
##  Example 
    ```python
    from canvas_sdk.commands import (
        PlanCommand,
        HistoryOfPresentIllnessCommand,
        QuestionnaireCommand,
        AssessCommand
    )
    from canvas_sdk.effects.batch_originate import BatchOriginateCommandEffect
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Questionnaire, Note
    from canvas_sdk.events import EventType
    class Handler(BaseHandler):
        def compute(self):
            note_uuid = str(Note.objects.last().id)
            # Create multiple commands
            plan1 = PlanCommand()
            plan1.narrative = "Order labs for lipid panel"
            plan1.note_uuid = note_uuid
            plan2 = PlanCommand()
            plan2.narrative = "Schedule follow-up in 3 months"
            plan2.note_uuid = note_uuid
            hpi = HistoryOfPresentIllnessCommand()
            hpi.narrative = "Annual wellness visit"
            hpi.note_uuid = note_uuid
            assess = AssessCommand()
            assess.icd10_code = "E11.9"
            assess.note_uuid = note_uuid
            assess.background = "Type 2 diabetes mellitus"
            # Add a questionnaire
            questionnaire = QuestionnaireCommand()
            questionnaire.note_uuid = note_uuid
            questionnaire_id = Questionnaire.objects.filter(
                name="Patient Health Questionnaire"
            ).first()
            if questionnaire_id:
                questionnaire.questionnaire_id = str(questionnaire_id.id)
            # Batch originate all commands
            commands_to_originate = [plan1, plan2, hpi, assess, questionnaire]
            return [BatchOriginateCommandEffect(commands=commands_to_originate).apply()]
    ```
##  Related Documentation 
  - [Commands Overview](/sdk/commands)

---

# Billing Line Items

Source: https://docs.canvasmedical.com/sdk/effect-billing-line-items/

The Canvas SDK allows you to create, update, and remove Billing Line Items from the footer of a note.
##  Adding a Billing Line Item 
To add a billing line item to a note, build an `AddBillingLineItem` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Adds the billing line item to the note's footer.
  - `note_id` and `cpt` are required.
  - `units` defaults to `1`.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
note_id| String| The id of the [Note](/sdk/data-note/) where the line item should be associated.| Yes  
cpt| String| The billing code to use for the line item.| Yes  
units| Integer| The number of units to bill for the code. Defaults to `1` if not provided.| No  
assessment_ids| list[String]| List of Assessment ids from the note that are relevant to the code, also referred to as "diagnosis pointers".| No  
modifiers| list[Coding]| The modifiers to create with the billing code.| No  
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Command, Assessment
    from canvas_sdk.effects.billing_line_item import AddBillingLineItem
    class MyHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.PERFORM_COMMAND__POST_ORIGINATE)
        ]
        def compute(self) -> list[Effect]:
            command_id = self.target
            command = Command.objects.get(id=command_id)
            note = command.note
            assessments = [
                str(i)
                for i in Assessment.objects.filter(note_id=note.dbid).values_list(
                    "id", flat=True
                )
            ]
            b = AddBillingLineItem(
                note_id=str(note.id),
                cpt="99213",
                units=1,
                assessment_ids=assessments,
                modifiers=[
                    {"code": "25", "system": "http://www.ama-assn.org/go/cpt"},
                    {"code": "59", "system": "http://www.ama-assn.org/go/cpt"},
                ],
            )
            return [b.apply()]
    ```
You don't set the line item's description in your plugin. When the line item is created, Canvas matches the `cpt` to a [ChargeDescriptionMaster](/sdk/data-charge-description-master/) charge and populates the description from that charge's `short_name`, truncated to 255 characters. If no charge matches the `cpt`, the description is left empty.
###  Adding billing codes from an external system 
To populate diagnosis and CPT codes in a note footer from an external billing system, expose a [SimpleAPI](/sdk/handlers-simple-api-http/) endpoint that the system can call. The endpoint receives the note, CPT code, units, and ICD-10 codes, matches the ICD-10 codes to the note's assessments, and returns an `AddBillingLineItem` effect whose `assessment_ids` act as the line item's diagnosis pointers. This example authenticates with [`APIKeyAuthMixin`](/sdk/handlers-simple-api-http/#authentication-mixins), which checks requests against a plugin secret named `simpleapi-api-key`:
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.billing_line_item import AddBillingLineItem
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPIRoute
    from canvas_sdk.v1.data.assessment import Assessment
    class BillingAPI(APIKeyAuthMixin, SimpleAPIRoute):
        PATH = "/billing/add-line-item"
        def post(self) -> list[Response | Effect]:
            # {"note_id": "...", "cpt_code": "99213", "units": 1, "icd10_codes": ["E119", "I10"]}
            body = self.request.json()
            note_id = body["note_id"]
            icd10_codes = {code.upper().replace(".", "") for code in body.get("icd10_codes", [])}
            # Use each of the note's assessments whose condition carries a requested ICD-10 code
            assessment_ids = [
                str(assessment.id)
                for assessment in Assessment.objects.filter(note__id=note_id).select_related("condition")
                if assessment.condition
                and any(
                    coding.system == "ICD-10" and coding.code.upper().replace(".", "") in icd10_codes
                    for coding in assessment.condition.codings.all()
                )
            ]
            effect = AddBillingLineItem(
                note_id=note_id,
                cpt=body["cpt_code"],
                units=body.get("units", 1),
                assessment_ids=assessment_ids,
            )
            return [
                effect.apply(),
                JSONResponse(
                    {"message": "Billing line item sent to Canvas", "assessment_ids": assessment_ids},
                    status_code=HTTPStatus.CREATED,
                ),
            ]
    ```
The [`cpt-billing-api` example plugin](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/cpt-billing-api/cpt_billing_api) builds on this with request validation, a check that the CPT code is active in the charge description master, and a response listing which ICD-10 codes matched.
> **Warning:** The billing line item is added to the note footer, not directly to a claim. As with any billing change, it must be applied before the note is locked, because locking pushes the note's charges to the claim. To apply it to the claim right away instead of at lock time, follow it with the Note effect's [`push_charges()`](/sdk/effect-notes/#push-charges) on the same note. If the API call succeeds but nothing appears on the note, confirm the note is unlocked and that the `note_id` resolves to the intended note.
##  Updating a Billing Line Item 
To update a billing line item, build an `UpdateBillingLineItem` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Updates the billing line item.
  - `billing_line_item_id` is required.
  - Only the attributes you set on the effect are changed. Attributes you leave unset keep their current values.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
billing_line_item_id| String| The id of the [BillingLineItem](/sdk/data-billing-line-item/) to update.| Yes  
cpt| String| The billing code to use for the line item.| No  
units| Integer| The number of units to bill for the code.| No  
assessment_ids| list[String]| List of Assessment ids from the note that are relevant to the code, also referred to as "diagnosis pointers".| No  
modifiers| list[Coding]| The modifiers to create with the billing code.| No  
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Assessment, Command, BillingLineItem
    from canvas_sdk.effects.billing_line_item import UpdateBillingLineItem
    class MyHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.PERFORM_COMMAND__POST_COMMIT)
        ]
        def compute(self) -> list[Effect]:
            command_id = self.target
            command = Command.objects.get(id=command_id)
            note = command.note
            cpt = command.data["perform"]["value"]
            b_ids = BillingLineItem.objects.filter(cpt="99213", note=note).values_list(
                "id", flat=True
            )
            assessment = Assessment.objects.filter(note_id=note.dbid).first()
            updates = [
                UpdateBillingLineItem(
                    billing_line_item_id=str(b_id),
                    cpt=cpt,
                    units=1,
                    assessment_ids=[str(assessment.id)],
                    modifiers=[{"code": "47", "system": "http://www.ama-assn.org/go/cpt"}],
                )
                for b_id in b_ids
            ]
            return [update.apply() for update in updates]
    ```
##  Removing a Billing Line Item 
To remove a billing line item, build a `RemoveBillingLineItem` and return its `apply()` from your handler.
When a Perform command is entered in error, Canvas removes the billing line item that the command added to the note footer. You don't need a plugin to remove it.
###  Methods 
####  apply() → Effect 
Removes the billing line item from the note's footer.
  - `billing_line_item_id` is required.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
billing_line_item_id| String| The id of the [BillingLineItem](/sdk/data-billing-line-item/) to remove.| Yes  
###  Example 
When a Perform command is entered in error, this handler removes every billing line item on the note that has the command's CPT code. That includes matching line items that came from other sources, such as another plugin, which Canvas doesn't remove on its own.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Command, BillingLineItem
    from canvas_sdk.effects.billing_line_item import RemoveBillingLineItem
    class MyHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.PERFORM_COMMAND__POST_ENTER_IN_ERROR)
        ]
        def compute(self) -> list[Effect]:
            command_id = self.target
            command = Command.objects.get(id=command_id)
            cpt = command.data["perform"]["value"]
            note_id = command.note.dbid
            b_ids = BillingLineItem.objects.filter(cpt=cpt, note_id=note_id).values_list(
                "id", flat=True
            )
            return [
                RemoveBillingLineItem(billing_line_item_id=str(b_id)).apply()
                for b_id in b_ids
            ]
    ```
For more information about the BillingLineItem data class, check out [this page](/sdk/data-billing-line-item).

---

# Charge Stored Card

Source: https://docs.canvasmedical.com/sdk/effect-charge-stored-card/

The `ChargeStoredCard` effect charges a patient's stored payment card through the payment processor configured for your Canvas instance. The charge is processed server-side against the tokenized card, so no card data crosses the plugin boundary.
You reference the card by an identifier the configured processor understands, never the underlying processor token:
  - The built-in Stripe processor takes the Canvas [PaymentCard](/sdk/data-payment-card/) id.
  - A [custom payment processor](/sdk/handlers-payment-processors/) takes whichever reference that processor manages.
> **Warning:** **You are responsible for obtaining patient consent before charging a stored card.** Canvas does not enforce consent for charges initiated through this effect.
##  Imports 
    ```python
    from canvas_sdk.effects.payment import ChargeStoredCard
    ```
##  Charging a stored card 
Build a `ChargeStoredCard` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Charges the stored card.
  - `patient_id`, `payment_card_id`, `amount`, and `idempotency_key` are required, and `patient_id` must be the id of an existing patient.
  - `claim_id` is required when `copay` is `true`, and must be the id of an existing claim when set.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
patient_id| String| The Canvas [Patient](/sdk/data-patient/#patient) id to charge.| Yes  
payment_card_id| String| A reference to the stored card that the configured processor resolves: the Canvas [PaymentCard](/sdk/data-payment-card/) id for the built-in Stripe processor, or a custom processor's own reference.| Yes  
amount| Decimal| The amount to charge, in dollars, with up to two decimal places (for example, `Decimal("49.99")`). Must be greater than `0`.| Yes  
idempotency_key| UUID or String| A key that makes the charge safe to retry. Reusing the same key for a retry guarantees the patient is not charged twice. See Idempotency.| Yes  
claim_id| UUID or String| A [Claim](/sdk/data-claim/) id to post the payment against. When omitted, the payment is allocated across the patient's outstanding balance. See Payment allocation.| When `copay` is `true`  
copay| Boolean| Whether the charge is a copay. When `true`, the amount is posted to the claim's copay line item; requires `claim_id`. Defaults to `false`. See Payment allocation.| No  
description| String| A free-text description to record with the payment. It has no length limit, and is recorded only on a charge that names a `claim_id`.| No  
###  Example 
    ```python
    from decimal import Decimal
    from uuid import uuid5, NAMESPACE_URL
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.payment import ChargeStoredCard
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Patient
    class ChargeBalanceOnBooking(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.APPOINTMENT_CREATED)]
        def compute(self) -> list[Effect]:
            # APPOINTMENT_CREATED targets the appointment; the patient is in the context.
            appointment_id = self.event.target.id
            patient = Patient.objects.get(id=self.event.context["patient"]["id"])
            card = patient.payment_cards.filter(is_default=True).first()
            if card is None:
                return []
            charge = ChargeStoredCard(
                patient_id=str(patient.id),
                payment_card_id=str(card.id),
                amount=Decimal("25.00"),
                idempotency_key=uuid5(NAMESPACE_URL, f"appointment-{appointment_id}-balance"),
            )
            return [charge.apply()]
    ```
This charge names no `claim_id`, so it pays down the patient's outstanding balance and is rejected unless that balance covers the amount. To take a copay instead, supply the `claim_id` it belongs to and set `copay=True`. See Payment allocation.
###  Validation 
`.apply()` raises a `ValidationError` when:
  - The `patient_id` does not match a patient.
  - A supplied `claim_id` does not match a claim.
  - `copay` is set without a `claim_id`.
The card itself is not checked here. `payment_card_id` is resolved and validated server-side when the charge is processed, so a reference the configured processor cannot resolve arrives as an error on the response event rather than raising from `.apply()`. See Error codes for the code each processor reports.
###  Card ownership 
Under the built-in Stripe processor, Canvas looks the card up scoped to `patient_id`, so a card belonging to a different patient, or one that has been removed, is rejected as `card_not_found` before the card is charged.
A [custom payment processor](/sdk/handlers-payment-processors/) keeps its own cards, which Canvas cannot see, so it passes `payment_card_id` through without checking it. On a custom processor, confirming that a card reference belongs to the patient being charged is the processor's responsibility.
##  Idempotency 
Every charge requires an `idempotency_key`. Pass either a `UUID` object or its string form, dashed or not; a string that does not parse as a UUID is rejected.
Reusing the same key on a retry guarantees the patient is not charged twice, so the key must be **stable across retries of the same logical charge**. Generate it deterministically from a stable identifier — for example `uuid5(namespace, f"appointment-{id}-charge")` — or persist a `uuid4` before emitting the effect. Do not generate a fresh key on each attempt.
##  Payment allocation 
The payment is always applied to the patient's account:
  - **Outstanding balance (default).** When no `claim_id` is given, the payment is allocated across the patient's outstanding balance. This is the only case where the amount is measured against a balance: the charge is rejected before the card is touched if the patient has no outstanding balance, and again if the amount exceeds it, so every charged dollar lands on a claim.
  - **Against a specific claim.** When `claim_id` is given and `copay` is left `false` (the default), the payment pays down that claim's non-copay line-item balances. The charge is rejected if the claim has nothing to charge against, but the amount is not capped at the claim's balance, so an amount above it leaves the claim in credit.
  - **As a copay on a claim.** When `claim_id` is given with `copay` set to `true`, the amount is recorded as a copay on that claim, posted to its copay line item. No balance is checked at all, so use this to collect a copay or prepayment against a claim that carries nothing to charge.
##  Reconciling the charge 
Once the charge has been processed, Canvas emits a [`REVENUE__STORED_CARD__CHARGE_RESPONSE`](/sdk/events/#stored-card-charge-events) event carrying the outcome. It fires whether or not the card was charged, and nothing a handler returns changes the charge, so handle it to reconcile rather than to intervene.
The event targets the patient that was charged: `self.event.target.id` is the patient id, and `self.event.target.instance` is the [Patient](/sdk/data-patient/#patient). Its actor is the one that emitted the originating effect.
Correlate each response with the charge that produced it using the `idempotency_key` you supplied on the request. It is the only field that ties the two together, since nothing in the response identifies the handler that asked for the charge.
This handler records the result of each charge, reading `payment_intent_id` when it succeeds and the `error` object when it does not:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    class ReconcileStoredCardCharge(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.REVENUE__STORED_CARD__CHARGE_RESPONSE)]
        def compute(self) -> list[Effect]:
            context = self.event.context
            idempotency_key = context["idempotency_key"]
            if context["success"]:
                payment_intent_id = context["payment_intent_id"]
                log.info(f"Charge {idempotency_key} succeeded: {payment_intent_id}")
            else:
                error = context["error"]
                log.error(f"Charge {idempotency_key} failed [{error['code']}]: {error['message']}")
            return []
    ```
###  Response context 
`self.event.context` arrives already parsed as a dictionary, so read the fields from it directly. It carries no card data or PHI. Apart from `success`, which is a boolean, and `error`, which is an object, every value is a string or `null`, including the amount and the ids that were UUIDs on the request, so cast `amount` before doing arithmetic on it.
Field| Type| Description  
---|---|---  
success| Boolean| Whether the charge succeeded.  
payment_intent_id| String or null| The processor's payment identifier on success — the Stripe PaymentIntent id, or a custom processor's transaction id. `null` on failure.  
error| Object or null| `null` on success. On failure, `error` is an object with `code` and `message` fields. See Error codes.  
idempotency_key| String| Echoed from the request. Correlate the response with the originating charge using this value.  
patient_id| String| Echoed from the request: the [Patient](/sdk/data-patient/#patient) that was charged.  
payment_card_id| String| Echoed from the request: the stored card that was charged, a [PaymentCard](/sdk/data-payment-card/) id under the built-in processor.  
claim_id| String or null| Echoed from the request: the [Claim](/sdk/data-claim/) the payment was posted against, or `null` when none was supplied.  
amount| String| Echoed from the request: the dollar amount that was submitted.  
###  Error codes 
On failure, `error.code` names the condition that stopped the charge.
`error.code`| When it occurs  
---|---  
`patient_not_found`| The `patient_id` did not match a patient.  
`card_not_found`| The stored card was not found. For the built-in Stripe processor, this also covers a card that exists but is not owned by the patient; a custom processor may raise a different code for that case — check the processor's own documentation.  
`claim_not_found`| The `claim_id` did not match a claim owned by the patient.  
`no_outstanding_balance`| A charge with no `claim_id` was attempted, but the patient has no outstanding balance. The balance is checked before the card is charged.  
`amount_exceeds_balance`| A charge with no `claim_id` exceeds the patient's outstanding balance. The amount is validated against the balance before the card is charged.  
`nothing_to_charge`| A per-claim charge with `copay` set to `false` was attempted, but the claim has no chargeable, non-copay balance. Set `copay` to `true` to record a copay or prepayment instead.  
`charge_failed`| An unexpected failure occurred while processing the charge. Retry using the same `idempotency_key`; the retry will not double-charge the patient.  
The payment processor's own decline codes also pass through in `error.code` — for example, `card_declined` from Stripe — and can arrive at charge time. Handle an unrecognized code gracefully rather than matching against a fixed set, since the processor can surface codes this list does not name.

---

# Claim Effects

Source: https://docs.canvasmedical.com/sdk/effect-claims/

The Canvas SDK provides effects to facilitate managing claims. The `ClaimEffect` class provides a unified interface for:
  - adding labels to claims
  - removing labels from claims
  - moving claim to a queue
  - adding comments to claims
  - posting payments to claims
  - upserting metadata on claims
  - adding banner alerts to claims
  - removing banner alerts from claims
  - updating provider information on claims
  - updating the supervising provider on claims
  - setting the incident-to flag on claims
Additionally, the SDK provides a separate effect to update claim line items.
The following standalone effect classes are deprecated and will be removed in a future release. Please use the `ClaimEffect` class instead.
Deprecated Class| Old Import Path| New Equivalent  
---|---|---  
`AddClaimLabel`| `canvas_sdk.effects.claim_label`| `ClaimEffect.add_labels()`  
`RemoveClaimLabel`| `canvas_sdk.effects.claim_label`| `ClaimEffect.remove_labels()`  
`MoveClaimToQueue`| `canvas_sdk.effects.claim_queue`| `ClaimEffect.move_to_queue()`  
`AddClaimComment`| `canvas_sdk.effects.claim_comment`| `ClaimEffect.add_comment()`  
`PostClaimPayment`| `canvas_sdk.effects.payment`| `ClaimEffect.post_payment()`  
##  Claim Effect 
The `ClaimEffect` class facilitates operations on existing claims.
`from canvas_sdk.effects.claim import ClaimEffect`
Build a `ClaimEffect` with the claim's id, then return one of the methods below from your handler. Each method takes its own parameters and returns an `Effect`.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`claim_id`| `UUID` or `str`| Identifier for the claim| Yes  
###  Add Labels 
`add_labels(labels: list[str | Label]) → Effect`
Adds one or more labels to a claim, and optionally creates new labels before assigning them to the claim.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`labels`| `list[str or Label]`| List of label names and Label dataclasses* to apply to the claim| Yes  
*Labels can be passed in by name or as a Label dataclass. If the label with the provided name or values does not exist in your Canvas instance, it will be created and then applied to the specified claim. However, if a label already exists with the provided name or properties, it will add this existing label to the claim.
####  Label 
The `Label` dataclass represents a label with specific properties, including color and name.
Attribute| Type| Description| Required  
---|---|---|---  
`color`| [ColorEnum](/sdk/data-enumeration-types/#colorenum)| The color of the label in the UI| Yes  
`name`| `str`| The display name of the label| Yes  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists.
  - Validates that `labels` are provided and non-empty.
####  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect, Label
    from canvas_sdk.v1.data import Note
    from canvas_sdk.v1.data.common import ColorEnum
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self) -> list[Effect]:
            """Creates and adds a new label the claim when charges are pushed.
            Adds the existing Urgent label when the note is locked."""
            note = Note.objects.get(id=self.event.context["note_id"])
            claim = note.get_claim()
            state = self.event.context["state"]
            if state == "PSH":
                claim_effect = ClaimEffect(claim_id=claim.id)
                return [claim_effect.add_labels([Label(color=ColorEnum.PINK, name="pushed not locked")])]
            elif state == "LKD":
                claim_effect = ClaimEffect(claim_id=claim.id)
                return [claim_effect.add_labels(["Urgent"])]
            return []
    ```
###  Remove Labels 
`remove_labels(labels: list[str]) → Effect`
Removes existing labels from a claim.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`labels`| `list[str]`| List of label names to remove from the claim| Yes  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists
  - Validates `labels` is provided and non-empty
####  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect
    from canvas_sdk.v1.data import Note
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self) -> list[Effect]:
            """When note is locked, remove the 'pushed not locked' label from the claim."""
            note = Note.objects.get(id=self.event.context["note_id"])
            claim = note.get_claim()
            state = self.event.context["state"]
            if state == "LKD":
                claim_effect = ClaimEffect(claim_id=claim.id)
                return [claim_effect.remove_labels(["pushed not locked"])]
            return []
    ```
###  Move to Queue 
`move_to_queue(queue: str) → Effect`
Moves a claim to a specific queue.
Combined with the [claim data module](/sdk/data-claim/) and the label effects above, this effect lets a plugin control which claims land in the coding queue. For example:
  - When a visit does not meet your billable criteria, move its claim out of the coding queue so no one has to clean it up by hand.
  - Add labels to categorize claims for downstream workflows.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`queue`| `str`| The name of the queue to move the claim to, which must be a [valid name](/sdk/data-claim/#claimqueues)| Yes  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists
  - Validates `queue` is provided and the [queue with that name exists](/sdk/data-claim/#claimqueues)
####  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect
    from canvas_sdk.v1.data import Note
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self) -> list[Effect]:
            if self.event.context["state"] == "ULK":
                note = Note.objects.get(id=self.event.context["note_id"])
                claim = note.get_claim()
                claim_effect = ClaimEffect(claim_id=str(claim.id))
                return [claim_effect.move_to_queue("NeedsClinicianReview")]
            return []
    ```
###  Add Comment 
`add_comment(comment: str) → Effect`
Creates a new comment on a claim.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`comment`| `str`| The comment text to add| Yes  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists
####  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect
    from canvas_sdk.v1.data import Patient, Claim
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.COVERAGE_CREATED)
        def compute(self) -> list[Effect]:
            pt = Patient.objects.get(id=self.event.context["patient"]["id"])
            # patient's claims that have not been submitted yet
            pt_claims = Claim.objects.filter(
                note__patient=pt, current_queue__queue_sort_ordering__in=[1, 2, 3, 4]
            )
            return [
                ClaimEffect(claim_id=claim.id).add_comment(
                    "Patient has a new coverage, please confirm if this claim's coverage info should be updated."
                )
                for claim in pt_claims
            ]
    ```
###  Post Payment 
`post_payment(claim_coverage_id, line_item_transactions, method, ...) → Effect`
Posts a payment to a claim, specifying payment details and line item transactions. This method supports payments from insurance or patient and allows you to specify payments, adjustments, transfers, and write-offs on individual claim line items.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`claim_coverage_id`| `UUID`, `str`, or `'patient'`| Identifier for the coverage or the string `'patient'` for patient payments.| Yes  
`line_item_transactions`| `list[LineItemTransaction]`| List of LineItemTransactions for claim line items.| Yes  
`method`| `PaymentMethod`| The PaymentMethod used (e.g., `cash`, `check`, `card`, `other`).| Yes  
`move_to_queue_name`| `str`| Name of the queue to move the claim to after payment.| No  
`claim_description`| `str`| Description for the claim allocation.| No  
`check_date`| `date`| Date of the check (required if method is `check`).| No  
`check_number`| `str`| Check number (required if method is `check`).| No  
`deposit_date`| `date`| Date the payment was deposited.| No  
`payment_description`| `str`| Description of the payment.| No  
####  Validations and Implementation Details 
  - `check_number` and `check_date` are required if payment method is `check`
  - `claim_id` must correspond to a valid existing claim. For insurance payments, there are a few ways to help you identify the correct claim using the [Claim](/sdk/data-claim/#claim), [ClaimSubmission](/sdk/data-claim/#claimsubmission), [ClaimCoverage](/sdk/data-claim/#claimcoverage) data models:
    - `Claim.account_number` is the identifier that Canvas sends to the clearinghouse as a unique Canvas identifier for the claim.
    - `ClaimSubmission.clearinghouse_claim_id` is the identifier that the clearinghouse sends back to Canvas after they have accepted the claim, and is used for the clearinghouse's internal tracking of the claim.
    - `ClaimCoverage.payer_icn` is the identifier that the insurance company uses for their internal tracking of the claim, and is usually provided to Canvas via the clearinghouse.
  - `claim_coverage_id` must be either the string `"patient"` or correspond to a valid and **active** [ClaimCoverage](/sdk/data-claim/#claimcoverage) for the Claim.
    - A helpful way to identify the correct claim coverage is to use the method `get_coverage_by_payer_id(payer_id: str, subscriber_number: str | None = None)` on the [Claim](/sdk/data-claim/#claim) data model, where `payer_id` is the standard id for the insurance company. You can optionally provide `subscriber_number` if it's possible that the patient has multiple coverages from the same payer and you want to identify the correct coverage.
  - `move_to_queue_name` must be a valid label from [ClaimQueue](/sdk/data-claim/#claimqueues), but is not required. If provided, the claim will move to this queue after payment is applied.
  - The payment and its line item transactions are recorded together. If any part of the posting fails, none of it is saved. After the posting is saved, Canvas sends one [CLAIM_BALANCE_CHANGED](/sdk/events/#claims) event for the claim with its final balances.
####  LineItemTransaction 
Attribute| Type| Description| Required  
---|---|---|---  
`claim_line_item_id`| `UUID` or `str`| Identifier for the claim line item.| Yes  
`charged`| `Decimal`| Charged amount for the line item.| No  
`allowed`| `Decimal`| Allowed amount for the line item.| No  
`payment`| `Decimal`| Payment amount for the line item.| No  
`adjustment`| `Decimal`| Adjustment amount for the line item.| No  
`adjustment_code`| `str`| Code describing the adjustment.| No  
`transfer_remaining_balance_to`| `UUID`, `str`, or `'patient'`| Transfer remaining balance to another payer or patient.| No  
`write_off`| `bool`| Whether to write off the remaining balance.| No  
#####  LineItemTransaction Validations 
  - `claim_line_item_id` must be a valid and **active** line item for the claim. It is recommended to search for it using `.active()` and by `proc_code`, e.g. `claim.line_items.active().filter(proc_code="99215").first()`
  - There can be many LineItemTransactions for the same `claim_line_item_id`, but the first LineItemTransaction for a claim line item must specify either a payment or an adjustment (or allowed amount); subsequent transactions require an adjustment.
  - If an `adjustment` is specified, an `adjustment_code` must also be provided.
  - If the adjustment code is for a transfer (code starts with "Transfer"), a valid `transfer_remaining_balance_to` must be provided, and it cannot be the same payer as the `claim_coverage_id` payer.
  - `transfer_remaining_balance_to` can only be made to the patient (using the string `"patient"`) or to an **active** `claim_coverage_id` for the claim.
  - Adjustments cannot simultaneously write off and transfer the same amount; only one of `write_off` or `transfer_remaining_balance_to` should be set on LineItemTransactions where `adjustment` is present.
  - Adjustments and transfers are not allowed for COPAY charges, i.e. claim line items where the proc_code = `COPAY`. Only payments are allowed for those line items.
  - `payment` on COPAY line items must have a `claim_coverage_id` equal to `"patient"`.
  - `allowed` should be empty or $0 if `claim_coverage_id` is equal to `"patient"`.
####  PaymentMethod Enumeration Type 
Enum| Value  
---|---  
`CASH`| cash  
`CHECK`| check  
`CARD`| card  
`OTHER`| other  
####  Example Usage 
The most common use case for this method will be with the [SimpleAPI](/sdk/handlers-simple-api-http/) handler.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.v1.data import ClaimLineItem, Claim
    from decimal import Decimal
    from canvas_sdk.effects.claim import (
        ClaimEffect,
        PaymentMethod,
        LineItemTransaction,
    )
    from datetime import date
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/post-claim-payment"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            # replace with desired authentication logic
            return True
        def get_claim_line_item(self, claim: Claim, proc_code: str) -> ClaimLineItem | None:
            return claim.line_items.active().filter(proc_code=proc_code).first()
        def create_line_item_transactions(
            self, charge: dict, claim: Claim, next_coverage_id: str
        ) -> list[LineItemTransaction]:
            transactions = []
            if not (line_item := self.get_claim_line_item(claim, charge.get("proc_code"))):
                return transactions
            charged = Decimal(charge["charge"])
            payment = Decimal(charge["paid"])
            allowed = Decimal(charge["allowed"])
            adjustments = charge.get("adjustment", [])
            first_adjustment = adjustments[0]
            payment = LineItemTransaction(
                claim_line_item_id=line_item.id,
                charged=charged,
                payment=payment,
                allowed=allowed,
                adjustment=Decimal(first_adjustment["amount"]),
                adjustment_code=f"{first_adjustment['group']}-{first_adjustment['code']}",
                # replace with whatever logic needed for resolving remaining balance
                transfer_remaining_balance_to="patient"
                if first_adjustment["group"] == "PR"
                else next_coverage_id,
            )
            transactions.append(payment)
            additional_adjustments = adjustments[1:]
            for adj in additional_adjustments:
                transaction = LineItemTransaction(
                    claim_line_item_id=line_item.id,
                    adjustment=Decimal(adj["amount"]),
                    adjustment_code=f"{adj['group']}-{adj['code']}",
                    # replace with whatever logic needed for resolving remaining balance
                    transfer_remaining_balance_to="patient"
                    if adj["group"] == "PR"
                    else next_coverage_id,
                )
                transactions.append(transaction)
            return transactions
        def get_claim(
            self, account_number: str, clearinghouse_claim_id: str
        ) -> Claim | None:
            return (
                Claim.objects.filter(account_number=account_number).first()
                or Claim.objects.filter(
                    submissions__clearinghouse_claim_id=clearinghouse_claim_id,
                ).first()
            )
        def post_payment(
            self,
            claim_payment_info: dict,
            check_number: str,
            check_date: str,
            payer_id: str,
        ) -> Effect | None:
            account_number = claim_payment_info.get("pcn")
            clearinghouse_claim_id = claim_payment_info.get("payer_icn")
            if not (claim := self.get_claim(account_number, clearinghouse_claim_id)):
                return None
            insurance_number = claim_payment_info.get("ins_number")
            if not (coverage := claim.get_coverage_by_payer_id(payer_id, insurance_number)):
                return None
            next_coverage_id = (
                claim.coverages.active().exclude(payer_id=payer_id).first().id
            )
            line_item_transactions = []
            for c in claim_payment_info.get("charge", []):
                line_item_transactions.extend(
                    self.create_line_item_transactions(c, claim, next_coverage_id)
                )
            claim_effect = ClaimEffect(claim_id=claim.id)
            return claim_effect.post_payment(
                claim_coverage_id=coverage.id,
                line_item_transactions=line_item_transactions,
                method=PaymentMethod.CHECK,
                check_date=date.fromisoformat(check_date),
                check_number=check_number,
                deposit_date=date.fromisoformat(check_date),
                payment_description="Aetna 835 payment",
                claim_description="Payment applied via 835",
            )
        def post(self) -> list[Response | Effect]:
            payment_info = self.request.json()
            check_number = payment_info.get("check_number")
            check_date = payment_info.get("paid_date")
            payer_id = payment_info.get("payerid")
            payments = [
                p
                for claim in payment_info.get("claim", [])
                if (p := self.post_payment(claim, check_number, check_date, payer_id))
            ]
            return payments + [JSONResponse({"message": "ok"})]
    ```
With the above plugin installed, an example call to the endpoint would look like this:
    ```bash
    curl -X POST "http://localhost:8000/plugin-io/api/pmt/routes/post-claim-payment" \
      -H "Content-Type: application/json" \
      -H "Authorization: <api-key>" \
      -d '{
        "paid_date": "2025-11-06",
        "eraid": "23853671",
        "check_number": "397547083-1662491258",
        "paid_amount": "346.00",
        "payerid": "60054",
        "claim": [
            {
                "pcn": "124974-1",
                "payer_icn": "TST397547083",
                "total_charge": "48",
                "from_dos": "20250827",
                "pat_name_f": "ETHYL",
                "ins_name_l": "BATES",
                "total_paid": "0",
                "thru_dos": null,
                "pat_name_l": "BATES",
                "ins_number": "412098745",
                "ins_name_f": "NORMAN",
                "charge": [
                    {
                        "chgid": "221043771",
                        "from_dos": "20220827",
                        "adjustment": [{"amount": "48", "group": "OA", "code": "109"}],
                        "paid": "0",
                        "allowed": "0",
                        "proc_code": "99212",
                        "charge": "48",
                        "thru_dos": null,
                        "units": "1"
                    }
                ]
            },
            {
                "pcn": "21830-1",
                "payer_icn": "TST397547094",
                "total_charge": "75",
                "from_dos": "20220827",
                "pat_name_f": "MARYLOU",
                "ins_name_l": "DENNIS",
                "total_paid": "45",
                "thru_dos": null,
                "pat_name_l": "DENNIS",
                "ins_number": "223444467",
                "ins_name_f": "ROBERT",
                "charge": [
                    {
                        "chgid": "221043716",
                        "from_dos": "20220827",
                        "adjustment": [
                            {"amount": "15", "group": "CO", "code": "45"},
                            {"amount": "10", "group": "PR", "code": "2"},
                            {"amount": "5", "group": "PR", "code": "3"}
                        ],
                        "paid": "45",
                        "allowed": "60",
                        "proc_code": "99213",
                        "charge": "75",
                        "thru_dos": null,
                        "units": "1"
                    }
                ]
            }
        ]
    }'
    ```
###  Upsert Metadata 
`upsert_metadata(key: str, value: str) → Effect`
Upserts a key-value metadata record on a claim. If a metadata record with the given key already exists for the claim, its value will be updated. Otherwise, a new metadata record will be created.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`key`| `str`| The key of the metadata| Yes  
`value`| `str`| The value of the metadata| Yes  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists
  - The claim-key pair is unique; upserting with an existing key will update the value rather than creating a duplicate
  - If a metadata record already exists with the same claim, key, and value, no update is performed
####  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect
    from canvas_sdk.v1.data import Note
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self) -> list[Effect]:
            """When a note is locked, store the lock timestamp as metadata on the claim."""
            note = Note.objects.get(id=self.event.context["note_id"])
            claim = note.get_claim()
            state = self.event.context["state"]
            if state == "LKD":
                claim_effect = ClaimEffect(claim_id=claim.id)
                return [claim_effect.upsert_metadata(key="locked_at", value=str(note.modified))]
            return []
    ```
###  Add Banner 
`add_banner(key: str, narrative: str, intent: BannerAlertIntent, href: str | None = None) → Effect`
Adds a banner alert to a claim. Banner alerts are displayed in the UI to surface important information about a claim.
> **Warning:** A claim banner alert belongs to the plugin that added it. Disabling the plugin hides its banners, and [uninstalling](/sdk/canvas_cli/#canvas-uninstall) it deletes them.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`key`| `str`| A unique key identifying the banner alert| Yes  
`narrative`| `str`| The banner text to display (max 90 characters)| Yes  
`intent`| BannerAlertIntent| The visual intent/severity of the banner| Yes  
`href`| `str`| An optional link URL for the banner| No  
####  BannerAlertIntent Enumeration Type 
Enum| Value  
---|---  
`INFO`| info  
`WARNING`| warning  
`ALERT`| alert  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists
  - The `narrative` field has a maximum length of 90 characters
####  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect, BannerAlertIntent
    from canvas_sdk.v1.data import Note
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self) -> list[Effect]:
            """When a note is unlocked, add a warning banner to the claim."""
            note = Note.objects.get(id=self.event.context["note_id"])
            claim = note.get_claim()
            state = self.event.context["state"]
            if state == "ULK":
                claim_effect = ClaimEffect(claim_id=claim.id)
                return [
                    claim_effect.add_banner(
                        key="review-needed",
                        narrative="This claim needs review before resubmission.",
                        intent=BannerAlertIntent.WARNING,
                    )
                ]
            return []
    ```
###  Remove Banner 
`remove_banner(key: str) → Effect`
Removes a banner alert from a claim by its key.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`key`| `str`| The unique key of the banner alert to remove| Yes  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists
####  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect
    from canvas_sdk.v1.data import Note
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self) -> list[Effect]:
            """When a note is locked, remove the review-needed banner from the claim."""
            note = Note.objects.get(id=self.event.context["note_id"])
            claim = note.get_claim()
            state = self.event.context["state"]
            if state == "LKD":
                claim_effect = ClaimEffect(claim_id=claim.id)
                return [claim_effect.remove_banner(key="review-needed")]
            return []
    ```
###  Update Provider 
`update_provider(billing_provider=None, provider=None, referring_provider=None, ordering_provider=None, facility=None) → Effect`
Updates provider information on a claim, including billing provider, rendering/attending provider, referring provider, ordering provider, and facility details. All parameters are optional — only the fields you provide will be updated.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`billing_provider`| ClaimBillingProvider or `None`| Billing provider information| No  
`provider`| ClaimProvider or `None`| Rendering or attending provider information| No  
`referring_provider`| ClaimReferringProvider or `None`| Referring provider information| No  
`ordering_provider`| ClaimOrderingProvider or `None`| Ordering provider information| No  
`facility`| ClaimFacility or `None`| Facility information| No  
####  ClaimBillingProvider 
Attribute| Type| Description  
---|---|---  
`name`| `str` or `None`| Provider name (max 255 chars)  
`phone`| `str` or `None`| Phone number (max 15 chars)  
`addr1`| `str` or `None`| Address line 1 (max 255 chars)  
`addr2`| `str` or `None`| Address line 2 (max 255 chars)  
`city`| `str` or `None`| City (max 255 chars)  
`state`| `str` or `None`| State code (max 2 chars)  
`zip`| `str` or `None`| ZIP code (max 255 chars)  
`npi`| `str` or `None`| NPI number (max 10 chars)  
`tax_id`| `str` or `None`| Tax ID (max 100 chars)  
`tax_id_type`| `str` or `None`| Tax ID type (max 1 char)  
`taxonomy`| `str` or `None`| Taxonomy code (max 100 chars)  
`clia_number`| `str` or `None`| CLIA number (max 100 chars)  
####  ClaimProvider 
Represents the rendering or attending provider.
Attribute| Type| Description  
---|---|---  
`first_name`| `str` or `None`| First name (max 255 chars)  
`last_name`| `str` or `None`| Last name (max 255 chars)  
`middle_name`| `str` or `None`| Middle name (max 255 chars)  
`npi`| `str` or `None`| NPI number (max 10 chars)  
`tax_id`| `str` or `None`| Tax ID (max 100 chars)  
`tax_id_type`| `str` or `None`| Tax ID type (max 1 char)  
`taxonomy`| `str` or `None`| Taxonomy code (max 100 chars)  
`ptan_identifier`| `str` or `None`| PTAN identifier (max 50 chars)  
`addr1`| `str` or `None`| Address line 1 (max 255 chars)  
`addr2`| `str` or `None`| Address line 2 (max 255 chars)  
`city`| `str` or `None`| City (max 255 chars)  
`state`| `str` or `None`| State code (max 2 chars)  
`zip`| `str` or `None`| ZIP code (max 255 chars)  
####  ClaimReferringProvider 
Attribute| Type| Description  
---|---|---  
`first_name`| `str` or `None`| First name (max 255 chars)  
`last_name`| `str` or `None`| Last name (max 255 chars)  
`middle_name`| `str` or `None`| Middle name (max 255 chars)  
`npi`| `str` or `None`| NPI number (max 10 chars)  
`ptan_identifier`| `str` or `None`| PTAN identifier (max 50 chars)  
####  ClaimOrderingProvider 
Attribute| Type| Description  
---|---|---  
`first_name`| `str` or `None`| First name (max 255 chars)  
`last_name`| `str` or `None`| Last name (max 255 chars)  
`middle_name`| `str` or `None`| Middle name (max 255 chars)  
`npi`| `str` or `None`| NPI number (max 10 chars)  
####  ClaimFacility 
Attribute| Type| Description  
---|---|---  
`name`| `str` or `None`| Facility name (max 255 chars)  
`npi`| `str` or `None`| NPI number (max 10 chars)  
`addr1`| `str` or `None`| Address line 1 (max 255 chars)  
`addr2`| `str` or `None`| Address line 2 (max 255 chars)  
`city`| `str` or `None`| City (max 255 chars)  
`state`| `str` or `None`| State code (max 2 chars)  
`zip`| `str` or `None`| ZIP code (max 255 chars)  
`hosp_from_date`| `date` or `None`| Hospitalization start date  
`hosp_to_date`| `date` or `None`| Hospitalization end date  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists
  - Validates that the claim has existing provider information (i.e., the claim's provider record is populated)
  - Only fields with non-`None` values are included in the update — any fields left as `None` are excluded
  - Date fields (`hosp_from_date`, `hosp_to_date`) are serialized to ISO format strings
####  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Claim, Note, PatientFacilityAddress
    from canvas_sdk.v1.data.common import AddressState
    from canvas_sdk.effects.claim.claim import ClaimEffect, ClaimBillingProvider, ClaimFacility
    class ClaimProviderHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.CLAIM_CREATED),
            EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED),
        ]
        def get_claim(self) -> Claim | None:
            if self.event.type == EventType.CLAIM_CREATED:
                return Claim.objects.get(id=self.event.target.id)
            if self.event.context["state"] not in ["LKD", "PSH", "DSC"]:
                # claim provider details can change when notes are locked, pushed, or discharged
                return None
            return Note.objects.get(self.event.target.id).get_claim()
        def get_patient_facility(self, claim) -> PatientFacilityAddress | None:
            return PatientFacilityAddress.objects.filter(
                patient=claim.note.patient, state=AddressState.ACTIVE
            ).first()
        def compute(self) -> list[Effect]:
            """When a claim is created, or note is locked/pushed/charged, update the claim's provider information."""
            if not (claim := self.get_claim()):
                return []
            if not (facility := self.get_patient_facility(claim)):
                return []
            billing = ClaimBillingProvider(
                name=facility.facility.name,
                phone=facility.facility.phone_number,
                addr1=facility.line1,
                addr2=facility.line2,
                city=facility.city,
                state=facility.state_code,
                zip=facility.postal_code,
                npi=facility.facility.npi_number,
            )
            facility = ClaimFacility(
                name=facility.facility.name,
                npi=facility.facility.npi_number,
                addr1=facility.line1,
                addr2=facility.line2,
                city=facility.city,
                state=facility.state_code,
                zip=facility.postal_code,
            )
            return [
                ClaimEffect(claim_id=claim.id).update_provider(
                    billing_provider=billing, facility=facility
                )
            ]
    ```
###  Update Supervising Provider 
`update_supervising_provider(supervising_provider=None, *, staff_id=None) → Effect`
Sets the supervising provider snapshot on a claim. This snapshot is captured for billing purposes (837P loop 2310D and the printed CMS-1500 form) and remains frozen after submission.
Provide exactly one of:
  - A `staff_id` to populate the snapshot from an existing Staff record (name, NPI, taxonomy, tax ID). The snapshot remains linked to the Staff record.
  - A `ClaimSupervisingProvider` dataclass to specify the snapshot fields directly. This clears any Staff association.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`supervising_provider`| ClaimSupervisingProvider or `None`| Free-text provider snapshot| Yes (if `staff_id` not given)  
`staff_id`| `str` or `None`| Staff identifier to populate from| Yes (if `supervising_provider` not given)  
####  ClaimSupervisingProvider 
The `ClaimSupervisingProvider` dataclass represents a supervising provider's identifying information for billing purposes.
Attribute| Type| Description  
---|---|---  
`first_name`| `str` or `None`| First name (max 255 chars)  
`last_name`| `str` or `None`| Last name (max 255 chars)  
`middle_name`| `str` or `None`| Middle name (max 255 chars)  
`npi`| `str` or `None`| NPI number (max 10 chars)  
`taxonomy`| `str` or `None`| Taxonomy code (max 100 chars)  
`tax_id`| `str` or `None`| Tax ID (max 100 chars)  
`tax_id_type`| `str` or `None`| Tax ID type (max 1 char)  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists
  - Validates that exactly one of `staff_id` or `supervising_provider` is provided
  - If `staff_id` is provided, validates that the Staff record exists
####  Example Usage 
Using a Staff record:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect
    from canvas_sdk.v1.data import Note
    class SupervisingProviderHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self) -> list[Effect]:
            """When a note is locked, set the supervising provider from the note's supervising provider."""
            note = Note.objects.get(id=self.event.context["note_id"])
            claim = note.get_claim()
            state = self.event.context["state"]
            if state == "LKD" and note.supervising_provider:
                claim_effect = ClaimEffect(claim_id=claim.id)
                return [claim_effect.update_supervising_provider(staff_id=str(note.supervising_provider.id))]
            return []
    ```
Using free-text provider information:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect, ClaimSupervisingProvider
    from canvas_sdk.v1.data import Note
    class SupervisingProviderHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self) -> list[Effect]:
            """When a note is locked, set a custom supervising provider on the claim."""
            note = Note.objects.get(id=self.event.context["note_id"])
            claim = note.get_claim()
            state = self.event.context["state"]
            if state == "LKD":
                claim_effect = ClaimEffect(claim_id=claim.id)
                return [
                    claim_effect.update_supervising_provider(
                        ClaimSupervisingProvider(
                            first_name="Jane",
                            last_name="Doe",
                            npi="1234567890",
                            taxonomy="207Q00000X",
                        )
                    )
                ]
            return []
    ```
###  Set Incident To 
`set_incident_to(value: bool) → Effect`
Sets the `incident_to` billing flag for Medicare incident-to billing. When set to `True`, the claim's rendering provider fields (name, NPI, taxonomy) are automatically replaced with the supervising provider's details.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`value`| `bool`| Whether the claim is billed incident-to the supervising physician| Yes  
####  How Incident-To Billing Works 
When a claim is marked as incident-to:
  1. **Automatic rendering provider swap** : The rendering provider fields (first name, last name, middle name, NPI, and taxonomy) are replaced with the supervising provider's values. This swap happens immediately when `incident_to` is set to `True`, not at claim submission.
  2. **Billing provider unchanged** : The billing provider information (NM1 _85 on the 837P) remains unchanged. Only the rendering provider (NM1_ 82 / Box 24J) is affected.
  3. **Frozen after submission** : Once a claim has been submitted to the clearinghouse, the rendering provider swap no longer occurs even if incident-to settings change.
  4. **Re-sync on supervising provider change** : If the supervising provider is updated on an incident-to claim, the rendering provider fields are automatically re-synced to match the new supervising provider.
####  Printed CMS-1500 Form 
The supervising provider appears on the printed CMS-1500 (HCFA) form differently depending on whether the claim is marked incident-to:
Scenario| Box 24J (Rendering NPI)| Box 17 (Referring/Supervising Provider)  
---|---|---  
**Incident-to claim**|  Supervising provider's NPI (via the automatic rendering swap)| Not populated for supervising—the provider already appears in Box 24J  
**Non-incident-to claim with supervising provider**|  Original rendering provider's NPI| Supervising provider with **DQ** qualifier (if no referring or ordering provider exists)  
For non-incident-to claims with a supervising provider who has a valid NPI and no referring or ordering provider, the printed form populates Box 17 with the supervising provider's name, Box 17a with the "DQ" (supervising physician) qualifier, and Box 17b with the supervising provider's NPI.
Box 17 follows a priority order: referring provider (DN) takes precedence over ordering provider (DK), which takes precedence over supervising provider (DQ). The supervising provider only appears in Box 17 when no referring or ordering provider is present.
####  Claim Errors 
The following errors prevent claim submission when incident-to is enabled:
Error| Description| Solution  
---|---|---  
Missing supervising provider| The claim is marked incident-to but has no supervising provider with an NPI.| Add a supervising provider with a valid NPI, or disable incident-to.  
Supervising provider same as rendering| The supervising provider is the same as the note's original rendering provider.| Set the supervising provider to a different physician, or disable incident-to.  
####  Claim Warnings 
The following warnings are displayed for incident-to claims but do not prevent submission:
Warning| Description| Guidance  
---|---|---  
Non-office place of service| The place of service is not office (11). Incident-to billing is generally not valid in facility settings per 42 CFR 410.26.| Confirm the place of service is correct, or disable incident-to if it does not apply.  
Non-Medicare payer| The payer is not Medicare. Incident-to rules are a Medicare policy; coverage varies by commercial payer.| Confirm the payer accepts incident-to billing, or disable incident-to if it does not apply.  
####  Implementation Details 
  - Validates `claim_id` is provided and that the associated claim exists
  - The rendering provider swap requires a valid supervising provider with an NPI
  - The swap is skipped if the supervising provider's NPI is missing or invalid
####  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects.claim import ClaimEffect
    from canvas_sdk.v1.data import Note
    class IncidentToHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.CLAIM_SUPERVISING_PROVIDER_CHANGED)
        def compute(self) -> list[Effect]:
            """When a supervising provider is set on a claim, enable incident-to billing."""
            claim_id = self.event.target.id
            claim_effect = ClaimEffect(claim_id=claim_id)
            return [claim_effect.set_incident_to(True)]
    ```
* * *
##  UpdateClaimLineItem 
The `UpdateClaimLineItem` effect allows you to update the `charge` field and `linked_diagnosis_codes` on a specified claim line item.
Build an `UpdateClaimLineItem` with the attributes below, then return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Updates the claim line item.
  - Validates `claim_line_item_id` is provided and that the associated claim line item exists
  - If `linked_diagnosis_codes` is provided, validates that all [ClaimLineItemDiagnosisCode](/sdk/data-claim/#claimlineitemdiagnosiscode) IDs correspond to existing diagnosis codes on the claim line item
  - The `linked_diagnosis_codes` list represents the complete set of diagnosis codes that will be linked to the claim line item when the effect is applied. Any diagnosis codes not included in this list will be unlinked. If you wish to add a new code to the existing linked codes, you must first retrieve the current list and include all codes you want to remain linked: `list(claim_line_item.diagnosis_codes.filter(linked=True).values_list("id", flat=True)) + [new_code_id]`
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`claim_line_item_id`| `UUID` or `str`| Identifier for the claim line item| Yes  
`charge`| `float`| The charge amount to update on the claim line item| No  
`linked_diagnosis_codes`| `list[UUID or str]`| List of [ClaimLineItemDiagnosisCode](/sdk/data-claim/#claimlineitemdiagnosiscode) IDs to link to the claim line item| No  
###  Example Usage 
Updating charge amount.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Note, ClaimLineItem
    from canvas_sdk.effects.claim_line_item import UpdateClaimLineItem
    class MyHandler(BaseHandler):
        """When a note is unlocked, update the associated claim's line items to have a charge of $0.00.
        When a note is locked, update the associated claim's line items to have a charge of $500.00."""
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def get_line_items(self) -> ClaimLineItem:
            note = Note.objects.get(id=self.event.context["note_id"])
            claim = note.get_claim()
            return claim.get_active_claim_line_items()
        def update_charge(self, id: str, charge: float) -> Effect:
            return UpdateClaimLineItem(claim_line_item_id=id, charge=charge).apply()
        def update_all_items(self, charge: float) -> list[Effect]:
            return [self.update_charge(line_item.id, charge) for line_item in self.get_line_items()]
        def compute(self) -> list[Effect]:
            if self.event.context["state"] == "ULK":
                return self.update_all_items(0.00)
            if self.event.context["state"] == "LKD":
                return self.update_all_items(500.00)
            return []
    ```
Linking and un-linking diagnosis codes.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Note, ClaimLineItem
    from canvas_sdk.effects.claim_line_item import UpdateClaimLineItem
    class MyHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED),
        ]
        def compute(self) -> list[Effect]:
            effects = []
            note = Note.objects.get(id=self.event.context["note_id"])
            if not (claim := note.get_claim()):
                return effects
            state = self.event.context["state"]
            if state == "PSH":
                # only link proc codes starting with "99" to diag codes starting with "I"
                items = claim.line_items.filter(proc_code__startswith="99")
                return self.generate_effects(items, self.get_diags_that_start_with_I)
            if state == "LKD":
                # link all proc codes to all diag codes
                items = claim.line_items.all()
                return self.generate_effects(items, self.get_all_diags)
            if state == "ULK":
                # unlink proc codes starting with "99" from diag codes starting with "I"
                items = claim.line_items.filter(proc_code__startswith="99")
                return self.generate_effects(items, self.get_diags_that_dont_start_with_I)
            if state == "DLT":
                # unlink all proc codes from all diag codes
                items = claim.line_items.all()
                return self.generate_effects(items, self.get_no_diags)
            return effects
        def get_diags_that_start_with_I(self, item: ClaimLineItem) -> list[str]:
            return list(
                item.diagnosis_codes.filter(code__startswith="I").values_list(
                    "id", flat=True
                )
            )
        def get_diags_that_dont_start_with_I(self, item: ClaimLineItem) -> list[str]:
            return list(
                item.diagnosis_codes.exclude(code__startswith="I").values_list(
                    "id", flat=True
                )
            )
        def get_all_diags(self, item: ClaimLineItem) -> list[str]:
            return list(item.diagnosis_codes.values_list("id", flat=True))
        def get_no_diags(self, item: ClaimLineItem) -> list[str]:
            return []
        def generate_effects(self, items, get_diag_ids) -> list[Effect]:
            return [
                UpdateClaimLineItem(
                    claim_line_item_id=item.id, linked_diagnosis_codes=get_diag_ids(item)
                ).apply()
                for item in items
            ]
    ```

---

# CommandMetadata Effect

Source: https://docs.canvasmedical.com/sdk/effect-command-metadata/

The `upsert_metadata` method on any command class provides a flexible key-value storage system for command-specific data within the Canvas system. This method enables the creation and updating of custom metadata entries associated with command records, allowing for extensible command information storage beyond standard command fields.
##  Overview 
Command metadata serves as a powerful extension mechanism for storing custom command-related information that doesn't fit within the standard command data model. Metadata is managed through the `upsert_metadata` method available on all command effect classes.
Metadata can be written two ways, and they store to the same place:
  - **From your plugin** , with the `upsert_metadata` method documented on this page.
  - **From the note** , with the [Command Metadata Create form effect](/sdk/command-metadata-create-form-effect/), which displays additional fields alongside a command in the chart and stores whatever a user enters as metadata against that command.
Either way, the entries are readable as [CommandMetadata](/sdk/data-command/#commandmetadata) in the data module.
##  Methods 
###  upsert_metadata(key: str, value: str) → Effect 
Creates or updates a metadata entry for the specified command.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`key`| `str`| Unique identifier for the metadata entry within the command context| Yes  
`value`| `str`| The metadata value to store| Yes  
####  Prerequisites 
The command effect must be initialized with a `command_uuid`. This can be either the UUID of an existing command or the UUID of a command being originated in the same effect list.
Attribute| Type| Description| Required  
---|---|---|---  
`command_uuid`| `str`| Id of the command record to associate metadata with| Yes  
####  Returns 
An `Effect` object configured for upserting command metadata.
####  Behavior 
  - If a metadata entry with the specified key already exists for the command, it will be updated with the new value
  - If no entry exists, a new metadata entry will be created
  - The operation is idempotent - repeated calls with the same key and value will not create duplicate entries
  - Raises `ValueError` if `command_uuid` is not set on the command effect
##  Implementation Details 
###  Validation 
The effect performs validation at two stages:
  1. **SDK Validation** : Ensures all required fields are provided before the effect is created
     - `command_uuid` must be set on the command effect
     - Both `key` and `value` must be provided
  2. **Server-Side Validation** : When the effect is processed, the server verifies that the referenced command exists
     - Returns a descriptive error if the command is not found after all effects in the list have been processed
##  Example Usage 
###  Basic Usage 
    ```python
    from canvas_sdk.commands import PlanCommand
    plan = PlanCommand(command_uuid="63hdik")
    effect = plan.upsert_metadata(key="my_plugin:priority", value="high")
    ```
###  Example: Chaining with originate() 
You can attach metadata to a command at the same time you originate it by returning both effects in the same list:
    ```python
    import uuid
    from canvas_sdk.commands import PlanCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class OriginateWithMetadata(BaseHandler):
        """Originates a plan command with metadata attached in a single operation."""
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART__SECTION__LOADED)
        def compute(self) -> list[Effect]:
            command_uuid = str(uuid.uuid4())
            plan = PlanCommand(
                note_uuid=self.context["note_id"],
                command_uuid=command_uuid,
                narrative="Follow up in 2 weeks",
            )
            return [
                plan.originate(),
                plan.upsert_metadata(key="my_plugin:source", value="auto_generated"),
            ]
    ```
###  Example: Tagging a command on commit 
    ```python
    from canvas_sdk.commands import PlanCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class TagPlanOnCommit(BaseHandler):
        """Tags a plan command with a workflow stage when it is committed."""
        RESPONDS_TO = EventType.Name(EventType.PLAN_COMMAND__POST_COMMIT)
        def compute(self) -> list[Effect]:
            plan = PlanCommand(command_uuid=self.event.target.id)
            return [plan.upsert_metadata(key="my_plugin:workflow_stage", value="committed")]
    ```
###  Responding to metadata events 
Once metadata is upserted, `COMMAND_METADATA_CREATED` and `COMMAND_METADATA_UPDATED` events are emitted and can be handled by plugins:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.command import CommandMetadata
    from logger import log
    class CommandMetadataListener(BaseHandler):
        """Reacts to command metadata changes."""
        RESPONDS_TO = [
            EventType.Name(EventType.COMMAND_METADATA_CREATED),
            EventType.Name(EventType.COMMAND_METADATA_UPDATED),
        ]
        def compute(self) -> list[Effect]:
            metadata = CommandMetadata.objects.get(id=self.event.target.id)
            log.info(f"Command {metadata.command.id}: {metadata.key}={metadata.value}")
            return []
    ```
##  Best Practices 
###  Key Naming Conventions 
  1. **Use Descriptive Names** : Choose keys that clearly indicate the purpose of the metadata
     - Good: `workflow_stage`, `external_id`, `review_status`
     - Avoid: `data1`, `temp`, `misc`
  2. **Namespace Your Keys** : Prefix keys with your plugin name to avoid collisions with other plugins
     - Example: `my_plugin:workflow_stage`, `my_plugin:external_id`
###  Value Storage 
**String Serialization** : All values are stored as strings. For complex data types, serialize to JSON:
    ```python
       import json
       from canvas_sdk.commands import AssessCommand
       cmd = AssessCommand(command_uuid="abc123")
       data = {"reviewer": "user-id", "approved_at": "2025-01-15T10:30:00Z"}
       cmd.upsert_metadata(key="my_plugin:review", value=json.dumps(data))
    ```
##  Notes 
  - Metadata entries are command-specific — the same key can have different values for different commands
  - There is no built-in versioning; updating a key overwrites the previous value
  - The system does not enforce any schema on metadata values — validation is the responsibility of the implementing code
  - The `key` field supports up to 256 characters
  - To collect metadata from a user in the chart rather than writing it from a plugin, see the [Command Metadata Create form effect](/sdk/command-metadata-create-form-effect/)

---

# Command Validation

Source: https://docs.canvasmedical.com/sdk/effect-command-validation/

The `CommandValidationErrorEffect` returns structured error messages that are displayed to users in the Canvas UI. It serves two purposes:
  - **Validate a command** as it is entered in the Canvas UI, surfacing problems before it can be committed (`__POST_VALIDATION` events).
  - **Block a deletion** by returning the effect from a command's `__PRE_DELETE` handler.
In both cases you build a `CommandValidationErrorEffect`, attach one or more error messages, and return it from your handler.
Validating a command is the supported way to require fields, or to run any custom validation such as checking a free-text date entered in a questionnaire, **before a command is committed**. It is different from validating a note before it is locked: pre-lock validation only stops the note from being locked, and the command underneath it, such as a questionnaire, is still committed. Command validation blocks the commit itself and shows the error to the user. The [`command-validation` example plugin](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/command-validation/command_validation) can be tailored to require every question on a questionnaire to be answered, or to check only specific questions or questionnaires.
Where these errors are enforced differs by event: `__POST_VALIDATION` errors block a commit **only in the Canvas UI** , while `__PRE_DELETE` errors block a deletion through **both** the Canvas UI and the SDK [commands module](/sdk/commands/). Each section below covers the specifics.
##  The effect 
###  CommandValidationErrorEffect 
Build a `CommandValidationErrorEffect`, add one or more errors, then return its `apply()` from your handler.
####  Methods 
#####  add_error(message: str | ValidationError) → CommandValidationErrorEffect 
Appends an error, given as a message or a `ValidationError`, and returns the effect, so calls can be chained.
#####  apply() → Effect 
Shows the errors to the user. See Validate a command and Block a deletion for what the errors block in each case.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`errors`| `list[``ValidationError``]`| List of validation errors to be displayed to the user.| No  
###  ValidationError 
Each `ValidationError` object represents a single validation error message:
Attribute| Type| Description| Required  
---|---|---|---  
`message`| `str`| The validation error message to display. Must not be empty.| Yes  
###  Building the errors 
Add errors incrementally with `add_error()`, which returns `self` so calls can be chained:
    ```python
    effect = CommandValidationErrorEffect()
    effect.add_error("Narrative is required").add_error("Please provide details about the plan")
    return [effect.apply()]
    ```
Or pass a list of `ValidationError` objects to the constructor:
    ```python
    from canvas_sdk.commands.validation import CommandValidationErrorEffect, ValidationError
    errors = [
        ValidationError("Narrative is required"),
        ValidationError("Narrative must be at least 10 characters long"),
    ]
    effect = CommandValidationErrorEffect(errors=errors)
    return [effect.apply()]
    ```
##  Validate a command 
Use `CommandValidationErrorEffect` with a command's `__POST_VALIDATION` event to check the command as it is entered and surface problems before it is committed. These events follow the pattern:
`{COMMAND_KEY}_COMMAND__POST_VALIDATION`
The following command types fire `__POST_VALIDATION` and can be validated with this effect:
  - `ADD_CONDITION_COMMAND__POST_VALIDATION`
  - `ADJUST_PRESCRIPTION_COMMAND__POST_VALIDATION`
  - `ALLERGY_COMMAND__POST_VALIDATION`
  - `APPROVE_REFILL_COMMAND__POST_VALIDATION`
  - `ASSESS_CODING_GAP_COMMAND__POST_VALIDATION`
  - `ASSESS_COMMAND__POST_VALIDATION`
  - `CANCEL_PRESCRIPTION_COMMAND__POST_VALIDATION`
  - `CHANGE_MEDICATION_COMMAND__POST_VALIDATION`
  - `CHART_SECTION_REVIEW_COMMAND__POST_VALIDATION`
  - `CLIPBOARD_COMMAND__POST_VALIDATION`
  - `CLOSE_GOAL_COMMAND__POST_VALIDATION`
  - `CREATE_CODING_GAP_COMMAND__POST_VALIDATION`
  - `DEFER_CODING_GAP_COMMAND__POST_VALIDATION`
  - `DENY_REFILL_COMMAND__POST_VALIDATION`
  - `DIAGNOSE_COMMAND__POST_VALIDATION`
  - `EDUCATIONAL_MATERIAL_COMMAND__POST_VALIDATION`
  - `FAMILY_HISTORY_COMMAND__POST_VALIDATION`
  - `FOLLOW_UP_COMMAND__POST_VALIDATION`
  - `GOAL_COMMAND__POST_VALIDATION`
  - `HISTORY_OF_PRESENT_ILLNESS_COMMAND__POST_VALIDATION`
  - `IMAGING_ORDER_COMMAND__POST_VALIDATION`
  - `IMMUNIZATION_STATEMENT_COMMAND__POST_VALIDATION`
  - `IMMUNIZE_COMMAND__POST_VALIDATION`
  - `INSTRUCT_COMMAND__POST_VALIDATION`
  - `LAB_ORDER_COMMAND__POST_VALIDATION`
  - `MEDICAL_HISTORY_COMMAND__POST_VALIDATION`
  - `MEDICATION_STATEMENT_COMMAND__POST_VALIDATION`
  - `ORDER_DME_COMMAND__POST_VALIDATION`
  - `PERFORM_COMMAND__POST_VALIDATION`
  - `PHYSICAL_EXAM_COMMAND__POST_VALIDATION`
  - `PLAN_COMMAND__POST_VALIDATION`
  - `POC_LAB_TEST_COMMAND__POST_VALIDATION`
  - `PRESCRIBE_COMMAND__POST_VALIDATION`
  - `QUESTIONNAIRE_COMMAND__POST_VALIDATION`
  - `REASON_FOR_VISIT_COMMAND__POST_VALIDATION`
  - `REFERENCE_COMMAND__POST_VALIDATION`
  - `REFER_COMMAND__POST_VALIDATION`
  - `REFILL_COMMAND__POST_VALIDATION`
  - `REMOVE_ALLERGY_COMMAND__POST_VALIDATION`
  - `REMOVE_PAST_MEDICAL_HISTORY_COMMAND__POST_VALIDATION`
  - `RESOLVE_CONDITION_COMMAND__POST_VALIDATION`
  - `ROS_COMMAND__POST_VALIDATION`
  - `SNOOZE_PROTOCOL_COMMAND__POST_VALIDATION`
  - `STOP_MEDICATION_COMMAND__POST_VALIDATION`
  - `STRUCTURED_ASSESSMENT_COMMAND__POST_VALIDATION`
  - `SURGICAL_HISTORY_COMMAND__POST_VALIDATION`
  - `TASK_COMMAND__POST_VALIDATION`
  - `UPDATE_DIAGNOSIS_COMMAND__POST_VALIDATION`
  - `UPDATE_GOAL_COMMAND__POST_VALIDATION`
  - `VALIDATE_CODING_GAP_COMMAND__POST_VALIDATION`
  - `VISUAL_EXAM_FINDING_COMMAND__POST_VALIDATION`
  - `VITALS_COMMAND__POST_VALIDATION`
The Custom Command, Imaging Review, Lab Review, Referral Review, Uncategorized Document Review commands do **not** fire `__POST_VALIDATION`, so they can't be validated with this effect.
The following handler validates a Plan command to ensure it meets specific requirements:
    ```python
    from canvas_sdk.commands import PlanCommand
    from canvas_sdk.commands.validation import CommandValidationErrorEffect
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    class MyHandler(BaseHandler):
        """
        Example protocol demonstrating command validation.
        This protocol validates Plan commands to ensure they meet
        organizational requirements before being committed.
        """
        RESPONDS_TO = EventType.Name(EventType.PLAN_COMMAND__POST_VALIDATION)
        def compute(self) -> list[Effect]:
            log.info("Running command validation protocol.")
            # Extract command fields from context
            narrative = self.context["fields"]["narrative"]
            # Create the validation effect
            effect = CommandValidationErrorEffect()
            # Perform validation checks
            if not narrative or not narrative.strip():
                effect.add_error("Narrative is required and cannot be empty")
            elif len(narrative.strip()) < 10:
                effect.add_error("Narrative must be at least 10 characters long")
            # Check for prohibited content
            prohibited_terms = ["TODO", "TBD", "FIXME"]
            if any(term in narrative.upper() for term in prohibited_terms):
                effect.add_error("Narrative cannot contain placeholder text (TODO, TBD, FIXME)")
            # Check for required keywords (example: follow-up plans must mention timeline)
            if "follow" in narrative.lower() and not any(word in narrative.lower() for word in ["week", "month", "day"]):
                effect.add_error("Follow-up plans must include a specific timeline")
            # Return the effect
            return [effect.apply()]
    ```
When validation errors are returned, the Canvas UI shows them to the user — the command's action buttons are disabled and the messages appear as a tooltip — so the command can't be committed there. Multiple errors can be returned at once, and all are displayed.
On a Refill command, the error disables the command's **REVIEW** button, so the user can't reach **Sign and send** , **Sign** , or **Print**. The message appears as a tooltip on the disabled button. The [`example_commands` example plugin](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/example_commands) blocks every refill this way; add a condition to its handler to block refills selectively.
Return the error from the `__POST_VALIDATION` event, not `__PRE_COMMIT`. On a Refill command, a validation error returned from `REFILL_COMMAND__PRE_COMMIT` is ignored, and the refill commits anyway.
> **Note:** `__POST_VALIDATION` only gates committing **in the Canvas UI**. A `.commit()` made through the SDK [commands module](/sdk/commands/) is **not** blocked by these errors — the command still commits. Use it as a UI guardrail, not as an enforced rule on SDK-driven commits. (Blocking a deletion, below, _does_ work through both the UI and the SDK.)
##  Block a deletion 
Return a `CommandValidationErrorEffect` from a command's `__PRE_DELETE` handler to block its deletion. Unlike `__POST_VALIDATION`, this works through **both** the Canvas UI and the SDK [commands module](/sdk/commands/): the deletion is aborted, the surrounding transaction is rolled back, and the error messages are returned to whatever initiated the delete — a [`delete()`](/sdk/commands/) call or a delete in the UI. For SDK-initiated deletes, the error is written to `canvas logs`. Pre-delete events follow the pattern:
`{COMMAND_KEY}_COMMAND__PRE_DELETE`
`__PRE_DELETE` is fired by the following command types (every command except Chart Section Review):
  - `ADD_CONDITION_COMMAND__PRE_DELETE`
  - `ADJUST_PRESCRIPTION_COMMAND__PRE_DELETE`
  - `ALLERGY_COMMAND__PRE_DELETE`
  - `APPROVE_REFILL_COMMAND__PRE_DELETE`
  - `ASSESS_CODING_GAP_COMMAND__PRE_DELETE`
  - `ASSESS_COMMAND__PRE_DELETE`
  - `CANCEL_PRESCRIPTION_COMMAND__PRE_DELETE`
  - `CHANGE_MEDICATION_COMMAND__PRE_DELETE`
  - `CLIPBOARD_COMMAND__PRE_DELETE`
  - `CLOSE_GOAL_COMMAND__PRE_DELETE`
  - `CREATE_CODING_GAP_COMMAND__PRE_DELETE`
  - `CUSTOM_COMMAND_COMMAND__PRE_DELETE`
  - `DEFER_CODING_GAP_COMMAND__PRE_DELETE`
  - `DENY_REFILL_COMMAND__PRE_DELETE`
  - `DIAGNOSE_COMMAND__PRE_DELETE`
  - `EDUCATIONAL_MATERIAL_COMMAND__PRE_DELETE`
  - `FAMILY_HISTORY_COMMAND__PRE_DELETE`
  - `FOLLOW_UP_COMMAND__PRE_DELETE`
  - `GOAL_COMMAND__PRE_DELETE`
  - `HISTORY_OF_PRESENT_ILLNESS_COMMAND__PRE_DELETE`
  - `IMAGING_ORDER_COMMAND__PRE_DELETE`
  - `IMAGING_REVIEW_COMMAND__PRE_DELETE`
  - `IMMUNIZATION_STATEMENT_COMMAND__PRE_DELETE`
  - `IMMUNIZE_COMMAND__PRE_DELETE`
  - `INSTRUCT_COMMAND__PRE_DELETE`
  - `LAB_ORDER_COMMAND__PRE_DELETE`
  - `LAB_REVIEW_COMMAND__PRE_DELETE`
  - `MEDICAL_HISTORY_COMMAND__PRE_DELETE`
  - `MEDICATION_STATEMENT_COMMAND__PRE_DELETE`
  - `ORDER_DME_COMMAND__PRE_DELETE`
  - `PERFORM_COMMAND__PRE_DELETE`
  - `PHYSICAL_EXAM_COMMAND__PRE_DELETE`
  - `PLAN_COMMAND__PRE_DELETE`
  - `POC_LAB_TEST_COMMAND__PRE_DELETE`
  - `PRESCRIBE_COMMAND__PRE_DELETE`
  - `QUESTIONNAIRE_COMMAND__PRE_DELETE`
  - `REASON_FOR_VISIT_COMMAND__PRE_DELETE`
  - `REFERENCE_COMMAND__PRE_DELETE`
  - `REFERRAL_REVIEW_COMMAND__PRE_DELETE`
  - `REFER_COMMAND__PRE_DELETE`
  - `REFILL_COMMAND__PRE_DELETE`
  - `REMOVE_ALLERGY_COMMAND__PRE_DELETE`
  - `REMOVE_PAST_MEDICAL_HISTORY_COMMAND__PRE_DELETE`
  - `RESOLVE_CONDITION_COMMAND__PRE_DELETE`
  - `ROS_COMMAND__PRE_DELETE`
  - `SNOOZE_PROTOCOL_COMMAND__PRE_DELETE`
  - `STOP_MEDICATION_COMMAND__PRE_DELETE`
  - `STRUCTURED_ASSESSMENT_COMMAND__PRE_DELETE`
  - `SURGICAL_HISTORY_COMMAND__PRE_DELETE`
  - `TASK_COMMAND__PRE_DELETE`
  - `UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__PRE_DELETE`
  - `UPDATE_DIAGNOSIS_COMMAND__PRE_DELETE`
  - `UPDATE_GOAL_COMMAND__PRE_DELETE`
  - `VALIDATE_CODING_GAP_COMMAND__PRE_DELETE`
  - `VISUAL_EXAM_FINDING_COMMAND__PRE_DELETE`
  - `VITALS_COMMAND__PRE_DELETE`
The following handler prevents deletion of a Refer command once its priority has been set to `Urgent` or `STAT`, so high-priority referrals can't be removed by mistake. The command's field values are available on the event context, so no extra lookup is needed:
    ```python
    from canvas_sdk.commands import ReferCommand
    from canvas_sdk.commands.validation import CommandValidationErrorEffect
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class BlockUrgentReferralDeletionHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.REFER_COMMAND__PRE_DELETE)
        def compute(self) -> list[Effect]:
            priority = self.context["fields"].get("priority")
            protected = {ReferCommand.Priority.URGENT.value, ReferCommand.Priority.STAT.value}
            if priority in protected:
                effect = CommandValidationErrorEffect()
                effect.add_error(
                    f"A {priority}-priority referral can't be deleted. "
                    "Lower its priority first if you need to remove it."
                )
                return [effect.apply()]
            return []
    ```
When a delete is attempted on an `Urgent` or `STAT` referral, it is blocked and the error message is returned to whoever initiated it.
For more information about command events and their context objects, see the [Events documentation](/sdk/events/).

---

# Compound Medication Effects

Source: https://docs.canvasmedical.com/sdk/effect-compound-medication/

The Compound Medication effects enable the creation and management of compound medication formulations within the Canvas system. These effects support the customization of medications prepared by compounding pharmacies according to prescriptions.
Build a `CompoundMedication` with the attributes you want to set, then return one of its two methods from your handler: `create()` for a new compound medication, or `update()` for an existing one.
##  Methods 
###  create() → Effect 
Creates a compound medication.
  - `formulation`, `potency_unit_code`, and `controlled_substance` are required.
  - `controlled_substance_ndc` is also required when `controlled_substance` is anything other than `"N"`.
See Creating a compound medication for an example.
###  update() → Effect 
Updates an existing compound medication.
  - `instance_id` is required, and must be the id of an existing compound medication.
  - Only the attributes you set on the effect are changed. Attributes you leave unset keep their current values.
See Updating a compound medication for an example.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `str` or `None`| The id of the compound medication to update| For `update()`  
`formulation`| `str` or `None`| The compound medication formulation (max 105 characters)| For `create()`  
`potency_unit_code`| `str` or `None`| The unit of measurement for the medication| For `create()`  
`controlled_substance`| `str` or `None`| The controlled substance schedule| For `create()`  
`controlled_substance_ndc`| `str` or `None`| NDC code for controlled substances (dashes removed)| When `controlled_substance` is not `"N"`  
`active`| `bool` or `None`| Whether the compound medication is active. Defaults to `True` on creation.| No  
##  Example Usage 
###  Creating a compound medication 
    ```python
    from canvas_sdk.effects.compound_medications import CompoundMedication as CompoundMedicationEffect
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.events import EventType
    from canvas_sdk.v1.data.compound_medication import CompoundMedication as CompoundMedicationModel
    class CompoundMedicationCreator(BaseHandler):
      RESPONDS_TO = [EventType.Name(EventType.PATIENT_CREATED)]
      def compute(self):
        # Create a non-controlled compound medication
        compound_med = CompoundMedicationEffect(
          formulation="Testosterone 200mg/mL in Grapeseed Oil",
          potency_unit_code=CompoundMedicationModel.PotencyUnit.Milliliter,
          controlled_substance=CompoundMedicationModel.ControlledSubstanceSchedule.SCHEDULE_NOT_SCHEDULED,
          active=True
        )
        # Create a controlled substance compound medication
        controlled_compound = CompoundMedicationEffect(
          formulation="Hydrocodone 5mg/Acetaminophen 325mg Capsule",
          potency_unit_code=CompoundMedicationModel.PotencyUnit.Capsule,
          controlled_substance=CompoundMedicationModel.ControlledSubstanceSchedule.SCHEDULE_II,
          controlled_substance_ndc="12345678901",
          active=True
        )
        return [compound_med.create(), controlled_compound.create()]
    ```
###  Updating a compound medication 
    ```python
    from canvas_sdk.effects.compound_medications import CompoundMedication as CompoundMedicationEffect
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.compound_medication import CompoundMedication as CompoundMedicationModel
    from canvas_sdk.events import EventType
    class CompoundMedicationUpdater(BaseHandler):
      RESPONDS_TO = [EventType.Name(EventType.PLUGIN_CREATED)]
      def compute(self):
        # Find a compound medication to update
        compound_med = CompoundMedicationModel.objects.filter(
            formulation__contains="Testosterone"
        ).first()
        if compound_med:
            # Update to make it a controlled substance
            update_effect = CompoundMedicationEffect(
                instance_id=str(compound_med.id),
                controlled_substance="III",
                controlled_substance_ndc="98765432101"
            )
            return [update_effect.update()]
        return []
    ```
##  Implementation Details 
  - **Formulation Validation** : The formulation field is limited to 105 characters
  - **NDC Formatting** : Any dashes in the NDC code are automatically removed during processing
  - **Cross-field Validation** : When a controlled substance schedule is specified (anything other than "N"), an NDC code must be provided
  - **Default Values** : If not specified, `active` defaults to `True` for new compound medications
  - **Potency Unit Codes** : Must use valid codes as defined in the [PotencyUnit](/sdk/data-compound-medication/#potencyunit) enumeration
  - **Controlled Substance Schedules** : Must use valid values as defined in the [ControlledSubstanceSchedule](/sdk/data-compound-medication/#controlledsubstanceschedule) enumeration
##  Validation 
Both methods perform validation before execution:
###  Create Effect Validation: 
  - Validates all required fields are provided
  - Ensures `potency_unit_code` is a valid value from the PotencyUnit enumeration
  - Ensures `controlled_substance` is a valid schedule from the ControlledSubstanceSchedule enumeration
  - Validates NDC is provided for controlled substances (when schedule is not "N")
  - Checks formulation length does not exceed 105 characters
###  Update Effect Validation: 
  - Verifies the compound medication exists before updating
  - Validates any provided fields follow the same rules as creation
  - Ensures NDC is provided if updating to a controlled substance
  - Only updates fields that are explicitly provided (partial updates supported)
##  Error Handling 
If validation fails, a `ValidationError` is raised with detailed error messages indicating which fields failed validation and why. Error messages are aggregated to provide comprehensive feedback about all validation failures at once.

---

# Configure Command Buttons

Source: https://docs.canvasmedical.com/sdk/effect-configure-command-buttons/

The `ConfigureCommandButtons` effect allows plugins to hide or disable the command buttons that appear in specific areas of the patient chart — such as the conditions section, medications section, or protocol cards.
Build a `ConfigureCommandButtons` with the attributes you want to set, then return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Applies the button visibility to the patient's chart.
  - `patient_id` is required.
  - Each `location` may appear only once in `locations`; a duplicate raises a `ValidationError`.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`patient_id`| `str`| The id of the [patient](/sdk/data-patient/).| Yes  
`locations`| `list[``LocationConfig``]`| Areas to configure. Areas not listed retain their default visible state.| No  
##  LocationConfig 
Each entry in `locations` is a `LocationConfig` with the following attributes, both required:
Attribute| Type| Description  
---|---|---  
`location`| `Location`| The chart area to configure  
`visibility`| `Visibility`| The visibility state for that area  
##  Locations 
The `Location` enum defines which areas of the chart can be configured:
Value| Area  
---|---  
`CONDITIONS`| Conditions chart summary section  
`MEDICATIONS`| Medications chart summary section  
`ALLERGIES`| Allergies chart summary section  
`GOALS`| Goals chart summary section  
`VITALS`| Vitals chart summary section  
`IMMUNIZATIONS`| Immunizations chart summary section  
`SURGICAL_HISTORY`| Surgical history chart summary section  
`FAMILY_HISTORY`| Family history chart summary section  
`SOCIAL_DETERMINANTS`| Social determinants chart summary section  
`CARE_TEAMS`| Care teams chart summary section  
`CODING_GAPS`| Coding gaps chart summary section  
`QUALITY_PROTOCOLS`| Quality protocol result cards  
`LAB_REVIEWS`| Lab report review result cards  
`IMAGING_REVIEWS`| Imaging report review result cards  
`REFERRAL_REVIEWS`| Referral report review result cards  
`DOCUMENT_REVIEWS`| Uncategorized document review result cards  
##  Visibility 
Each location can be configured with one of three visibility values:
Value| Behavior  
---|---  
`VISIBLE`| Buttons are shown and interactive (default when not listed)  
`HIDDEN`| Buttons are not rendered  
`DISABLED`| Buttons are rendered but not interactive  
##  Example: Patient Chart Load 
`PATIENT_TIMELINE__GET_CONFIGURATION` fires every time a patient chart is opened, making it a convenient hook for configuring button visibility on chart load. The example below hides all command buttons across every location:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.configure_command_buttons import ConfigureCommandButtons
    from canvas_sdk.events import EventType
    from canvas_sdk.protocols import BaseProtocol
    Location = ConfigureCommandButtons.Location
    LocationConfig = ConfigureCommandButtons.LocationConfig
    Visibility = ConfigureCommandButtons.Visibility
    class HideButtonsOnChartLoad(BaseProtocol):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_TIMELINE__GET_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [
                ConfigureCommandButtons(
                    patient_id=self.target,
                    locations=[
                        LocationConfig(location=loc, visibility=Visibility.HIDDEN)
                        for loc in Location
                    ],
                ).apply()
            ]
    ```
##  Example: Note Applications 
One use case is toggling chart buttons alongside a `NoteApplication`. When the application tab opens, `on_open` disables chart buttons. When the provider switches back to the note body, Canvas sends a `NOTE_TAB_CHANGE` message to the iframe, which calls a `SimpleAPI` endpoint to restore them.
###  Python 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.configure_command_buttons import ConfigureCommandButtons
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.application import NoteApplication
    from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin, api
    from canvas_sdk.templates import render_to_string
    Location = ConfigureCommandButtons.Location
    LocationConfig = ConfigureCommandButtons.LocationConfig
    Visibility = ConfigureCommandButtons.Visibility
    class MyChartingApp(NoteApplication):
        NAME = "My Charting App"
        IDENTIFIER = "my-plugin:charting-app"
        def on_open(self) -> list[Effect]:
            patient_id = self.event.context.get("patient", {}).get("id")
            return [
                LaunchModalEffect(
                    target=LaunchModalEffect.TargetType.NOTE,
                    content=render_to_string(
                        "templates/charting_app.html",
                        context={"identifier": self.IDENTIFIER},
                    ),
                    title="My Charting App",
                ).apply(),
                ConfigureCommandButtons(
                    patient_id=patient_id,
                    locations=[
                        LocationConfig(location=loc, visibility=Visibility.DISABLED)
                        for loc in Location
                    ],
                ).apply(),
            ]
    class CommandButtonsApi(StaffSessionAuthMixin, SimpleAPI):
        @api.post("/configure-buttons/disable")
        def disable(self) -> list[Response | Effect]:
            patient_id = self.request.json().get("patient_id")
            return [
                JSONResponse({"ok": True}),
                ConfigureCommandButtons(
                    patient_id=patient_id,
                    locations=[
                        LocationConfig(location=loc, visibility=Visibility.DISABLED)
                        for loc in Location
                    ],
                ).apply(),
            ]
        @api.post("/configure-buttons/enable")
        def enable(self) -> list[Response | Effect]:
            patient_id = self.request.json().get("patient_id")
            return [
                JSONResponse({"ok": True}),
                ConfigureCommandButtons(
                    patient_id=patient_id,
                    locations=[
                        LocationConfig(location=loc, visibility=Visibility.VISIBLE)
                        for loc in Location
                    ],
                ).apply(),
            ]
    ```
###  Template 
The iframe listens for `NOTE_TAB_CHANGE` messages from Canvas and calls the appropriate endpoint. When `tab` is `"note"` the provider has switched back to the note body; when `tab` matches the application's identifier the application tab is active.
    ```html
    <!-- templates/charting_app.html -->
    <script>
      var port;
      var myIdentifier = '';
      function post(endpoint, patientId) {
        fetch('/plugin-io/api/my_plugin/configure-buttons/' + endpoint, {
          method: 'POST',
          body: JSON.stringify({ patient_id: patientId })
        });
      }
      window.addEventListener('message', function(event) {
        if (event.data?.type === 'INIT_CHANNEL') {
          port = event.ports[0];
          port.onmessage = function(e) {
            if (e.data?.type === 'NOTE_TAB_CHANGE') {
              if (e.data.tab === 'note') post('enable', e.data.patient.id);
              else if (e.data.tab === myIdentifier) post('disable', e.data.patient.id);
            }
          };
        }
      });
    </script>
    ```
Both `MyChartingApp` and `CommandButtonsApi` should be registered as `handlers` in your [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#handlers).

---

# Coverage Effect

Source: https://docs.canvasmedical.com/sdk/effect-coverage/

The `Coverage` effect writes a patient's insurance coverage from a plugin, including the front and back images of the insurance card. Use it to capture insurance during intake, such as from a patient portal form where the patient photographs their card. You can also use it to keep coverages in step with an external system. The `CoverageReorder` effect changes the rank and stack of several coverages at once.
Canvas applies the same rules to these effects as it does to the coverage form in the patient's chart. The effects also check most of those rules in your plugin before the effect is sent. An invalid coverage raises a validation error in your handler.
To read coverages, see the [Coverage data model](/sdk/data-coverage/).
##  Methods 
Build a `Coverage` with the attributes you want to set, then return one of its methods from your handler.
###  create() → Effect 
Creates a coverage for a patient.
  - `patient_id`, `issuer_id`, `coverage_rank`, `id_number`, and `patient_relationship_to_subscriber` are required.
  - `coverage_id` must not be set.
  - The patient must not already have a coverage with the same `coverage_rank` in the same stack. A coverage that ends today or earlier, in the instance's time zone, frees its rank. To replace a primary coverage, expire the old one with today's date, then create the new one the same day.
  - `stack` defaults to `IN_USE`, and `coverage_start_date` defaults to today in the instance's time zone.
  - Canvas requests an eligibility check after the coverage is saved.
###  update() → Effect 
Changes an existing coverage.
  - `coverage_id` is required, and must be the id of an existing coverage.
  - Only the attributes you set on the effect are changed. Setting an optional attribute to `None` clears it.
  - The required attributes, `stack`, `subscriber_id`, and `coverage_start_date` cannot be set to `None` or an empty string.
  - `patient_id` cannot be changed.
  - If you change `issuer_id`, Canvas clears the coverage's `issuer_address_id`, `issuer_phone_id`, and `coverage_type`, unless you set new values in the same update.
  - If another coverage in the same stack already holds the new rank, the coverage you updated takes it. The other coverage moves down one rank.
  - Canvas requests a new eligibility check when the update changes `issuer_id`, `issuer_address_id`, `id_number`, `subscriber_id`, or `patient_relationship_to_subscriber`.
###  expire(coverage_end_date) → Effect 
Ends an existing coverage on `coverage_end_date`, a `datetime.date`. `coverage_id` is required. The end date must be on or after the coverage's start date; a coverage can end on the day it starts. Canvas records an audit event, as it does when a coverage is expired from the chart.
###  remove() → Effect 
Moves an existing coverage to the `REMOVED` stack. `coverage_id` is required. Canvas records an audit event.
`create()`, `update()`, and `CoverageReorder` do not accept the `REMOVED` stack. Use `remove()` instead.
###  remove_photo(side) → Effect 
Removes the front or back card image from an existing coverage. `coverage_id` is required. Set `side` to `PhotoSide.FRONT` or `PhotoSide.BACK`.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`coverage_id`| `UUID` or `str`| The `id` of an existing [Coverage](/sdk/data-coverage/#coverage). Must be unset when creating a coverage.| For every method except `create()`  
`patient_id`| `str`| The `id` of the [Patient](/sdk/data-patient/#patient) the coverage belongs to.| For `create()`  
`issuer_id`| `UUID` or `str`| The `id` of the payer, a [Transactor](/sdk/data-coverage/#transactor). The coverage's plan type comes from the payer.| For `create()`  
`issuer_address_id`| `UUID` or `str` or `None`| The `id` of a [TransactorAddress](/sdk/data-coverage/#transactoraddress) that belongs to the payer.| No  
`issuer_phone_id`| `UUID` or `str` or `None`| The `id` of a [TransactorPhone](/sdk/data-coverage/#transactorphone) that belongs to the payer.| No  
`patient_relationship_to_subscriber`| [`CoverageRelationshipCode`](/sdk/data-coverage/#coveragerelationshipcode)| The patient's relationship to the subscriber. See Subscribers.| For `create()`  
`subscriber_id`| `str`| The `id` of the [Patient](/sdk/data-patient/#patient) who holds the policy. See Subscribers.| When the patient is not the subscriber  
`subscriber_identifier`| `str` or `None`| The subscriber's identifier on the policy. Up to 100 characters.| No  
`coverage_rank`| [`CoverageRank`](/sdk/data-coverage/#coveragerank)| The coverage's order within its stack: `PRIMARY` (1), `SECONDARY` (2), `TERTIARY` (3), `QUATERNARY` (4), or `QUINARY` (5).| For `create()`  
`stack`| [`CoverageStack`](/sdk/data-coverage/#coveragestack)| `IN_USE` or `OTHER`. Defaults to `IN_USE` on create.| No  
`coverage_type`| [`TransactorCoverageType`](/sdk/data-coverage/#transactorcoveragetype) or `None`| The type of coverage.| No  
`id_number`| `str`| The member ID on the insurance card. Up to 100 characters.| For `create()`  
`plan`| `str` or `None`| Plan name. Up to 255 characters.| No  
`sub_plan`| `str` or `None`| Sub-plan name. Up to 255 characters.| No  
`group`| `str` or `None`| Group number. Up to 255 characters.| No  
`sub_group`| `str` or `None`| Sub-group number. Up to 255 characters.| No  
`employer`| `str` or `None`| The subscriber's employer. Up to 255 characters.| No  
`coverage_start_date`| `datetime.date`| The date the coverage starts. Must be on or before `coverage_end_date`. Defaults to today on create.| No  
`coverage_end_date`| `datetime.date` or `None`| The date the coverage ends.| No  
`comments`| `str` or `None`| Free-text comments.| No  
`card_image_front_upload_key`| `str` or `None`| The upload key of the front image of the insurance card. See Card images.| No  
`card_image_back_upload_key`| `str` or `None`| The upload key of the back image of the insurance card. See Card images.| No  
`CoverageRank`, `CoverageRelationshipCode`, `CoverageStack`, `TransactorCoverageType`, and `Transactor` are imported from `canvas_sdk.v1.data.coverage`. `PhotoSide` is imported from `canvas_sdk.effects.coverage`.
###  Subscribers 
When `patient_relationship_to_subscriber` is `CoverageRelationshipCode.SELF`, the patient is the subscriber. Leave `subscriber_id` unset, or set it to the patient's `id`.
For any other relationship, set `subscriber_id` to the `id` of a different patient, the person who holds the policy.
##  Card images 
Card images are PNG or JPEG files that a user uploads to your plugin through a SimpleAPI route declared with `file_uploads="stored"`. Set `card_image_front_upload_key` and `card_image_back_upload_key` to the `key` of each uploaded `StoredFilePart`. See [Storing uploaded files](/sdk/handlers-simple-api-http/#storing-uploaded-files).
Each key must come from a file your plugin uploaded, and each file must be a PNG or JPEG image. When the effect is applied, Canvas copies the file to the coverage and then deletes the upload, so each key works only once. If any part of the effect fails, Canvas saves none of it, including the card images.
On `update()`, setting one image key replaces that side of the card and leaves the other side unchanged. A key of `None` attaches no image, so that side also keeps its current image. To remove an image, use `remove_photo()`.
For working code, see Capture an insurance card from a form, which creates a coverage from uploaded card photos, and Expire or remove a coverage, or remove a card image, which removes one side of the card.
##  Reordering coverages 
`CoverageReorder` sets the rank and stack of several of a patient's coverages in one effect. Build it with the patient's `id` and an `ordering` list of `CoverageReorderEntry` objects, then return `apply()`.
Attribute| Type| Description  
---|---|---  
`patient_id`| `str`| The `id` of the [Patient](/sdk/data-patient/#patient).  
`ordering`| `list[CoverageReorderEntry]`| The new position of each coverage. Must contain at least one entry.  
Each `CoverageReorderEntry` has these attributes, all required:
Attribute| Type| Description  
---|---|---  
`coverage_id`| `UUID` or `str`| The `id` of one of the patient's [coverages](/sdk/data-coverage/#coverage).  
`coverage_rank`| [`CoverageRank`](/sdk/data-coverage/#coveragerank)| The coverage's new rank.  
`stack`| [`CoverageStack`](/sdk/data-coverage/#coveragestack)| The coverage's new stack: `IN_USE` or `OTHER`.  
The ordering must follow these rules:
  - Each coverage appears once and belongs to the patient.
  - Within each stack, ranks are unique and consecutive, starting at 1.
  - For each stack the ordering places a coverage in, the ordering lists every active coverage in that stack.
For working code, see Swap primary and secondary coverages.
##  Examples 
###  Capture an insurance card from a form 
This SimpleAPI route creates a primary coverage from a `multipart/form-data` request. The request carries the patient's id, the payer's id, the member ID, and photos of both sides of the card. The route uses the [API key mixin](/sdk/handlers-simple-api-http/#api-key-1), so declare the `simpleapi-api-key` secret in your manifest and set it on your instance:
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.coverage import Coverage
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPI, api
    from canvas_sdk.v1.data.coverage import CoverageRank, CoverageRelationshipCode
    class InsuranceCardAPI(APIKeyAuthMixin, SimpleAPI):
        @api.post("/insurance-card", file_uploads="stored")
        def insurance_card(self) -> list[Response | Effect]:
            form = self.request.form_data()
            front = form["card_front"]
            back = form["card_back"]
            if front.error or back.error:
                return [JSONResponse({"error": "upload failed"}, status_code=HTTPStatus.BAD_GATEWAY)]
            coverage = Coverage(
                patient_id=form["patient_id"].value,
                issuer_id=form["payer_id"].value,
                id_number=form["member_id"].value,
                coverage_rank=CoverageRank.PRIMARY,
                patient_relationship_to_subscriber=CoverageRelationshipCode.SELF,
                card_image_front_upload_key=front.key,
                card_image_back_upload_key=back.key,
            )
            return [coverage.create(), JSONResponse({}, status_code=HTTPStatus.ACCEPTED)]
    ```
Call the route with a `multipart/form-data` POST. Each form field name matches a key the handler reads, the two card photos are sent as files, and the API key goes in the `Authorization` header:
    ```shell
    curl --request POST \
         --url 'https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/insurance-card' \
         --header 'Authorization: <api-key>' \
         --form 'patient_id=b80b1cdc2e6a4aca90ccebc02e683f35' \
         --form 'payer_id=0f3b6c1e-9a2d-4e7b-8c5f-1d2e3a4b5c6d' \
         --form 'member_id=W123456789' \
         --form 'card_front=@card-front.jpg;type=image/jpeg' \
         --form 'card_back=@card-back.jpg;type=image/jpeg'
    ```
The same request from a Python script, uploading two card photos saved on disk, using the [`requests`](https://requests.readthedocs.io/) library:
    ```python
    from pathlib import Path
    import requests
    url = "https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/insurance-card"
    front_path = Path("card-front.jpg")
    back_path = Path("card-back.jpg")
    with front_path.open("rb") as front, back_path.open("rb") as back:
        response = requests.post(
            url,
            headers={"Authorization": "<api-key>"},
            data={
                "patient_id": "b80b1cdc2e6a4aca90ccebc02e683f35",
                "payer_id": "0f3b6c1e-9a2d-4e7b-8c5f-1d2e3a4b5c6d",
                "member_id": "W123456789",
            },
            files={
                "card_front": (front_path.name, front, "image/jpeg"),
                "card_back": (back_path.name, back, "image/jpeg"),
            },
            timeout=30,
        )
    print(response.status_code)
    ```
Passing `files` makes `requests` send the request as `multipart/form-data`, with each `data` entry as a plain form field. Each file is a `(filename, file, content_type)` tuple; open it in binary mode.
`curl --form` sends the request as `multipart/form-data` too. A browser form does the same with `enctype="multipart/form-data"`, or a `FormData` object passed to `fetch`. The route answers:
  - `202 Accepted` when both photos were stored and the coverage effect was returned.
  - `502 Bad Gateway` when a photo failed to store. Canvas returns this before calling the handler when every file fails; the handler returns it when only one does.
  - `400 Bad Request` when the request isn't `multipart/form-data`.
  - `401 Unauthorized` when the API key is missing or wrong.
To find a payer's `id`, query the [Transactor](/sdk/data-coverage/#transactor) model:
    ```python
    from canvas_sdk.v1.data.coverage import Transactor
    payer = Transactor.objects.filter(name__icontains="aetna", active=True).first()
    ```
###  Update a coverage 
    ```python
    from canvas_sdk.effects.coverage import Coverage
    from canvas_sdk.v1.data.coverage import Coverage as CoverageModel
    coverage = CoverageModel.objects.get(id="b3b5e4f6-1c2d-4e8a-9f0b-7a6c5d4e3f21")
    # Change the group number and clear the comments
    effect = Coverage(coverage_id=coverage.id, group="GRP-2027", comments=None).update()
    ```
###  Expire or remove a coverage, or remove a card image 
    ```python
    from datetime import date
    from canvas_sdk.effects.coverage import Coverage, PhotoSide
    coverage_id = "b3b5e4f6-1c2d-4e8a-9f0b-7a6c5d4e3f21"
    expire = Coverage(coverage_id=coverage_id).expire(coverage_end_date=date(2026, 12, 31))
    remove = Coverage(coverage_id=coverage_id).remove()
    remove_back = Coverage(coverage_id=coverage_id).remove_photo(side=PhotoSide.BACK)
    ```
###  Swap primary and secondary coverages 
    ```python
    from canvas_sdk.effects.coverage import CoverageReorder, CoverageReorderEntry
    from canvas_sdk.v1.data.coverage import CoverageRank, CoverageStack
    effect = CoverageReorder(
        patient_id="d7af3e356368446c85b40a5d6ff7288e",
        ordering=[
            CoverageReorderEntry(
                coverage_id="b3b5e4f6-1c2d-4e8a-9f0b-7a6c5d4e3f21",
                coverage_rank=CoverageRank.PRIMARY,
                stack=CoverageStack.IN_USE,
            ),
            CoverageReorderEntry(
                coverage_id="4a9e2c71-8d3b-4f5e-a6c0-1b2d3e4f5a6b",
                coverage_rank=CoverageRank.SECONDARY,
                stack=CoverageStack.IN_USE,
            ),
        ],
    ).apply()
    ```

---

# CreateCCDA

Source: https://docs.canvasmedical.com/sdk/effect-create-ccda-export/

The `CreateCCDA` effect creates a C-CDA document for a patient with the provided XML content. This effect allows plugins to store C-CDA XML documents, which can be used for clinical document exchange, patient summaries, or referrals.
This effect stores a C-CDA document, generating or otherwise sourcing that document is the responsibility of the plugin.
Build a `CreateCCDA` and return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Creates the C-CDA document for the patient.
  - `patient_id` and `content` are required. `patient_id` must be the id of an existing patient, and `content` must be valid XML.
  - `document_type` defaults to `CCD`.
##  Attributes 
Name| Type| Description| Required  
---|---|---|---  
`patient_id`| `str`| The id of the [patient](/sdk/data-patient/).| Yes  
`content`| `str`| The C-CDA XML content as a string. Must be valid XML.| Yes  
`document_type`| `DocumentType`| Type of C-CDA document. Defaults to `DocumentType.CCD`.| No  
##  DocumentType Enum 
Value| Description  
---|---  
`CCD`| Continuity of Care Document (default)  
`REFERRAL`| Referral document  
##  Validation 
The effect performs the following validations before execution:
  - **Patient Exists** : Verifies that a patient with the given `patient_id` exists in the system.
  - **Valid XML** : Validates that the `content` field contains well-formed XML. Malformed XML will result in a validation error.
  - **Required Fields** : Both `patient_id` and `content` must be non-empty strings.
##  Example Usage 
###  Basic CCD Creation 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.ccda import CreateCCDA, DocumentType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.PATIENT_UPDATED)]
        def compute(self) -> list[Effect]:
            # Sample C-CDA XML content
            ccda_xml = """<?xml version="1.0" encoding="UTF-8"?>
            <ClinicalDocument xmlns="urn:hl7-org:v3">
                <typeId root="2.16.840.1.113883.1.3" extension="POCD_HD000040"/>
                <templateId root="2.16.840.1.113883.10.20.22.1.1"/>
                <id root="document-id"/>
                <code code="34133-9" displayName="Summarization of Episode Note"
                      codeSystem="2.16.840.1.113883.6.1"/>
                <title>Patient Summary</title>
                <effectiveTime value="20240101120000"/>
                <confidentialityCode code="N" codeSystem="2.16.840.1.113883.5.25"/>
                <languageCode code="en-US"/>
            </ClinicalDocument>"""
            effect = CreateCCDA(
                patient_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                content=ccda_xml,
                document_type=DocumentType.CCD,
            )
            return [effect.apply()]
    ```
###  Creating a Referral Document 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.ccda import CreateCCDA, DocumentType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.PATIENT_UPDATED)]
        def compute(self) -> list[Effect]:
            referral_xml_content = "<ClinicalDocument>...</ClinicalDocument>"
            effect = CreateCCDA(
                patient_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                content=referral_xml_content,
                document_type=DocumentType.REFERRAL,
            )
            return [effect.apply()]
    ```
###  Using Default Document Type 
When `document_type` is not specified, it defaults to `CCD`:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.ccda import CreateCCDA
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.PATIENT_UPDATED)]
        def compute(self) -> list[Effect]:
            ccda_xml = "<ClinicalDocument>...</ClinicalDocument>"
            effect = CreateCCDA(
                patient_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                content=ccda_xml,
            )
            # document_type defaults to DocumentType.CCD
            return [effect.apply()]
    ```
##  Use Cases 
  - **Clinical Document Exchange** : Generate C-CDAs for sharing patient information with external systems or providers.
  - **Patient Summaries** : Create Continuity of Care Documents containing a patient's clinical summary.
  - **Referral Documentation** : Generate referral documents when referring patients to specialists.
  - **Integration with External Systems** : Produce standardized C-CDA documents for healthcare interoperability.
##  Notes 
  - The C-CDA XML content is stored as a file on the patient's record. You can access the record in Settings > CCDAs to be able to view, transmit, or download the file.

---

# CreatePatientExternalIdentifier

Source: https://docs.canvasmedical.com/sdk/effect-create-patient-external-identifier/

Creates a new external identifier for a patient.
##  Methods 
###  create() → Effect 
Creates the external identifier on the patient.
  - `value` and `patient_id` are required.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`patient_id`| `str`| The id of the [patient](/sdk/data-patient/).| Yes  
`system`| `str`| The system for the external identifier (url).| No  
`value`| `str`| The value of the external identifier.| Yes  
##  Example 
    ```python
    from canvas_sdk.effects.patient import CreatePatientExternalIdentifier
    effect = CreatePatientExternalIdentifier(
        patient_id="1eed3ea2a8d546a1b681a2a45de1d790",
        system="https://www.va.gov/",
        value="VET123456"
    )
    effect.create()
    ```
This effect will create a new external identifier for the specified patient.

---

# CreatePatientPreferredPharmacies

Source: https://docs.canvasmedical.com/sdk/effect-create-patient-preferred-pharmacies/

Creates preferred pharmacies for a patient.
##  Methods 
###  create() → Effect 
Sets the patient's preferred pharmacies.
  - `patient_id` and `pharmacies` are required, and `patient_id` must be the id of an existing patient.
  - At most one pharmacy in `pharmacies` can be marked as the default.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`patient_id`| `str` or `UUID`| The id of the [patient](/sdk/data-patient/).| Yes  
`pharmacies`| list[PatientPreferredPharmacy]| List of pharmacies to create.| Yes  
##  PatientPreferredPharmacy 
The `PatientPreferredPharmacy` dataclass represents a patient's preferred pharmacy, and if it's their default pharmacy.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`ncpdp_id`| `str`| The NCPDC identifier of the pharmacy.| Yes  
`default`| `bool`| Indicates if this is the patient's default pharmacy. Defaults to `False`.| No  
###  Validation 
When this effect is interpreted, Canvas validates the `ncpdp_id` before setting the preferred pharmacy. If the `ncpdp_id` is invalid or does not exist, the effect will fail.
To ensure the `ncpdp_id` exists before using this effect, you can verify it using Canvas's [pharmacy HTTP utility](/sdk/utils/#making-requests-to-the-pharmacy-service) to check the pharmacy beforehand.
##  Example 
    ```python
    from canvas_sdk.effects.patient import CreatePatientPreferredPharmacies, PatientPreferredPharmacy
    from canvas_sdk.v1.data import Patient as PatientModel
    first_patient_id = PatientModel.objects.values_list("id", flat=True).first()
    preferred_pharmacies_effect = CreatePatientPreferredPharmacies(
                                    pharmacies=[PatientPreferredPharmacy(ncpdp_id="0586163", default=True)],
                                    patient_id=first_patient_id
    )
    preferred_pharmacies_effect.create()
    ```
This effect will create a new preferred pharmacy for the specified patient.
Since the `default` attribute is set to `True`, it will mark this pharmacy as the patient's default preferred pharmacy.

---

# Data Integration

Source: https://docs.canvasmedical.com/sdk/effect-data-integration/

Plugins can automate triage of inbound clinical documents in the [Data Integration queue](/sdk/data-integration-task/) — lab reports, imaging reports, faxes, clinical and administrative documents, and other uploaded files awaiting staff review before they're attached to a patient's chart.
Most of these effects work by writing a **prefill suggestion** to the IntegrationTask. The Data Integration UI surfaces that suggestion as a pre-populated value in the staff member's review form — the suggested patient, document type, template values, or reviewer assignment — along with optional annotation badges. A staff member still reviews and commits the change; the plugin doesn't directly mutate the IntegrationTask.
The exceptions are `JunkDocument` and `RemoveDocumentFromPatient`, which act on the IntegrationTask's status or patient link immediately without writing a prefill.
##  Assigning a Reviewer 
To assign a staff member or team as the reviewer for a document in the Data Integration queue, build an `AssignDocumentReviewer` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Suggests the reviewer for the document.
  - `document_id` is required.
  - Set `reviewer_id` or `team_id`. If both are set, the staff reviewer is used; with neither, the effect does nothing.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`document_id`| `str`| The `id` of the [IntegrationTask](/sdk/data-integration-task/#integrationtask) document.| Yes  
`reviewer_id`| `str`| The `id` of the [Staff](/sdk/data-staff/#staff) member to assign as reviewer.| One of `reviewer_id` or `team_id`  
`team_id`| `str`| The `id` of the [Team](/sdk/data-team/#team) to assign as reviewer.| One of `reviewer_id` or `team_id`  
`review_mode`| ReviewMode| Review mode. Defaults to `ReviewMode.REVIEW_REQUIRED`.| No  
`annotations`| `list`| List of annotations for display in the UI. See Annotations.| No  
###  ReviewMode 
Value| Description  
---|---  
`ReviewMode.REVIEW_REQUIRED` (default)| Document requires explicit review.  
`ReviewMode.ALREADY_REVIEWED`| Document is marked as already reviewed.  
`ReviewMode.REVIEW_NOT_REQUIRED`| Document does not require review.  
An example of assigning a staff reviewer. Annotations render as colored badges next to the reviewer field in the Data Integration UI — useful for surfacing why the plugin chose this reviewer:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.data_integration import AssignDocumentReviewer, ReviewMode
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class AssignReviewerHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.DOCUMENT_RECEIVED)
        def compute(self) -> list[Effect]:
            return [
                AssignDocumentReviewer(
                    document_id=self.event.target.id,
                    reviewer_id="4150cd20de8a470aa570a852859ac87e",
                    review_mode=ReviewMode.ALREADY_REVIEWED,
                    annotations=[
                        {"text": "Team lead", "color": "#4CAF50"},
                        {"text": "Auto-assigned", "color": "#FF9800"},
                    ],
                ).apply()
            ]
    ```
An example of assigning a team instead of an individual reviewer:
    ```python
    from canvas_sdk.effects.data_integration import AssignDocumentReviewer
    assign_reviewer = AssignDocumentReviewer(
        document_id="d2194110-5c9a-4842-8733-ef09ea5ead11",
        team_id="3f8a2e1c-9b4d-4f5a-8c7e-1d2b3a4c5d6e",
        annotations=[
            {"text": "Routed to Coding team", "color": "#2196F3"},
        ],
    )
    ```
##  Categorizing a Document 
To categorize a document in the Data Integration queue into a specific document type, build a `CategorizeDocument` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Suggests the document type.
  - `document_id` and `document_type` are required.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`document_id`| `str`| The `id` of the [IntegrationTask](/sdk/data-integration-task/#integrationtask) document to categorize.| Yes  
`document_type`| DocumentType| Document type information for categorizing the document.| Yes  
`annotations`| `list`| List of annotations for display in the UI. See Annotations.| No  
###  DocumentType 
The `document_type` parameter is a dictionary with the following fields:
Key|  | Type| Description  
---|---|---|---  
`key`| required| string| The unique key identifying the document type. Must match a key from the Supported Document Types table below.  
`name`| required| string| The human-readable name of the document type. Should match the catalog's `Name` for that key.  
`report_type`| required| string| The type of report. Must be `"CLINICAL"` or `"ADMINISTRATIVE"`.  
`template_type`| required| string | null| Must be `"LabReportTemplate"`, `"ImagingReportTemplate"`, `"SpecialtyReportTemplate"`, or `null`.  
###  Supported Document Types 
Canvas's built-in document type catalog. Use the `Key` value in your `document_type` dict; the other columns show the catalog's `report_type` and the matching parse template (when applicable).
Name| Key| Report Type| Template Type  
---|---|---|---  
Advance Beneficiary Notice| `5375e6ae238e41b4972717174be99d10`| ADMINISTRATIVE| `null`  
Advance Directive / Living Will| `1d5a4821140dab935e90d9d73bfd7a35`| ADMINISTRATIVE| `null`  
CDL (Commercial Driver License)| `7639c58fb4b75e2ff74270787eda80a7`| ADMINISTRATIVE| `null`  
Care Management| `6b4b539a233145fe871e8ac703f39fcb`| CLINICAL| `null`  
Disability Form| `a5fd8d81026747c0b01f757b7935f82a`| ADMINISTRATIVE| `null`  
Emergency Department Report| `67037fd377654984b8b368b47d0ab0e4`| CLINICAL| `null`  
External Medical Records| `b61d0a4ebf4316a1a3beea32bec88052`| CLINICAL| `null`  
Handicap Parking Permit| `649a852657357c20491856f4eb7a2690`| ADMINISTRATIVE| `null`  
Home Care Report| `d368eaa8f1b2419cb792bb7876bfac8a`| CLINICAL| `null`  
Hospital Discharge Summary| `6be998e1335a4d9689cae33ec7ed6968`| CLINICAL| `null`  
Hospital History & Physical| `d9060893790744589c5252ddb81b785e`| CLINICAL| `null`  
Imaging Report| `87041869c5954337b84fd10094fe5c0a`| CLINICAL| `ImagingReportTemplate`  
In-Office Testing| `372e7248ba944dbeab54712078c0ec44`| CLINICAL| `null`  
Insurance Card| `2551841bcfd34e1aa839cb1e3b7ef48f`| ADMINISTRATIVE| `null`  
Insurer Prior Authorization| `0394e7a3a5c847f495414e7511d12543`| ADMINISTRATIVE| `null`  
Lab Report| `f605e084dcad4beca16c0f62e6586d76`| CLINICAL| `LabReportTemplate`  
Medicaid Documents| `e02e0f6dc76d42aaa61384c85ca90830`| ADMINISTRATIVE| `null`  
Nursing Home| `fc14824cdc9fdcd1e2ce005aa3019d20`| CLINICAL| `null`  
Operative Report| `7f118206607248b7b13409e69c638eba`| CLINICAL| `null`  
POLST (Provider Order for Life Sustaining Treatment)| `cf72e522dd95fa1da1297cf3bf5e54e8`| ADMINISTRATIVE| `null`  
Patient Administrative Intake Form| `b25601a3e8ac543f5f2d7a85006de223`| ADMINISTRATIVE| `null`  
Patient Agreement| `2e16ccd7ad5a4bcf9d21dd51b4d16cb9`| ADMINISTRATIVE| `null`  
Patient Assistance| `ebd8c4f6f35b4c008e512d0e3c666e95`| ADMINISTRATIVE| `null`  
Patient Clinical Intake Form| `8c9ca86c76704d57a775cd6f48a02b6c`| CLINICAL| `null`  
Patient Consent| `7ce5a6eefedcff89a5a460f6be89d308`| ADMINISTRATIVE| `null`  
Physical Exams| `b1146b76cd2c4b488c964cf497fb1dce`| CLINICAL| `null`  
Power of Attorney| `1ff5f640868528e633a5d45f2142161e`| ADMINISTRATIVE| `null`  
Prescription Card| `0d002c5fe86c44b0a63c08e70e0df37c`| ADMINISTRATIVE| `null`  
Prescription Refill Request| `714a8229339b4af3989403a308bdcbfb`| CLINICAL| `null`  
Rehabilitation Report| `660f6fce32a64b3f9817f4bad3d56c79`| CLINICAL| `null`  
Release of Information Request| `2283372cb0fa4962a6fcff2eb3ca080b`| ADMINISTRATIVE| `null`  
Specialist Consult Report| `f0f1398f6f4640d29e4ff80d5481eb3f`| CLINICAL| `SpecialtyReportTemplate`  
Uncategorized Administrative Document| `7ebe754f4c3b860cf80d3aa9ebd8494c`| ADMINISTRATIVE| `null`  
Uncategorized Clinical Document| `52ef59487ecabc9cdd645c21c7a35458`| CLINICAL| `null`  
Worker's Compensation Documents| `54a06a3f06b48cbebf8dec88707272c3`| ADMINISTRATIVE| `null`  
###  Example 
The `DOCUMENT_RECEIVED` event context includes `available_document_types`, a list of every document type the instance supports — each entry carries the `key`, `name`, `report_type`, and `template_type` you'll need to construct a `CategorizeDocument` effect. The idiomatic pattern is to read from that list rather than hardcode catalog values, so a plugin keeps working as the catalog changes.
The handler below matches by `name` (using the Supported Document Types table above as a reference for what names to expect) and forwards the matched values to the effect. `ReportType` and `TemplateType` enum instances are constructed explicitly from the context's string values — the SDK rejects raw strings.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.data_integration import CategorizeDocument
    from canvas_sdk.effects.data_integration.types import ReportType, TemplateType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class CategorizeLabReports(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.DOCUMENT_RECEIVED)
        def compute(self) -> list[Effect]:
            available = self.event.context.get("available_document_types", [])
            lab_report = next((dt for dt in available if dt["name"] == "Lab Report"), None)
            if not lab_report:
                return []
            template_type = lab_report.get("template_type")
            return [
                CategorizeDocument(
                    document_id=self.event.target.id,
                    document_type={
                        "key": lab_report["key"],
                        "name": lab_report["name"],
                        "report_type": ReportType(lab_report["report_type"]),
                        "template_type": TemplateType(template_type) if template_type else None,
                    },
                    annotations=[
                        {"text": "AI Categorized", "color": "#4CAF50"},
                    ],
                ).apply()
            ]
    ```
For full end-to-end usage including discovery, error handling, and the other Data Integration effects in a single handler, see the [`data_integration_example` plugin](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/data_integration_example) in canvas-plugins.
##  Linking a Document to a Patient 
To link a document in the Data Integration queue to a patient, build a `LinkDocumentToPatient` and return its `apply()` from your handler. The plugin is responsible for matching the patient and supplying their id; Canvas does not search for matching patients itself.
###  Methods 
####  apply() → Effect 
Suggests the patient to link the document to.
  - `document_id` and `patient_key` are required.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`document_id`| `str`| The `id` of the [IntegrationTask](/sdk/data-integration-task/#integrationtask) document.| Yes  
`patient_key`| `str`| The `id` of the [Patient](/sdk/data-patient/#patient) to link the document to.| Yes  
`annotations`| `list`| List of annotations for display in the UI. See Annotations.| No  
An example of linking a document to a patient:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.data_integration import LinkDocumentToPatient
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.patient import Patient
    class LinkDocumentHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.DOCUMENT_RECEIVED)
        def compute(self) -> list[Effect]:
            document_id = self.event.target.id
            document_title = self.event.context.get("document", {}).get("title", "")
            # Plugin-specific matching logic — e.g., parse the document title or
            # call an OCR/LLM service to extract patient demographics, then look
            # up the patient via the SDK data module.
            patient = Patient.objects.filter(...).first()
            if not patient:
                return []
            return [
                LinkDocumentToPatient(
                    document_id=document_id,
                    patient_key=patient.id,
                    annotations=[
                        {"text": "AI 92%", "color": "#4CAF50"},
                        {"text": f"Matched from '{document_title}'", "color": "#2196F3"},
                    ],
                ).apply()
            ]
    ```
##  Marking a Document as Junk 
To mark a document in the Data Integration queue as junk (spam), build a `JunkDocument` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Marks the document as junk immediately.
  - `document_id` is required, and must be the id of an existing IntegrationTask in an early-stage state.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`document_id`| `str`| The `id` of the [IntegrationTask](/sdk/data-integration-task/#integrationtask) document to mark as junk.| Yes  
`JunkDocument` only works on IntegrationTasks in early-stage states: **Unread** , **Read** , **Error** , **Unread error** , or **Junk** (already). IntegrationTasks in **Processed** or **Reviewed** states cannot be junked — attempting to do so raises a validation error. The effect also validates that `document_id` resolves to an existing IntegrationTask and is a well-formed UUID; missing, malformed, or unknown IDs raise validation errors before the IntegrationTask is touched.
To avoid the validation error for tasks that have moved past the early-stage states, you can read the [`status`](/sdk/data-integration-task/#integrationtask) field from the SDK data module and preflight-check before emitting the effect.
An example that preflight-checks the IntegrationTask status before junking:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.data_integration import JunkDocument
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.integration_task import IntegrationTask, IntegrationTaskStatus
    class JunkDocumentHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.DOCUMENT_RECEIVED)
        def compute(self) -> list[Effect]:
            document_id = self.event.target.id
            task = IntegrationTask.objects.get(id=document_id)
            # Skip tasks that have already been processed or reviewed
            if task.status in (IntegrationTaskStatus.PROCESSED, IntegrationTaskStatus.REVIEWED):
                return []
            return [JunkDocument(document_id=document_id).apply()]
    ```
##  Prefilling Document Fields 
To pre-populate the parse-template fields on an IntegrationTask, build a `PrefillDocumentFields` and return its `apply()` from your handler. **Only three document types support field prefill** — those whose `template_type` is a known parse-template family:
Document type| `template_type`| SDK data module  
---|---|---  
Lab Report| `LabReportTemplate`| [`LabReportTemplate`](/sdk/data-lab-report-template/)  
Imaging Report| `ImagingReportTemplate`| [`ImagingReportTemplate`](/sdk/data-imaging-report-template/)  
Specialist Consult Report| `SpecialtyReportTemplate`| [`SpecialtyReportTemplate`](/sdk/data-specialty-report-template/)  
Document types with inline fields (Patient Consent, Power of Attorney, the Uncategorized variants, and the other ~30 entries in the Supported Document Types catalog) cannot have their fields prefilled by this effect.
###  Methods 
####  apply() → Effect 
Suggests values for the template fields.
  - `document_id` and at least one entry in `templates` are required.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`document_id`| `str`| The `id` of the [IntegrationTask](/sdk/data-integration-task/#integrationtask) document.| Yes  
`templates`| list[PrefillTemplate]| One or more templates to prefill. Must contain at least one entry.| Yes  
`annotations`| `list`| List of annotations for display in the UI. See Annotations.| No  
###  PrefillTemplate 
A `PrefillTemplate` is a dictionary with the following keys:
Key|  | Type| Description  
---|---|---|---  
`template_id`| required| int| The integer `dbid` of a `LabReportTemplate`, `ImagingReportTemplate`, or `SpecialtyReportTemplate` record. (Note: this is the integer primary key, not the `id` UUID.) Look this up via the SDK data module — see the example below.  
`template_name`| required| string| The matching template's `.name`.  
`fields`| required| dict[str, PrefillDocumentFieldData]| Map of field name to field data. Keys must match the `label` of a field on the chosen template — iterate `template.fields.all()` to discover the available labels, units, types, and required-ness.  
###  PrefillDocumentFieldData 
A `PrefillDocumentFieldData` is a dictionary with the following keys:
Key|  | Type| Description  
---|---|---|---  
`value`| required| string| The field value, stringified into the form field at render time. The same rules apply to all three template families (`LabReportTemplateField`, `ImagingReportTemplateField`, `SpecialtyReportTemplateField`). Currently supported are fields whose `type` is `"float"`, `"text"`, `"date"`, `"select"`, or `"radio"`. For `"select"` and `"radio"`, the value must exactly match one of the field's `options[*].key` for the dropdown to pre-select.  
`unit`| optional| string| Unit of measurement. Should match the corresponding template field's `units` (`LabReportTemplateField.units`, `ImagingReportTemplateField.units`, or `SpecialtyReportTemplateField.units`).  
`reference_range`| optional| string| Reference range for the value.  
`abnormal`| optional| bool| Whether the value is abnormal.  
`annotations`| optional| list| Per-field annotations. Same shape as Annotations.  
###  Discovering Available Fields 
Before constructing a `PrefillDocumentFields` payload, you can inspect the template to see what labels, units, types, and option keys it defines. The same approach works for `ImagingReportTemplate` and `SpecialtyReportTemplate`.
    ```python
    from canvas_sdk.v1.data import LabReportTemplate
    from logger import log
    def inspect_lab_template(template_name) -> None:
        template = (
            LabReportTemplate.objects
            .active()
            .filter(name=template_name)
            .first()
        )
        if not template:
            log.info(f"No template found with name {template_name}")
            return
        log.info(f"Template: {template.name} (dbid={template.dbid})")
        for field in template.fields.all().order_by("sequence"):
            log.info(
                f"  {field.label}",
                type=field.type,
                units=field.units,
                required=field.required,
                code=field.code,
                code_system=field.code_system,
            )
            for opt in field.options.all():
                log.info(f"    option", key=opt.key, label=opt.label)
    ```
Sample output for a CBC Panel template:
    ```text
    Template: CBC Panel (dbid=42)
      Hemoglobin   type=float  units=g/dL    required=True   code=718-7   code_system=LOINC
      WBC          type=float  units=10^3/uL required=True   code=6690-2  code_system=LOINC
      Differential type=select units=        required=False  code=        code_system=
        option key=NORMAL    label=Normal
        option key=ABNORMAL  label=Abnormal
    ```
With that you can see which labels go into the `fields` dict's keys, what `unit` value to send, and — for `select`/`radio` fields — which `option.key` values are valid for the `value` field.
###  Example 
An example of prefilling a Lab Report. The plugin looks up the CBC Panel template via the [`LabReportTemplate`](/sdk/data-lab-report-template/) SDK data module, then iterates the template's `fields` relation to discover which labels and units are available before filling in the values it extracted from the document.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.data_integration import PrefillDocumentFields
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import LabReportTemplate
    class PrefillLabReportHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.DOCUMENT_RECEIVED)
        def compute(self) -> list[Effect]:
            cbc = (
                LabReportTemplate.objects
                .active()
                .filter(name__icontains="CBC")
                .first()
            )
            if not cbc:
                return []
            # Values the plugin extracted from the document via OCR/LLM.
            # Hardcoded here for clarity.
            extracted = {
                "Hemoglobin": ("13.5", False),
                "WBC": ("11.2", True),
            }
            # Iterate the template's fields to discover which labels and units
            # the template defines, then fill in only the ones the plugin has
            # values for. Each field exposes `label`, `units`, `type`, and
            # `required` (see LabReportTemplateField).
            prefill_fields: dict[str, dict] = {}
            for field in cbc.fields.all():
                if field.label not in extracted:
                    continue
                value, abnormal = extracted[field.label]
                prefill_fields[field.label] = {
                    "value": value,
                    "unit": field.units or "",
                    "abnormal": abnormal,
                }
            return [
                PrefillDocumentFields(
                    document_id=self.event.target.id,
                    templates=[
                        {
                            "template_id": cbc.dbid,
                            "template_name": cbc.name,
                            "fields": prefill_fields,
                        },
                    ],
                    annotations=[
                        {"text": "Prefilled via AI", "color": "#FF9800"},
                    ],
                ).apply()
            ]
    ```
##  Removing a Document from a Patient 
To unlink a document from its currently-linked patient in the Data Integration queue, build a `RemoveDocumentFromPatient` and return its `apply()` from your handler. An IntegrationTask carries at most one patient link at a time, so this effect simply clears that link.
###  Methods 
####  apply() → Effect 
Clears the document's patient link immediately.
  - `document_id` is required.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`document_id`| `str`| The `id` of the [IntegrationTask](/sdk/data-integration-task/#integrationtask) document to unlink from its patient.| Yes  
`patient_id`| `str`| The id of the [patient](/sdk/data-patient/) the document is linked to. Recorded in the log for auditing; the link is cleared whatever its value.| No  
An example of unlinking a document from its patient:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.data_integration import RemoveDocumentFromPatient
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class RemoveDocumentHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.DOCUMENT_LINKED_TO_PATIENT)
        def compute(self) -> list[Effect]:
            return [
                RemoveDocumentFromPatient(
                    document_id=self.event.target.id,
                ).apply()
            ]
    ```
##  Annotations 
The `annotations` field on any data integration effect accepts a list of dictionaries with the following keys:
Key| Type| Description  
---|---|---  
`text`| string| The annotation text to display (e.g., "AI 95%").  
`color`| string| Hex color code (e.g., "#4CAF50" for green).  

---

# EventValidationError Effect

Source: https://docs.canvasmedical.com/sdk/effect-event-validation-error/

##  Overview 
The `EventValidationError` effect is used to block the creation of an event (such as a NoteStateChangeEvent create) when custom validation fails. If this effect is returned by a protocol in response to an event (e.g., `NOTE_STATE_CHANGE_EVENT_PRE_CREATE`), the event is aborted and the provided error message is surfaced to the user.
Build an `EventValidationError`, add one or more errors with `add_error()`, and return its `apply()` from your handler.
##  Methods 
###  add_error(message: str | ValidationError) → EventValidationError 
Adds a validation error to the effect, either as a message string or a `ValidationError`. It returns the effect, so calls can be chained.
###  apply() → Effect 
Blocks the event and shows the errors to the user.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
errors| list[ValidationError]| List of validation errors to display to the user.| Yes  
###  ValidationError dataclass 
Each item in the `errors` list is a `ValidationError` dataclass with the following fields:
Field| Type| Description  
---|---|---  
message| string| The error message to display to the user.  
##  Example Usage 
Return an `EventValidationError` from your protocol's `compute` method to block the event and show a message to the user. You can also return other effects alongside `EventValidationError`.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Note
    from canvas_sdk.v1.data.coverage import CoverageStack
    from canvas_sdk.effects.validation import EventValidationError, ValidationError
    from canvas_sdk.effects.banner_alert import AddBannerAlert, RemoveBannerAlert
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_PRE_CREATE)
        def handle_no_coverage(self, patient_id: str, note: Note) -> list[Effect]:
            """If the patient has no coverage, add banner alert and do not allow notes to be locked or charges pushed."""
            if note.patient.coverages.filter(stack=CoverageStack.IN_USE).count() == 0:
                return [
                    EventValidationError(
                        errors=[
                            ValidationError(
                                message="Patient has no coverage. Do not send claim to billing department until coverage(s) have been added."
                            )
                        ]
                    ).apply(),
                    AddBannerAlert(
                        patient_id=patient_id,
                        key="no_coverage",
                        narrative="Patient has no documented coverages.",
                        placement=[
                            AddBannerAlert.Placement.CHART,
                            AddBannerAlert.Placement.APPOINTMENT_CARD,
                        ],
                        intent=AddBannerAlert.Intent.ALERT,
                    ).apply(),
                ]
            return [RemoveBannerAlert(patient_id=patient_id, key="no_coverage").apply()]
        def handle_no_billing_line_items(self, note: Note) -> Effect | None:
            """If the note has no billing line items, do not allow notes to be locked or charges pushed."""
            if note.billing_line_items.filter(status="active").count() > 0:
                return None
            val_effect = EventValidationError()
            val_effect.add_error(
                "Cannot lock or push charges for a note with no billing line items."
            )
            return val_effect.apply()
        def compute(self) -> list[Effect]:
            state = self.event.context["state"]
            if state not in ["PSH", "LKD"]:
                return []
            note = Note.objects.get(id=self.event.context["note_id"])
            patient_id = str(note.patient.id)
            effects = self.handle_no_coverage(patient_id=patient_id, note=note)
            if v := self.handle_no_billing_line_items(note=note):
                effects.append(v)
            return effects
    ```
##  Supported Events 
Event| Behavior  
---|---  
[`NOTE_STATE_CHANGE_EVENT_PRE_CREATE`](/sdk/events/#notes)| Blocks the note state change (e.g. lock, push charges) and displays errors in the UI.  
[`APPOINTMENT__FORM__UPDATED`](/sdk/events/#appointments)| Disables the Book button on the appointment scheduling modal and displays errors as a tooltip.  
##  Implementation Details 
  - If an `EventValidationError` is returned, the event is aborted and the error message is shown in the UI (if initiated from the UI).
  - This effect is typically used for pre-create validation of events, such as note state changes or appointment scheduling.
  - Any other effects returned alongside an `EventValidationError` are still applied, even though the event itself is blocked. In the example above, the `AddBannerAlert` effect is added and persists even when the note state change is rejected.

---

# External Event Effect

Source: https://docs.canvasmedical.com/sdk/effect-external-event/

The `ExternalEvent` effect provides a way to create and update external clinical events within the Canvas platform. External events represent clinical encounters from external data sources such as ADT (Admission, Discharge, Transfer) feeds, enabling tracking of patient visits that occur outside of Canvas.
Build an `ExternalEvent` with the attributes you want to set, then return one of its two methods from your handler: `create()` for a new external event, or `update()` for an existing one.
##  Methods 
###  create() → Effect 
Creates an external event.
  - `patient_id`, `visit_identifier`, `message_control_id`, and `event_type` are required.
  - `external_event_id` must not be set.
###  update() → Effect 
Updates an existing external event.
  - `external_event_id` is required, and must be the id of an existing external event.
  - Only the attributes you set on the effect are changed. Attributes you leave unset keep their current values.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`external_event_id`| `str` or `UUID` or `None`| Unique identifier of an existing external event. Must be unset when creating.| For `update()`  
`patient_id`| `str` or `None`| ID of the patient for this event.| For `create()`  
`visit_identifier`| `str` or `None`| Identifier for the visit/encounter.| For `create()`  
`message_control_id`| `str` or `None`| Unique identifier for the message (e.g., HL7 message control ID).| For `create()`  
`event_type`| `str` or `None`| Type of event (e.g., "ADT^A01" for admission).| For `create()`  
`event_datetime`| `datetime` or `None`| Date and time when the event occurred.| No  
`event_cancelation_datetime`| `datetime` or `None`| Date and time when the event was cancelled. Set this to mark an event as cancelled.| No  
`message_datetime`| `datetime` or `None`| Date and time when the message was sent.| No  
`information_source`| `str` or `None`| Source of the event information (e.g., hospital name, system name).| No  
`facility_name`| `str` or `None`| Name of the facility where the event occurred.| No  
`raw_message`| `str` or `None`| Raw message content (e.g., original HL7 message).| No  
##  Validation & Errors 
Before any effect is emitted, the model runs these checks:
###  Create Validation 
  - **external_event_id** must **not** be set (will be generated by the system)
  - **patient_id** is **required**
  - **visit_identifier** is **required**
  - **message_control_id** is **required**
  - **event_type** is **required**
###  Update Validation 
  - **external_event_id** is **required** and must reference an existing external event
  - All other fields are optional; only dirty (modified) fields are updated
##  Example Usage 
    ```python
    from datetime import datetime
    from canvas_sdk.effects.external_event import ExternalEvent
    from canvas_sdk.v1.data.external_event import ExternalEvent as ExternalEventModel
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.first()
    ```
###  Create an Admission Event 
    ```python
    # Create an external event for a hospital admission
    admission_event = ExternalEvent(
        patient_id=str(patient.id),
        visit_identifier="VISIT-2024-001234",
        message_control_id="MSG-20240115-143052",
        event_type="ADT^A01",  # Admission
        event_datetime=datetime.now(),
        message_datetime=datetime.now(),
        information_source="General Hospital ADT Feed",
        facility_name="General Hospital - Main Campus",
        raw_message="MSH|^~\&|HOSPITAL|FAC|CANVAS|...",
    )
    effect_create = admission_event.create()
    ```
###  Create a Discharge Event 
    ```python
    # Create an external event for a discharge
    discharge_event = ExternalEvent(
        patient_id=str(patient.id),
        visit_identifier="VISIT-2024-001234",  # Same visit as admission
        message_control_id="MSG-20240118-091530",
        event_type="ADT^A03",  # Discharge
        event_datetime=datetime.now(),
        message_datetime=datetime.now(),
        information_source="General Hospital ADT Feed",
        facility_name="General Hospital - Main Campus",
    )
    effect_discharge = discharge_event.create()
    ```
###  Cancel an Existing Event 
    ```python
    # Find an existing external event to cancel
    existing_event = ExternalEventModel.objects.filter(
        patient__id=patient.id,
        event_cancelation_datetime__isnull=True,  # Not already cancelled
    ).first()
    if existing_event:
        # Cancel the event by setting the cancelation datetime
        cancel_effect = ExternalEvent(
            external_event_id=str(existing_event.id),
            event_cancelation_datetime=datetime.now(),
        )
        effect_cancel = cancel_effect.update()
    ```
###  Update Event Details 
    ```python
    # Update an existing external event with additional information
    existing_event = ExternalEventModel.objects.filter(patient__id=patient.id).first()
    if existing_event:
        updated_event = ExternalEvent(
            external_event_id=str(existing_event.id),
            facility_name="General Hospital - West Wing (Corrected)",
            raw_message="MSH|^~\&|HOSPITAL|FAC|CANVAS|...|CORRECTED",
        )
        effect_update = updated_event.update()
    ```
###  Create Event with All Fields 
    ```python
    # Create an external event with all optional fields populated
    complete_event = ExternalEvent(
        # Required fields
        patient_id=str(patient.id),
        visit_identifier="VISIT-2024-005678",
        message_control_id="MSG-20240120-163045",
        event_type="ADT^A01",
        # Optional datetime fields
        event_datetime=datetime(2024, 1, 20, 16, 30, 0),
        message_datetime=datetime(2024, 1, 20, 16, 30, 45),
        # Optional string fields
        information_source="Regional Medical Center - HL7 Interface",
        facility_name="Regional Medical Center - Emergency Department",
        raw_message="MSH|^~\&|RMC|ED|CANVAS|RECV|20240120163045||ADT^A01|MSG123|P|2.5",
    )
    effect_complete = complete_event.create()
    ```
##  Common Event Types 
The `event_type` field typically contains HL7 ADT event codes:
Event Type| Description  
---|---  
ADT^A01| Admit/Visit Notification  
ADT^A02| Transfer a Patient  
ADT^A03| Discharge/End Visit  
ADT^A04| Register a Patient  
ADT^A08| Update Patient Information  
ADT^A11| Cancel Admit/Visit Notification  
ADT^A12| Cancel Transfer  
ADT^A13| Cancel Discharge/End Visit  

---

# Fax Effects

Source: https://docs.canvasmedical.com/sdk/effect-fax/

The Canvas SDK includes effects to fax a note, or to fax a referral, imaging order, lab order or letter without the rest of its note. The recipient gets the same PDF that the document's own **Fax** action sends from Canvas.
Effect| Sends| Recipient when you don't name one  
---|---|---  
`FaxNoteEffect`| The note| None. A recipient is required.  
`FaxReferralEffect`| The referral and its attachments, plus the visit note when the referral includes it| The referral's service provider, when it has a fax number  
`FaxImagingOrderEffect`| The imaging order| The order's imaging center, when it has a fax number  
`FaxLabOrderEffect`| The lab order's requisition form| None. A recipient is required.  
`FaxLetterEffect`| The letter and its attachments| None. A recipient is required.  
##  Fax a Note 
To fax a note, build a `FaxNoteEffect` and return its `apply()` from your handler. This effect is also documented under [Fax Note](/sdk/effect-notes/#fax-note) on the Note Effects page.
###  Methods 
####  apply() → Effect 
Faxes the note.
  - Validates that the note exists.
  - If `include_coversheet` is `True`, `subject`, `comment` and `location_id` become required, and the practice location must exist.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`note_id`| `UUID` or `str`| Identifier of the note to fax.| Yes  
`recipient_name`| `str`| Name of the fax recipient.| Yes  
`recipient_fax_number`| `str`| Fax number of the recipient, including the country code.| Yes  
`include_coversheet`| `bool`| Whether to include a coversheet with the fax.| No  
`subject`| `str` or `None`| Subject line for the coversheet (required if coversheet used).| No  
`comment`| `str` or `None`| Additional comments for the coversheet (required if coversheet used).| No  
`location_id`| `UUID` or `str` or `None`| Practice location ID (required if coversheet used).| No  
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.fax import FaxNoteEffect
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self) -> list[Effect]:
            fax_effect = FaxNoteEffect(
                note_id="existing-note-uuid",
                recipient_name="Dr. Jane Smith",
                recipient_fax_number="15551234567",
                include_coversheet=True,
                subject="Patient Referral - Follow-up Care",
                comment="Please review attached consultation notes for continuing care.",
                location_id="practice-location-uuid",
            )
            return [fax_effect.apply()]
    ```
##  Fax a Referral 
To fax a referral, build a `FaxReferralEffect` and return its `apply()` from your handler. The fax includes the referral's attachments, and the visit note when the referral includes it.
###  Methods 
####  apply() → Effect 
Faxes the referral.
  - Validates that the referral exists. It must be committed and not entered in error, as for its own **Fax** action in Canvas.
  - Leave out both `recipient_name` and `recipient_fax_number` to fax the referral's service provider. Nothing is faxed if you give only one, if the referral has no service provider, or if the service provider has no fax number.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`referral_id`| `UUID` or `str`| Identifier of the referral to fax.| Yes  
`recipient_name`| `str` or `None`| Name of the fax recipient. Give it together with `recipient_fax_number`.| No  
`recipient_fax_number`| `str` or `None`| Fax number of the recipient, including the country code. Give it together with `recipient_name`.| No  
`include_coversheet`| `bool`| Whether to include a coversheet with the fax.| No  
`subject`| `str` or `None`| Subject line for the coversheet (required if coversheet used).| No  
`comment`| `str` or `None`| Additional comments for the coversheet (required if coversheet used).| No  
`location_id`| `UUID` or `str` or `None`| Practice location ID (required if coversheet used).| No  
###  Example 
Fax each referral to its service provider when its Refer command is committed:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.fax import FaxReferralEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data import Command
    class FaxReferralOnCommit(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.REFER_COMMAND__POST_COMMIT)
        def compute(self) -> list[Effect]:
            referral = Command.objects.get(id=self.event.target.id).anchor_object
            if referral is None:
                return []
            return [FaxReferralEffect(referral_id=referral.id).apply()]
    ```
##  Fax an Imaging Order 
To fax an imaging order, build a `FaxImagingOrderEffect` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Faxes the imaging order.
  - Validates that the imaging order exists. It must be committed and not entered in error, as for its own **Fax** action in Canvas.
  - Leave out both `recipient_name` and `recipient_fax_number` to fax the order's imaging center. Nothing is faxed if you give only one, if the order has no imaging center, or if the imaging center has no fax number.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`imaging_order_id`| `UUID` or `str`| Identifier of the imaging order to fax.| Yes  
`recipient_name`| `str` or `None`| Name of the fax recipient. Give it together with `recipient_fax_number`.| No  
`recipient_fax_number`| `str` or `None`| Fax number of the recipient, including the country code. Give it together with `recipient_name`.| No  
`include_coversheet`| `bool`| Whether to include a coversheet with the fax.| No  
`subject`| `str` or `None`| Subject line for the coversheet (required if coversheet used).| No  
`comment`| `str` or `None`| Additional comments for the coversheet (required if coversheet used).| No  
`location_id`| `UUID` or `str` or `None`| Practice location ID (required if coversheet used).| No  
###  Example 
Fax an imaging order to its imaging center:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.fax import FaxImagingOrderEffect
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self) -> list[Effect]:
            return [FaxImagingOrderEffect(imaging_order_id="existing-imaging-order-uuid").apply()]
    ```
##  Fax a Lab Order 
To fax a lab order's requisition form, build a `FaxLabOrderEffect` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Faxes the lab order's requisition form.
  - Validates that the lab order exists. It must be committed and not entered in error, as for its own **Fax** action in Canvas.
  - `recipient_name` and `recipient_fax_number` are required, because a lab order has no recipient on file.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`lab_order_id`| `UUID` or `str`| Identifier of the lab order to fax.| Yes  
`recipient_name`| `str`| Name of the fax recipient.| Yes  
`recipient_fax_number`| `str`| Fax number of the recipient, including the country code.| Yes  
`include_coversheet`| `bool`| Whether to include a coversheet with the fax.| No  
`subject`| `str` or `None`| Subject line for the coversheet (required if coversheet used).| No  
`comment`| `str` or `None`| Additional comments for the coversheet (required if coversheet used).| No  
`location_id`| `UUID` or `str` or `None`| Practice location ID (required if coversheet used).| No  
###  Example 
Fax a lab order's requisition form to the lab, with a coversheet:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.fax import FaxLabOrderEffect
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self) -> list[Effect]:
            fax_effect = FaxLabOrderEffect(
                lab_order_id="existing-lab-order-uuid",
                recipient_name="Acme Labs",
                recipient_fax_number="15555550100",
                include_coversheet=True,
                subject="Lab requisition",
                comment="Requisition for the attached lab order.",
                location_id="practice-location-uuid",
            )
            return [fax_effect.apply()]
    ```
##  Fax a Letter 
To fax a letter, build a `FaxLetterEffect` and return its `apply()` from your handler. The fax includes the letter's attachments.
###  Methods 
####  apply() → Effect 
Faxes the letter.
  - Validates that the letter exists.
  - `recipient_name` and `recipient_fax_number` are required.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`letter_id`| `UUID` or `str`| Identifier of the letter to fax.| Yes  
`recipient_name`| `str`| Name of the fax recipient.| Yes  
`recipient_fax_number`| `str`| Fax number of the recipient, including the country code.| Yes  
`include_coversheet`| `bool`| Whether to include a coversheet with the fax.| No  
`subject`| `str` or `None`| Subject line for the coversheet (required if coversheet used).| No  
`comment`| `str` or `None`| Additional comments for the coversheet (required if coversheet used).| No  
`location_id`| `UUID` or `str` or `None`| Practice location ID (required if coversheet used).| No  
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.fax import FaxLetterEffect
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self) -> list[Effect]:
            fax_effect = FaxLetterEffect(
                letter_id="existing-letter-uuid",
                recipient_name="Dr. Jane Smith",
                recipient_fax_number="15551234567",
            )
            return [fax_effect.apply()]
    ```
##  Fax history 
Each fax is recorded on its document with Canvas Bot as its `originator`, and appears in the document's fax history in Canvas. `delivered_by_fax` is updated when the faxing service reports the outcome. See [Faxes sent by a plugin](/sdk/data-fax/#faxes-sent-by-a-plugin).
Effect| Recorded as  
---|---  
`FaxNoteEffect`| [NoteActionEvent](/sdk/data-fax/#noteactionevent), read through `note.action_events`  
`FaxReferralEffect`| [ReferralActionEvent](/sdk/data-fax/#referralactionevent)  
`FaxImagingOrderEffect`| [ImagingOrderActionEvent](/sdk/data-fax/#imagingorderactionevent)  
`FaxLabOrderEffect`| [LabOrderActionEvent](/sdk/data-fax/#laborderactionevent)  
`FaxLetterEffect`| [LetterActionEvent](/sdk/data-letter-action-event/)

---

# HTTP Request

Source: https://docs.canvasmedical.com/sdk/effect-http-request/

The `HttpRequestEffect` lets a plugin ask the Canvas platform to issue an HTTP request on its behalf. The plugin returns the effect from a handler and the platform performs the call.
We recommend running the request asynchronously by chaining `.set_async(...)` onto the applied effect. The request is then handed off to the platform's async runner, which manages delay, retries, and backoff so the handler doesn't block on the network. Setting `retry_on_status_codes` automatically opts into async execution (equivalent to `.set_async(delay_seconds=0)`), so you only need to call `.set_async(...)` explicitly to add a delay or set `max_retries`.
Without `.set_async(...)` and without `retry_on_status_codes`, the effect is executed inline.
Build an `HttpRequestEffect` and return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Sends the HTTP request.
  - `url` is required.
  - `method` defaults to `GET`.
##  Attributes 
Name| Type| Description| Required  
---|---|---|---  
`url`| `str`| The URL to request. Must be non-empty. Cannot resolve to a private or loopback address (see Security).| Yes  
`method`| `HttpMethod`| The HTTP method to use. Defaults to `HttpMethod.GET`.| No  
`headers`| `dict[str, str]` or `None`| Request headers. Header values are transmitted as-is — store credentials in the plugin's [`secrets`](/sdk/secrets/) and reference them here rather than hard-coding them.| No  
`body`| `str` or `None`| The request body, as a string. For JSON payloads, serialize with `json.dumps(...)` and set the appropriate `Content-Type` header.| No  
`retry_on_status_codes`| `list[int]` or `None`| HTTP status codes that should trigger a retry. Each value must be in the range `100`–`599`. Setting this automatically routes the request through the async runner (equivalent to `.set_async(delay_seconds=0)`); use `.set_async(...)` only to override the delay or set `max_retries`.| No  
##  `HttpMethod`
A `StrEnum` of the supported HTTP methods. You can also pass the string value as well.
Member| Value  
---|---  
`HttpMethod.GET`| `"GET"`  
`HttpMethod.POST`| `"POST"`  
`HttpMethod.PUT`| `"PUT"`  
`HttpMethod.PATCH`| `"PATCH"`  
`HttpMethod.DELETE`| `"DELETE"`  
##  Security & Network Behavior 
The platform applies several safeguards before executing the request:
  - **SSRF protection.** The host is resolved and rejected if it points at a private (RFC 1918), loopback, link-local (including the `169.254.169.254` cloud metadata address), multicast, reserved, or unspecified address. Both literal IPs (e.g. `http://10.0.0.1/`) and hostnames that resolve to such addresses are blocked.
  - **Redirect behavior.** GET requests follow redirects normally. Non-GET methods (POST, PUT, PATCH, DELETE) are made with `allow_redirects=False`, so a `3xx` response is returned as-is rather than re-posting data to a different host.
  - **Request timeout.** Each request has a 30-second timeout. Requests that exceed it are aborted.
  - **Connection errors are swallowed.** If the upstream service is unreachable or the request fails at the transport layer, the failure is logged and the effect pipeline continues — it does not raise back into your handler.
  - **Redacted logging.** The platform logs the request method, host, path, and final status code. Query strings, fragments, request headers, request bodies, and response bodies are never logged, so credentials passed via query string or `Authorization` headers do not leak into platform logs.
##  Async Execution 
Chain `.set_async(...)` onto the result of `.apply()` to have the platform schedule the request through its async runner instead of running it inline with the handler. You can read more about async effect execution [here](/sdk/effects/#async-execution).
When `retry_on_status_codes` is set on the effect, the SDK automatically sets `delay_seconds=0` (async-now) so the request is routed through the async runner — you don't need to call `.set_async()` separately just for retries. The async runner uses `retry_on_status_codes` (in combination with `max_retries`) to decide whether a response should trigger a retry.
##  Handling Credentials 
Header values are transmitted to the upstream service exactly as provided. Do not hard-code API tokens or other credentials into your plugin source. Instead, declare them as [secrets](/sdk/secrets/) in `CANVAS_MANIFEST.json` and read them at runtime via `self.secrets` on the handler.
##  Example Usage 
###  Send a POST request asynchronously 
    ```python
    import json
    from canvas_sdk.events import EventType
    from canvas_sdk.effects.http_request import HttpMethod, HttpRequestEffect
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CREATED)
        def compute(self):
            http_effect = HttpRequestEffect(
                url="https://api.example.com/submit",
                method=HttpMethod.POST,
                headers={
                    "Authorization": f"Bearer {self.secrets['MY_API_TOKEN']}",
                    "Content-Type": "application/json",
                },
                body=json.dumps({"patient_id": self.target}),
                retry_on_status_codes=[500, 502, 503],
            )
            # retry_on_status_codes already implies async-now; .set_async() is here to add max_retries
            return [http_effect.apply().set_async(max_retries=3)]
    ```
###  Issue a simple GET request 
    ```python
    http_effect = HttpRequestEffect(
        url="https://api.example.com/status",
    )
    return [http_effect.apply().set_async(delay_seconds=0)]
    ```
###  Schedule a delayed request 
    ```python
    # Run the request 60 seconds from now
    http_effect = HttpRequestEffect(
        url="https://api.example.com/sync",
        method=HttpMethod.PUT,
        body=json.dumps({"status": "ready"}),
        headers={"Content-Type": "application/json"},
    )
    return [http_effect.apply().set_async(delay_seconds=60)]
    ```
##  Validation 
Construction is validated by Pydantic and will raise a `ValidationError` for:
  - An empty `url`.
  - A `method` that is not a member of `HttpMethod`.
  - A `retry_on_status_codes` entry that is not an integer or falls outside the `100`–`599` range.

---

# Lab Report Effect

Source: https://docs.canvasmedical.com/sdk/effect-lab-report/

The `LabReport` effect lets plugins manage a lab report's full lifecycle, independently of any lab order. It is designed for workflows where a report exists before its structured results do — for example, a scanned report that arrives by fax or upload and is OCR'd asynchronously, so the lab tests and values aren't ready until hours or days after the report is created.
With these effects a plugin can:
  - **Create** a report up front, with no order, no PDF, and no results.
  - **Attach results** (lab tests and values) to that report later, as they become available.
  - **Update** report metadata, such as its name.
  - **Enter-in-error** a report so a user can self-correct a mistake.
A created report is linked to the patient you supply. It starts **empty** — until you attach results it holds no tests or values, and it stays an **uncommitted draft**. A results-less draft does **not** appear in the patient's lab reports in the chart (that view only shows committed reports); it exists but isn't surfaced there yet. The first `attach_results()` commits the report — that's when it fills in, creates the observations behind its values, and appears in the chart, reading like any other lab report. It is **not** a Data Integration document, so it never appears in the Data Integration queue, and Canvas creates the report's diagnostic report and renders a document from its data automatically.
##  Identifying a report 
Every effect references a report by one of two handles:
Handle| What it is| When to use it  
---|---|---  
`reference_id`| A stable identifier your plugin assigns when it creates a report.| The report your plugin created. Required on `create()`.  
`report_id`| The [LabReport](/sdk/data-labs/)'s `id`.| Any report — including ones your plugin didn't create.  
Effects are fire-and-forget, so `create()` does not return the new report's `report_id`. Use the `reference_id` you assigned as your handle for the later `attach`/`update`/`enter_in_error` calls. If you need the `report_id` (for example to act on a report your plugin did not create), read it from the `LAB_REPORT_CREATED` event or query the [LabReport](/sdk/data-labs/) data model by `reference_id` (the handle you assigned is stored there; the data model's own `external_id` is reserved for electronic/Health-Gorilla feed ids).
Namespace your `reference_id` values (e.g. `"my-plugin:batch-2026-06-17:img-44"`) so they don't collide with report ids from other inbound-lab sources.
Build a `LabReport` and return one of its methods from your handler: `create()`, `update()`, `enter_in_error()`, or `attach_results()`.
##  Methods 
###  create() → Effect 
Create a lab report decoupled from its results — no order, no PDF, and no values required.
####  Validation 
  - `reference_id` is **required** (it is your handle for attaching results later).
  - `patient_id` is **required**.
  - `report_id` must **not** be set (creation assigns the id).
  - The `reference_id` must not already be in use by an existing report.
####  Example 
    ```python
    import datetime
    from canvas_sdk.effects.lab_report import LabReport
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.first()
    report = LabReport(
        reference_id="my-plugin:batch-2026-06-17:img-44",
        patient_id=patient.id,
        report_name="CBC (scanned 2026-06-17)",
        date_performed=datetime.datetime.now(),
    )
    effect = report.create()
    ```
###  update() → Effect 
Update report metadata, such as renaming it via `report_name`. Only the fields you set are sent. Only `report_name` and `date_performed` can be changed — `update()` **cannot move the report to a different patient** ; the patient is fixed when the report is created. If a report was attached to the wrong patient, enter it in error and recreate it on the correct patient.
####  Validation 
  - Exactly one handle (`reference_id` or `report_id`) is **required**.
  - At least one mutable field (`report_name` or `date_performed`) must be provided.
  - The report must not already be entered-in-error or reviewed by a provider.
####  Example 
    ```python
    from canvas_sdk.effects.lab_report import LabReport
    renamed = LabReport(
        reference_id="my-plugin:batch-2026-06-17:img-44",
        report_name="Complete Blood Count",
    )
    effect = renamed.update()
    ```
###  enter_in_error() → Effect 
Flag a report as entered-in-error — use it when a report was filed incorrectly. It junks the report (removing it from active views) and records who entered it in error. The report's observations and its linked DiagnosticReport and DocumentReference records are marked entered-in-error as well. Once a report is entered-in-error (or junked) it can no longer be modified — `update()` and `attach_results()` on it raise a validation error.
####  Validation 
  - A handle (`reference_id` or `report_id`) is **required**.
  - Any other field is ignored (not rejected).
  - The report must not already be entered-in-error or reviewed by a provider.
####  Example 
    ```python
    from canvas_sdk.effects.lab_report import LabReport
    voided = LabReport(reference_id="my-plugin:batch-2026-06-17:img-44")
    effect = voided.enter_in_error()
    ```
###  attach_results() → Effect 
Adds lab tests and values to an existing report. See Attaching results for its arguments and an example.
##  Attributes 
Name| Type| Description| Required  
---|---|---|---  
`reference_id`| `str` or `None`| The plugin-assigned handle (maximum 40 characters). **Required** when creating; usable as the handle for other operations.| For `create()`; for `update()` and `enter_in_error()`, this or `report_id`  
`report_id`| `UUID` or `None`| The [LabReport](/sdk/data-labs/)'s `id` (a valid uuid string is also accepted). Must be **unset** when creating; an alternative handle otherwise.| For `update()` and `enter_in_error()`, this or `reference_id`  
`patient_id`| `str` or `None`| The [Patient](/sdk/data-patient/)'s `id`. **Required** when creating.| For `create()`  
`report_name`| `str` or `None`| Human-readable report name (maps to the report's document name).| No  
`date_performed`| `datetime` or `None`| The report's effective/displayed date. If omitted on `create`, it defaults to the creation time — correct it later via `update`.| No  
##  Attaching results 
Once results are available, attach them with the `attach_results` method on `LabReport`. The report handle comes from the `LabReport` instance (`report_id` or `reference_id`); the method takes a list of `LabTest`s, each grouping the `LabValue`s measured for it — so the values for one test are bundled under that test in the chart. Attaching is **additive** : it appends tests and values without removing any already on the report, and Canvas creates an observation for each value automatically.
Attaching results saves the report and regenerates its linked DiagnosticReport and rendered DocumentReference (the report's document) to reflect the newly attached values. The first `attach_results()` call also commits the report (a never-populated report stays an uncommitted draft). A committed report enters the lab-review workflow **review-required** and **requiring a signature** , but with **no reviewer assigned** — a clinician still has to pick it up, review, and sign it. Once a provider has reviewed it, the report is locked to further SDK edits.
###  Arguments 
Name| Type| Description  
---|---|---  
`lab_tests`| list[`LabTest`]| The tests to attach. At least one is required. The report handle comes from the `LabReport` instance.  
###  `LabTest`
A `LabTest` is a test that was performed — an ordered panel or a single analyte — and it groups its result values (a result test can carry many values). `ontology_test_code`/`ontology_test_name` are the lab's **order/compendium** code and name — _not_ LOINC. LOINC is supplied separately via `codings` (see `CodingData` below).
Name| Type| Description  
---|---|---  
`ontology_test_code`| `str`| The lab's order/compendium code for the test. Defaults to empty string.  
`ontology_test_name`| `str`| Human-readable test name. Defaults to empty string.  
`codings`| list[`CodingData`] or `None`| The test's LOINC coding(s); only LOINC-system codings are stored.  
`values`| list[`LabValue`]| The result values for this test. **At least one is required.**  
###  `LabValue`
Each `LabValue` is one measured result on its test.
Name| Type| Description  
---|---|---  
`value`| `str`| The result value. Required.  
`units`| `str`| Unit of measure (e.g. `"g/dL"`). Defaults to empty string.  
`reference_range`| `str`| Reference range as free text. Defaults to empty string.  
`abnormal_flag`| `AbnormalFlag` or `None`| Flags the value against its reference range. Any non-empty flag marks the result abnormal in the lab report. Defaults to `None`.  
`observation_status`| `ObservationStatus`| Status of the observation. Defaults to `ObservationStatus.FINAL`.  
`comment`| `str`| Free-text comment. Defaults to empty string.  
`codings`| list[`CodingData`] or `None`| The value's LOINC coding(s); only LOINC-system codings are stored.  
###  `CodingData`
A coding attached to a test or a value, reused from the [`Observation`](/sdk/effect-observation/) effect. Only codings whose `system` is `http://loinc.org` are persisted, and the `display` becomes the stored coding name.
Name| Type| Description  
---|---|---  
`code`| `str`| The LOINC code (e.g. `"718-7"`). Required.  
`display`| `str`| Human-readable display; stored as the coding's name.  
`system`| `str`| Coding system URI. Use `"http://loinc.org"`.  
`version`| `str`| Optional coding-system version. Defaults to empty.  
`user_selected`| `bool`| Whether a user selected this coding. Defaults to `False`.  
###  `AbnormalFlag`
A `StrEnum` of abnormal-result flags (HL7 v2 table 0078) for a `LabValue`. Setting any of these marks the result abnormal on the lab report.
Member| Value  
---|---  
`HIGH`| `H`  
`LOW`| `L`  
`CRITICAL_HIGH`| `HH`  
`CRITICAL_LOW`| `LL`  
`BELOW_ABSOLUTE_LOW`| `<`  
`ABOVE_ABSOLUTE_HIGH`| `>`  
`ABNORMAL`| `A`  
`CRITICAL_ABNORMAL`| `AA`  
`SUSCEPTIBLE`| `S`  
`RESISTANT`| `R`  
`INTERMEDIATE`| `I`  
`NEGATIVE`| `NEG`  
`POSITIVE`| `POS`  
###  `ObservationStatus`
A `StrEnum` of statuses for a `LabValue`'s observation. Defaults to `FINAL`.
Member| Value  
---|---  
`FINAL`| `final`  
`PRELIMINARY`| `preliminary`  
`AMENDED`| `amended`  
`CORRECTED`| `corrected`  
`CANCELLED`| `cancelled`  
`REGISTERED`| `registered`  
`ENTERED_IN_ERROR`| `entered-in-error`  
`UNKNOWN`| `unknown`  
####  Validation 
  - Exactly one of `reference_id` or `report_id` is **required**.
  - At least one `LabTest` is **required** , and each `LabTest` requires at least one `LabValue`.
  - The report must exist and must not be entered-in-error or reviewed by a provider.
####  Example 
A SimpleAPI route an OCR service calls once it has abstracted the values:
    ```python
    from canvas_sdk.effects.lab_report import LabReport, LabTest, LabValue
    from canvas_sdk.effects.observation import CodingData
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPIRoute
    LOINC = "http://loinc.org"
    class LabResultsAPI(APIKeyAuthMixin, SimpleAPIRoute):
        PATH = "/lab-results"
        def post(self) -> list[Response]:
            body = self.request.json()
            return [
                LabReport(reference_id=body["reference_id"]).attach_results(
                    [
                        LabTest(
                            ontology_test_code=test.get("order_code", ""),
                            ontology_test_name=test.get("name", ""),
                            codings=(
                                [CodingData(code=test["loinc"], display=test.get("name", ""), system=LOINC)]
                                if test.get("loinc")
                                else None
                            ),
                            values=[
                                LabValue(
                                    value=value["value"],
                                    units=value.get("units", ""),
                                    reference_range=value.get("reference_range", ""),
                                    codings=(
                                        [CodingData(code=value["loinc"], display=value.get("name", ""), system=LOINC)]
                                        if value.get("loinc")
                                        else None
                                    ),
                                )
                                for value in test["values"]
                            ],
                        )
                        for test in body["tests"]
                    ]
                ),
                JSONResponse({"reference_id": body["reference_id"]}, status_code=202),
            ]
    ```
##  Example Workflow 
The four effects compose into the asynchronous OCR workflow:
  1. A scanned report arrives. The plugin calls `LabReport(reference_id=..., patient_id=..., ...).create()`, keying off an `reference_id` it controls.
  2. Days later, the OCR service finishes. The plugin calls `LabReport(reference_id=...).attach_results([LabTest(..., values=[LabValue(...)])])` to attach the abstracted tests and values — the report's observations populate from there.
  3. To fix the report name, the plugin calls `LabReport(reference_id=..., report_name=...).update()`.
  4. If the report was filed in error, the plugin calls `LabReport(reference_id=...).enter_in_error()`.
##  Related 
  - [`Observation`](/sdk/effect-observation/) — create or update individual clinical observations.

---

# Message Effect

Source: https://docs.canvasmedical.com/sdk/effect-messages/

The `Message` effect provides a unified way to create, edit, and transmit messages between users (patients or staff) within the Canvas platform. It supports standalone creation, immediate send after creating, edits, and dedicated send operations.
Build a `Message` with the attributes you want to set, then return one of its methods from your handler: `create()`, `create_and_send()`, `edit()`, or `send()`.
To route a message to a group of staff rather than one person, assign it to a team. See Assigning a message to a team.
##  Methods 
###  create() → Effect 
Creates a message without sending it.
  - `content`, `sender_id`, and `recipient_id` are required, and `content` cannot be empty.
  - `message_id` must not be set.
  - `team_id` is optional. Set it to create the message already assigned to a team.
###  create_and_send() → Effect 
Creates the message and sends it in one operation.
  - `content`, `sender_id`, and `recipient_id` are required, and `content` cannot be empty.
  - `message_id` must not be set.
  - `team_id` is optional. Set it to create the message already assigned to a team.
  - When the recipient is a patient, the patient needs an eligible contact point. See Sending to a patient.
###  edit() → Effect 
Changes an existing message.
  - `message_id` is required, and must be the id of an existing message.
  - Only the attributes you set on the effect are changed. Attributes you leave unset keep their current values.
  - `attachment_upload_keys` adds files to the message, and can be the only attribute you set. A locked message can't take new files. See Attaching files.
  - `team_id` must not be set. Editing a message keeps its team. To change the team, use `AssignMessageTeam`.
###  send() → Effect 
Sends a message that was already created, if you separated creating it from sending it.
  - Set `message_id` to the message to send.
  - `attachment_upload_keys` must not be set. Attach files with `create()`, `create_and_send()`, or `edit()` before sending.
  - `team_id` must not be set. Use `AssignMessageTeam` to change the team.
  - When the recipient is a patient, the patient needs an eligible contact point. See Sending to a patient.
##  Attaching files 
To attach files to a message, set `attachment_upload_keys` to a list of upload keys. Each key is the `key` of a `StoredFilePart` that a user uploaded to your plugin through a SimpleAPI route declared with `file_uploads="stored"`. See [Storing uploaded files](/sdk/handlers-simple-api-http/#storing-uploaded-files).
Attachments can be PNG, JPEG, or PDF files, and each key must come from a file your plugin uploaded. When the effect is applied, Canvas adds the files in the same transaction as the message, before the message is sent. Canvas then deletes the uploads, so each key works only once.
This SimpleAPI route sends the files in a `multipart/form-data` request to a patient, from the logged-in staff member:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note.message import Message
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin, api
    class SendFilesAPI(StaffSessionAuthMixin, SimpleAPI):
        @api.post("/send-files", file_uploads="stored")
        def send_files(self) -> list[Response | Effect]:
            form = self.request.form_data()
            message = Message(
                content="Here is the form we discussed.",
                sender_id=self.request.headers["canvas-logged-in-user-id"],
                recipient_id=form["patient_id"].value,
                attachment_upload_keys=[part.key for part in form.get_list("files") if not part.error],
            )
            return [message.create_and_send(), JSONResponse({})]
    ```
To read a message's attachments, see [MessageAttachment](/sdk/data-message/#messageattachment).
##  Sending to a patient 
When `create_and_send()` or `send()` sends a message to a patient, Canvas notifies the patient the same way it does for a message sent from the chart: a text message or email to each of the patient's phone numbers and email addresses that is eligible. A contact point is eligible when all three of these are true:
  - `has_consent` is `True`
  - `last_verified` is set
  - `state` is `"active"`
If the patient has no eligible contact point, Canvas cannot deliver the message. The message is saved but not sent, it appears as a draft in the patient's chart, and the effect fails.
To avoid this, check the patient's [contact points](/sdk/data-patient/#patientcontactpoint) before sending, and use `create()` instead when none is eligible:
    ```python
    has_eligible_contact = patient.telecom.filter(
        has_consent=True,
        last_verified__isnull=False,
        state="active",
    ).exists()
    message = Message(content=content, sender_id=staff.id, recipient_id=patient.id)
    effect = message.create_and_send() if has_eligible_contact else message.create()
    ```
Instances set up to deliver patient messages through a plugin, rather than through Canvas, do not send these notifications.
`create()` on its own never notifies the patient.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`message_id`| `str` or `UUID` or `None`| Unique identifier of an existing message. Must be unset when creating a new message.| For `edit()` and `send()`  
`content`| `str` or `None`| The text body of the message. Cannot be empty.| For `create()` and `create_and_send()`  
`sender_id`| `str` or `UUID`| ID of the user (Patient or Staff) who is sending the message.| Yes  
`recipient_id`| `str` or `UUID`| ID of the user (Patient or Staff) who will receive the message.| Yes  
`read`| `datetime` or `None`| Timestamp indicating when the message was read by the recipient. Defaults to `None` (unread).| No  
`attachment_upload_keys`| `list[str]` or `None`| Upload keys of PNG, JPEG, or PDF files to attach. Not allowed with `send()`. See Attaching files.| No  
`team_id`| `str` or `UUID` or `None`| ID of the [team](/sdk/data-team/) to assign the new message to. Not allowed with `edit()` or `send()`. See Assigning a message to a team.| No  
##  Validation & Errors 
Before any effect is emitted, the model runs these checks:
  - **Sender and Recipient Exist** Verifies that both `sender_id` and `recipient_id` belong to either a `Patient` or a `Staff` record.
  - **Create vs. Edit Constraints**
    - **Create** and **Create-and-Send** must **not** include `message_id`.
    - **Create** and **Create-and-Send** must include non-empty `content` (content cannot be blank or whitespace-only).
    - **Edit** operations **must** include a valid `message_id` that already exists in the database.
  - **Team Exists** When `create()` or `create_and_send()` sets `team_id`, it must be the id of an existing team. `edit()` and `send()` reject `team_id`.
##  Caveats 
  - **Role Constraints:** Sender and Recipient must always be one of Patient or Staff. Patient-to-Patient messaging is not allowed.
  - **UI Refresh Required:** Due to system constraints, editing a message requires a manual UI refresh for updated content to display.
  - **Immediate Post for Patient-to-Staff:** Messages created from a Patient to Staff cannot be drafted and will immediately appear in the timeline. This means that `CREATE_AND_SEND` and `SEND` effects will fail in these scenarios. You should only use the `CREATE` method for Patient-to-Staff messaging.
##  Example Usage 
    ```python
    from canvas_sdk.v1.data.message import Message as MessageModel
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.v1.data.staff import Staff
    from canvas_sdk.effects.note.message import Message
    staff = Staff.objects.first()
    patient = Patient.objects.first()
    ```
###  Create (originate) only 
    ```python
    m1 = Message(
        content="Your lab results are available.",
        sender_id=staff.id,
        recipient_id=patient.id
    )
    effect_create = m1.create()
    ```
###  Create and send in one step 
    ```python
    m2 = Message(
        content="Your appointment is confirmed.",
        sender_id=staff.id,
        recipient_id=patient.id
    )
    effect_create_and_send = m2.create_and_send()
    m = MessageModel.objects.get(message_id="msg-1234")
    ```
###  Edit an existing message 
    ```python
    m3 = Message(
        message_id=m.id,
        content="Updated: Your appointment has moved to 3pm."
    )
    effect_edit = m3.edit()
    ```
###  Send an existing message 
    ```python
    m4 = Message(message_id=m.id)
    effect_send = m4.send()
    ```
##  Assigning a message to a team 
A message always has one staff or patient `recipient`. It can also be assigned to a [team](/sdk/data-team/), so a group such as a front desk or a care team can work messages together. Assigning a team does not change the `recipient`. In the global Messages panel, the assignee filter defaults to **Me or my teams** , so staff see messages addressed to them and messages assigned to any of their teams, and the unread badge counts both. A message has a single read timestamp, so when one team member reads a team message, it is read for the whole team.
There are two ways to assign a team:
  - Set `team_id` when you create the message with `create()` or `create_and_send()`.
  - Return an `AssignMessageTeam` effect to set, change, or clear the team of an existing message.
###  AssignMessageTeam 
Build an `AssignMessageTeam` and return its `apply()` from your handler.
####  Methods 
#####  apply() → Effect 
Sets, changes, or clears the team of an existing message.
  - `message_id` is required, and must be the id of an existing message.
  - `team_id` is required. Set it to `None` to unassign the message.
  - The effect fails validation, and the message keeps its current team, when either id is not a valid UUID or does not match an existing message or team.
  - Each assignment, reassignment, and unassignment emits the [`MESSAGE_TEAM_ASSIGNED`](/sdk/events/#messaging) event. Creating a message with a team emits it too.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`message_id`| `str` or `UUID`| ID of the [message](/sdk/data-message/#message) to assign.| Yes  
`team_id`| `str` or `UUID` or `None`| ID of the [team](/sdk/data-team/) to assign the message to, or `None` to unassign it.| Yes  
####  Example 
This handler assigns each message a patient sends to the team named "Front Desk":
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note.message import AssignMessageTeam
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data import Message, Team
    class RoutePatientMessages(BaseHandler):
        """Assign messages that patients send to the Front Desk team."""
        RESPONDS_TO = EventType.Name(EventType.MESSAGE_CREATED)
        def compute(self) -> list[Effect]:
            message = Message.objects.select_related("sender").filter(id=self.target).first()
            # Only route messages a patient sent, not messages staff sent to a patient.
            if message is None or message.sender is None or message.sender.is_staff:
                return []
            team = Team.objects.filter(name="Front Desk").first()
            if team is None:
                return []
            return [AssignMessageTeam(message_id=message.id, team_id=team.id).apply()]
    ```

---

# Note Custom Content Effect

Source: https://docs.canvasmedical.com/sdk/effect-note-custom-content/

The `NoteCustomContent` effect adds a custom content block to a clinical note. Use it to show plugin-generated information where clinicians already work in the note. For example, show a patient summary above the note body or a card inside a note section. A block can be an inline HTML string or the URL of a page your plugin serves.
Return this effect in response to the [`NOTE__GET_CUSTOM_CONTENT`](/sdk/events/#note-custom-content) event. If no handler returns one, the note renders without custom content.
> **Warning:** **Beta Participation:** Custom content is part of the [revamped note beta program](/product-updates/note-revamp/), which Canvas turns on per instance. On an instance outside the beta, Canvas doesn't fire `NOTE__GET_CUSTOM_CONTENT`, and notes render without custom content. Reach out to Canvas support if you would like to participate.
* * *
##  How it works 
When a note renders, Canvas fires `NOTE__GET_CUSTOM_CONTENT` targeting that note. `event.target.id` holds the note's id. A handler subscribed to the event returns one or more `NoteCustomContent` effects, and Canvas renders each block in the section it names.
  - **Placement:** Set `section` to place a block at the top of that note section. Leave `section` unset to place the block above the note body.
  - **Note views:** Blocks with a `section` appear only while the note is grouped into sections, and are hidden while their section is collapsed. When a user views the whole note instead, or sections are turned off for the instance, only blocks without a `section` appear.
  - **Multiple blocks:** A handler can return several effects. Blocks returned for the same section stack in the order the handlers ran.
  - **Frames:** Canvas renders each block in its own iframe, so one plugin's block can't reach another's.
  - **Sections:** `section` names a section as the note renders it, not the clinical note section of a command. Canvas decides which commands each rendered section gathers, so a plugin that targets a rendered section keeps working if that grouping changes.
###  Attributes 
Field| Type| Default| Description  
---|---|---|---  
`section`| `NoteCustomContent.Section` or `None`| `None`| The note section to render the block in. When unset, the block renders above the note body.  
`url`| `str`| `None`| The URL of a page to render in the block, such as a [SimpleAPI](/sdk/handlers-simple-api/) route your plugin serves.  
`content`| `str`| `None`| An HTML string to render in the block.  
Set exactly one of `url` or `content`. The effect raises a validation error when both are set or when neither is set.
###  Sections 
`section` accepts a member of the `NoteCustomContent.Section` enum. Plain strings such as `"exam"` fail validation.
Member| Section  
---|---  
`NoteCustomContent.Section.HISTORY`| History  
`NoteCustomContent.Section.EXAM`| Exam  
`NoteCustomContent.Section.ASSESSMENT_PLAN`| Assessment & Plan  
`NoteCustomContent.Section.INTERNAL`| Internal  
###  Choose between `content` and `url`
Use `content` for a static block you can build as an HTML string inside the handler.
Use `url` for a block that updates itself after the note renders, as described in Keeping content current. Canvas renders inline `content` in a frame it manages, and a [WebSocket](/sdk/handlers-simple-api-websocket/) opened from that frame receives no messages. A page served from your plugin keeps its WebSocket connection open and can receive `Broadcast` messages.
###  Keeping content current 
Canvas fires `NOTE__GET_CUSTOM_CONTENT` when a note renders, and doesn't fire it again as the note changes. To keep a block current, hold its state in the page and push updates to it with a `Broadcast` effect, rather than expecting Canvas to ask for the content again:
  1. Serve the block from a `url`, and have the page connect to a [WebSocket](/sdk/handlers-simple-api-websocket/) channel your plugin defines. Use one channel per note, such as `note-<note id>`, so a block hears only about the note it's rendered in.
  2. From a handler that responds to the events that change the block, return a [`Broadcast`](/sdk/handlers-simple-api-websocket/#broadcasting-messages) effect for that channel. Put the new data in the message, so the page can update without fetching anything.
For example, a block that counts the note's commands can broadcast new counts when a command is added, deleted, or entered in error. Each command type fires its own events for these, such as `PLAN_COMMAND__POST_ORIGINATE`, `PLAN_COMMAND__POST_DELETE`, and `PLAN_COMMAND__POST_ENTER_IN_ERROR`.
This handler broadcasts to a note's channel when a Plan or Vitals command is added to the note:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Broadcast
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.command import Command
    class NotifyNoteBlocks(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.PLAN_COMMAND__POST_ORIGINATE),
            EventType.Name(EventType.VITALS_COMMAND__POST_ORIGINATE),
        ]
        def compute(self) -> list[Effect]:
            note_id = (
                Command.objects.filter(id=self.event.target.id)
                .values_list("note__id", flat=True)
                .first()
            )
            if not note_id:
                return []
            return [
                Broadcast(
                    channel=f"note-{note_id}",
                    message={
                        "event_type": "command_added",
                        "command_id": self.event.target.id,
                    },
                ).apply()
            ]
    ```
###  Permissions for URL blocks 
A `url` block's frame receives the permissions your plugin registers for that URL in the [`url_permissions`](/sdk/canvas_manifest/#url-permissions) section of `CANVAS_MANIFEST.json`, such as `MICROPHONE` or `ALLOW_SAME_ORIGIN`. The format is the same as for [modals and widgets](/sdk/layout-effect/#additional-configuration). Inline `content` blocks receive no permissions.
###  Frame height 
Each frame starts 120 pixels tall. To fit the frame to your block, send a `RESIZE` message with the block's height over the message channel Canvas opens with the frame:
    ```html
    <script>
      window.addEventListener('message', (event) => {
        if (event.data?.type !== 'INIT_CHANNEL' || !event.ports?.[0]) {
          return;
        }
        const port = event.ports[0];
        const reportHeight = () =>
          port.postMessage({ type: 'RESIZE', height: document.body.scrollHeight });
        reportHeight();
        new ResizeObserver(reportHeight).observe(document.body);
      });
    </script>
    ```
###  Examples 
Return an inline block above the note body:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note_custom_content import NoteCustomContent
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class NoteReminder(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE__GET_CUSTOM_CONTENT)
        def compute(self) -> list[Effect]:
            return [
                NoteCustomContent(
                    content="<p>Review the patient's care plan before signing.</p>",
                ).apply()
            ]
    ```
Return a block for each section, each pointing at a page the plugin serves. Here `/plugin-io/api/my_plugin/section` stands in for a SimpleAPI route in your plugin that returns the block's HTML:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note_custom_content import NoteCustomContent
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    BASE_URL = "/plugin-io/api/my_plugin"
    class SectionCards(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE__GET_CUSTOM_CONTENT)
        def compute(self) -> list[Effect]:
            note_id = self.event.target.id
            return [
                NoteCustomContent(
                    section=section,
                    url=f"{BASE_URL}/section?note_id={note_id}&section={section.value}",
                ).apply()
                for section in NoteCustomContent.Section
            ]
    ```
For a complete plugin that serves its blocks as pages and keeps them current over a WebSocket, see the [`note_custom_content` example plugin](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/note_custom_content).

---

# Note Footer Configuration Effect

Source: https://docs.canvasmedical.com/sdk/effect-note-footer-configuration/

The `NoteFooterConfiguration` effect configures the note footer at the note level (rather than per button). Its primary use is hiding Canvas's default state-transition buttons — Lock, Sign, Push charges, Delete, and so on — so that a plugin can supply its own footer buttons in their place, such as with [Note State Action Buttons](/sdk/handlers-action-buttons/#note-state-action-buttons).
Return this effect in response to the `NOTE_FOOTER__GET_CONFIGURATION` event, which fires when a note's footer is loaded. If your handler does not return a configuration, the default state-transition buttons remain visible.
Build a `NoteFooterConfiguration` with the attributes you want to set, then return its `apply()` from your handler.
* * *
##  Methods 
###  apply() → Effect 
Configures the footer of the note the event targets. No attribute is required.
##  How it works 
As a note's footer loads, Canvas fires `NOTE_FOOTER__GET_CONFIGURATION` targeting that note's external id. A handler subscribed to the event returns a `NoteFooterConfiguration` effect to configure the footer. If no plugin returns one, the footer keeps its default configuration.
###  Event payload 
Property| Value| Description  
---|---|---  
`event.target.id`| `str` (UUID)| The external id of the [Note](/sdk/data-note/#note) whose footer is loading.  
`event.actor`| user| The logged-in user viewing the note, when available.  
`event.context`| `{}`| Empty — no additional context is provided.  
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`hide_default_state_buttons`| `bool`| Hide Canvas's native footer state-transition buttons for this note. Defaults to `False`.| No  
##  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note_footer_configuration import NoteFooterConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class HideDefaultStateButtons(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_FOOTER__GET_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [NoteFooterConfiguration(hide_default_state_buttons=True).apply()]
    ```

---

# NoteMetadata Effect

Source: https://docs.canvasmedical.com/sdk/effect-note-metadata/

The `Note.upsert_metadata` method provides a flexible key-value storage system for note-specific data within the Canvas system. This method enables the creation and updating of custom metadata entries associated with note records, allowing for extensible note information storage beyond standard note fields.
##  Overview 
Note metadata serves as a powerful extension mechanism for storing custom note-related information that doesn't fit within the standard note data model. Metadata is managed through the `upsert_metadata` method on the `Note` effect class.
##  Methods 
###  upsert_metadata(key: str, value: str) → Effect 
Creates or updates a metadata entry for the specified note.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`key`| `str`| Unique identifier for the metadata entry within the note context| Yes  
`value`| `str`| The metadata value to store| Yes  
####  Prerequisites 
The `Note` effect must be initialized with an `instance_id` corresponding to an existing note.
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Id of the note record to associate metadata with| Yes  
####  Returns 
An `Effect` object configured for upserting note metadata.
####  Behavior 
  - If a metadata entry with the specified key already exists for the note, it will be updated with the new value
  - If no entry exists, a new metadata entry will be created
  - The operation is idempotent - repeated calls with the same key and value will not create duplicate entries
  - Raises `ValueError` if `instance_id` is not set on the `Note` effect
##  Implementation Details 
###  Validation 
The effect performs comprehensive validation before execution:
  1. **Note Existence Validation** : Verifies that the referenced note exists in the system
  - Queries the note database to confirm the `instance_id` corresponds to an existing note record
  - Returns a descriptive error if the note is not found
  1. **Field Validation** : Ensures all required fields are provided and properly formatted
  - `instance_id` must be set on the `Note` effect
  - Both `key` and `value` must be provided
##  Example Usage 
###  Basic Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    # Create a metadata entry for note tracking
    note = Note(instance_id="803ce56a-350e-49a4-abae-019d9f5f24b2")
    effect = note.upsert_metadata(key="my_plugin:external_system_id", value="EXT-12345")
    ```
###  Example 
    ```python
    import json
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class NoteMetadataHandler(BaseHandler):
      """
      Adds metadata to notes when a plan command is updated.
      """
      RESPONDS_TO = EventType.Name(EventType.PLAN_COMMAND__POST_UPDATE)
      def compute(self) -> list[Effect]:
        note_id = self.event.context["note"]["id"]
        command_id = self.event.target.id
        note = Note(instance_id=note_id)
        return [note.upsert_metadata(key="my_plugin:last_plan_update_command", value=str(command_id))]
    ```
###  Storing Multiple Metadata Entries 
    ```python
    import json
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class SigningMetadataHandler(BaseHandler):
      """
      Adds metadata to notes when they are signed.
      """
      RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
      def compute(self) -> list[Effect]:
        note_id = self.event.context["note"]["id"]
        state = self.event.context.get("note_state_change_event", {}).get("state")
        effects: list[Effect] = []
        if state == "SGN":
          note = Note(instance_id=note_id)
          # Store signing source
          effects.append(note.upsert_metadata(key="my_plugin:signing_source", value="protocol"))
          # Store additional context as JSON
          context_data = {
            "signed_by": self.event.context.get("actor", {}).get("id"),
            "protocol_version": "1.0"
          }
          effects.append(note.upsert_metadata(key="my_plugin:signing_context", value=json.dumps(context_data)))
        return effects
    ```
##  Best Practices 
###  Key Naming Conventions 
  1. **Use Descriptive Names** : Choose keys that clearly indicate the purpose of the metadata
  - Good: `external_system_id`, `workflow_stage`, `signing_source`
  - Avoid: `data1`, `temp`, `misc`
  1. **Namespace Your Keys** : Prefix keys with your plugin name to avoid collisions with other plugins
  - Example: `my_plugin:external_system_id`, `my_plugin:workflow_stage`, `my_plugin:signing_source`
###  Value Storage 
  1. **String Serialization** : All values are stored as strings. For complex data types:
         ```python
         import json
         from canvas_sdk.effects.note.note import Note
         note = Note(instance_id="803ce56a-350e-49a4-abae-019d9f5f24b2")
         complex_data = {"stage": "review", "approvers": ["user1", "user2"], "timestamp": "2025-01-15T10:30:00Z"}
         note.upsert_metadata(key="my_plugin:workflow_state", value=json.dumps(complex_data))
         ```
  2. **Boolean Values** : Store as "true" or "false" strings for consistency
         ```python
         from canvas_sdk.effects.note.note import Note
         needs_followup = True
         note = Note(instance_id="803ce56a-350e-49a4-abae-019d9f5f24b2")
         note.upsert_metadata(key="my_plugin:requires_followup", value="true" if needs_followup else "false")
         ```
##  Notes 
  - Metadata entries are note-specific and isolated - the same key can have different values for different notes
  - There is no built-in versioning; updating a key overwrites the previous value
  - The system does not enforce any schema on metadata values - validation is the responsibility of the implementing code

---

# Note Restrictions Effect

Source: https://docs.canvasmedical.com/sdk/effect-note-restrictions/

The `NoteRestrictionsEffect` and `NoteRestrictionsUpdatedEffect` allow plugins to restrict access to notes and push real-time permission updates to connected clients.
  - **`NoteRestrictionsEffect`** — returned by a plugin in response to a `GET_NOTE_RESTRICTIONS` event. It tells the Canvas UI whether the requesting user should see a banner, have the note content blurred, or have editing disabled.
  - **`NoteRestrictionsUpdatedEffect`** — emitted by a plugin at any time to signal that restrictions for a specific note have changed, causing all connected clients viewing that note to immediately refetch their restrictions.
* * *
##  NoteRestrictionsEffect 
To restrict a note for the requesting user, build a `NoteRestrictionsEffect` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Applies the restrictions to the user who opened the note. No attribute is required; an effect with none set leaves the note unrestricted.
###  How it works 
Every time a note is opened (or its restrictions are refetched), Canvas fires a `GET_NOTE_RESTRICTIONS` event targeting that note's external ID. Plugins that subscribe to this event can return a `NoteRestrictionsEffect` to control what the user sees.
If no plugin returns a `NoteRestrictionsEffect`, the note is unrestricted by default.
###  Event payload 
Property| Value| Description  
---|---|---  
`event.target.id`| `str` (UUID)| The `id` of the note being accessed. Use this to look up the note or its metadata.  
`event.actor.id`| `str` (int)| The database ID of the authenticated user requesting the note. Use `Staff.objects.filter(user__dbid=event.actor.id)` to resolve to a staff record.  
`event.context`| `{}`| Empty — no additional context is provided.  
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`restrict_access`| `bool`| Whether the requesting user is restricted from editing this note. Defaults to `False`.| No  
`blur_content`| `bool`| Whether the note body should be blurred for the requesting user. Defaults to `False`.| No  
`banner_message`| `str` | `None`| Message shown in the warning banner at the top of the note. If `None`, a default "This note is currently restricted." message is displayed. Defaults to `None`.| No  
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note.restrictions import NoteRestrictionsEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class NoteAccessHandler(BaseHandler):
        """Restrict access to notes based on custom business logic."""
        RESPONDS_TO = EventType.Name(EventType.GET_NOTE_RESTRICTIONS)
        def compute(self) -> list[Effect]:
            note_id = self.event.target.id
            actor_id = self.event.actor.id
            if not self.user_can_access(note_id, actor_id):
                return [
                    NoteRestrictionsEffect(
                        restrict_access=True,
                        blur_content=True,
                        banner_message="You do not have permission to view this note.",
                    ).apply()
                ]
            return []
        def user_can_access(self, note_id: str, actor_id: str) -> bool:
            # Custom access logic here
            ...
    ```
* * *
##  NoteRestrictionsUpdatedEffect 
To push a restriction change to everyone viewing a note, build a `NoteRestrictionsUpdatedEffect` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Tells every client viewing the note to refetch its restrictions.
  - `note_id` is required.
###  How it works 
When a plugin performs an action that changes whether a note is restricted (e.g. writing an edit lock to `NoteMetadata`, updating an access rule), it can emit a `NoteRestrictionsUpdatedEffect`. Canvas will broadcast a WebSocket notification to all clients currently viewing that note, causing them to refetch their restrictions immediately — no page reload required.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`note_id`| `str` (UUID)| The id of the note whose restrictions have changed.| Yes  
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note.restrictions import NoteRestrictionsUpdatedEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import NoteMetadata
    class NoteAccessChangedHandler(BaseHandler):
        """Broadcast a real-time restriction update after note metadata changes."""
        RESPONDS_TO = EventType.Name(EventType.NOTE_METADATA_UPDATED)
        def compute(self) -> list[Effect]:
            note_id = (
                NoteMetadata.objects
                .filter(id=self.event.target.id)
                .values_list("note__id", flat=True)
                .first()
            )
            if not note_id:
                return []
            return [NoteRestrictionsUpdatedEffect(note_id=str(note_id)).apply()]
    ```
* * *
##  Common use cases 
  - **Concurrent edit protection** — prevent multiple providers from editing the same note simultaneously; the second user sees a banner and disabled inputs until the first provider's session expires.
  - **Role-based note type access** — restrict certain note types (e.g. sensitive clinical notes) to a specific set of staff members.
  - **Sensitive note hiding** — blur the content of notes containing sensitive information for users who should not see the full details.
For full working implementations of these patterns, see the [**note-timeline-restrictions**](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/note-timeline-restrictions) example plugin, which covers concurrent edit locking, role-based access via a dashboard, automatic lock expiry via a cron job, and real-time updates.

---

# Note Effects

Source: https://docs.canvasmedical.com/sdk/effect-notes/

The Canvas SDK provides effects to facilitate creating, updating, and managing **visit notes** , **appointments** , and **schedule events**. Below you'll find detailed documentation for each effect type and their operations.
##  Note Effect 
The `Note` effect facilitates the creation and updating of visit notes for patients.
Build a `Note` with the attributes the operation needs, then return one of its methods from your handler. Each section below covers one method and lists its attributes: `create()`, `update()`, `push_charges()`, `lock()`, `sign()`, `unlock()`, `check_in()`, `no_show()`, `delete()`, `undelete()`, `discharge()`, and `upsert_metadata()`. Faxing a note uses a separate `FaxNoteEffect`, covered under Fax Note.
###  Create Note 
`create() → Effect`
Creates a new note. Can be passed an optional UUID as `instance_id` from the `uuid.uuid4` library, or will be assigned one if not present. Passing a user-set UUID as the `instance_id` allows for [assigning commands to the note](/sdk/commands/#chaining-methods-with-a-user-set-uuid) in the same plugin action.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier for the note| No  
`note_type_id`| `UUID` or `str`| Identifier for the note type| Yes  
`datetime_of_service`| `datetime.datetime`| When the service was provided| Yes  
`patient_id`| `str`| Identifier for the patient| Yes  
`practice_location_id`| `UUID` or `str`| Identifier for the practice location| Yes  
`provider_id`| `str`| Identifier for the provider| Yes  
`title`| `str` or `None`| Optional title for the note| No  
`supervising_provider_id`| `str` or `None`| Staff identifier for the supervising provider| No  
####  Implementation Details 
  - Validates that the note type exists and has an appropriate category
  - Ensures the patient exists in the system
  - Verifies that the practice location and provider are valid
  - If `supervising_provider_id` is provided, validates that the Staff record exists
> **Info:** You can set a custom `title` on any non–Schedule Event note type, regardless of the note type's `allow_custom_title` value. The `allow_custom_title` field on `NoteType` only applies to Schedule Event (Event Type) note types — it controls whether a custom description can be set on those events (stored on `note.description`) and is only enforced by the ScheduleEvent effect. It is not checked when the `Note` effect creates a chart note, so there is no need to gate the `title` on `allow_custom_title`.
####  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(
                note_type_id="note-type-uuid",
                datetime_of_service=datetime.datetime.now(),
                patient_id="patient-uuid",
                practice_location_id="practice-location-uuid",
                provider_id="provider-uuid"
            )
            return [note_effect.create()]
    ```
To create a note and add commands to it in the same `compute()`, give the note an `instance_id` you generate, use that same value as each command's `note_uuid`, and return the note's `create()` effect before the command effects. Canvas applies a handler's effects in the order they are returned, so the note exists by the time the commands are originated:
    ```python
    import datetime
    import uuid
    from canvas_sdk.commands import PlanCommand
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_id = str(uuid.uuid4())
            note_effect = Note(
                instance_id=note_id,
                note_type_id="note-type-uuid",
                datetime_of_service=datetime.datetime.now(),
                patient_id="patient-uuid",
                practice_location_id="practice-location-uuid",
                provider_id="provider-uuid",
            )
            plan = PlanCommand(note_uuid=note_id, narrative="Follow up in two weeks")
            return [note_effect.create(), plan.originate()]
    ```
###  Update Note 
`update() → Effect`
Updates an existing note. Only certain fields can be modified after creation.
####  Attributes 
Attribute| Type| Description| Required| Updatable  
---|---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note to update| Yes| No  
`title`| `str` or `None`| Updated title for the note| No| Yes  
`datetime_of_service`| `datetime.datetime`| Updated service date/time| No| Yes  
`practice_location_id`| `UUID` or `str`| Updated practice location| No| Yes  
`provider_id`| `str`| Updated provider| No| Yes  
`supervising_provider_id`| `str` or `None`| Staff identifier for the supervising provider| No| Yes  
**Note** : `patient_id` and `note_type_id` cannot be updated after creation.
####  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-note-uuid")
            note_effect.title = "Updated Consultation Notes"
            note_effect.datetime_of_service = datetime.datetime.now()
            return [note_effect.update()]
    ```
###  Fax Note 
`FaxNoteEffect.apply() → Effect`
Sends an existing note via fax to a specified recipient. This effect allows you to transmit patient notes to external healthcare providers or facilities.
To fax a referral, imaging order, lab order or letter without the rest of its note, use the [fax effects](/sdk/effect-fax/).
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`note_id`| `UUID` or `str`| Identifier of the note to fax| Yes  
`recipient_name`| `str`| Name of the fax recipient| Yes  
`recipient_fax_number`| `str`| Fax number of the recipient. Should include the country code| Yes  
`include_coversheet`| `bool`| Whether to include a coversheet with the fax| No  
`subject`| `str` or `None`| Subject line for the coversheet (required if coversheet used)| No  
`comment`| `str` or `None`| Additional comments for coversheet (required if coversheet used)| No  
`location_id`| `UUID` or `str` or `None`| Practice location ID (required if coversheet used)| No  
####  Implementation Details 
  - Validates that the note exists in the system
  - If `include_coversheet` is `True`, the following fields become required:
    - `subject`: The subject line for the coversheet
    - `comment`: Additional comments to include on the coversheet
    - `location_id`: The practice location identifier (must exist in the system)
  - Validates that the practice location exists if provided
  - The fax is recorded as a [NoteActionEvent](/sdk/data-fax/#noteactionevent) on the note, so a plugin reads whether it was delivered through `note.action_events`. See [Faxes sent by a plugin](/sdk/data-fax/#faxes-sent-by-a-plugin)
####  Example Usage 
    ```python
    from canvas_sdk.effects.fax.note import FaxNoteEffect
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            # Basic fax without coversheet
            fax_effect = FaxNoteEffect(
                note_id="existing-note-uuid",
                recipient_name="Dr. Jane Smith",
                recipient_fax_number="15551234567"
            )
            return [fax_effect.apply()]
    ```
####  Example with Coversheet 
    ```python
    from canvas_sdk.effects.fax.note import FaxNoteEffect
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            # Fax with coversheet
            fax_effect = FaxNoteEffect(
                note_id="existing-note-uuid",
                recipient_name="Dr. Jane Smith",
                recipient_fax_number="15551234567",
                include_coversheet=True,
                subject="Patient Referral - Follow-up Care",
                comment="Please review attached consultation notes for continuing care.",
                location_id="practice-location-uuid"
            )
            return [fax_effect.apply()]
    ```
###  Note state transitions 
The state change effects below (push charges, lock, sign, unlock, check in, no show, delete, undelete, and discharge) each move a note to a new [state](/sdk/data-note/#notestates), and each is accepted only from certain current states. Which transitions a note allows depends on its note type's category, and on whether the type is billable or requires a signature. An effect applied from any other state raises `ValueError: Invalid state transition`.
Effect| Moves the note to| Allowed from  
---|---|---  
`push_charges()`| `PSH`| `NEW`, `CVD`, `PSH`, `ULK`, `UND`. Billable encounter note types only, and only when the Push charges button is enabled.  
`lock()`| `LKD`| `NEW`, `CVD`, `ULK`, `UND`, and also `PSH` for encounter notes. Appointment notes lock only from `NSW`.  
`sign()`| `SGN`| `LKD`, or `SGN` to sign again. Note types with `is_sig_required` only.  
`unlock()`| `ULK`| `LKD`, and also `SGN` for note types with `is_sig_required`. On appointment notes, unlocking moves `LKD` back to `NSW`.  
`check_in()`| `CVD`| `BKD`, `RVT`, `NSW`. Appointment notes only.  
`no_show()`| `NSW`| `BKD`, `RVT`. Appointment notes only.  
`delete()`| `DLT`| `NEW`, `CVD`, `ULK`, `UND`, and also `PSH` for encounter notes. Appointment notes delete only from `SCH`.  
`undelete()`| `UND`| `DLT`. Not available for appointment notes.  
`discharge()`| `DSC`| `NEW`, `CVD`, `ULK`, `UND`. Inpatient notes only.  
Notes in the remaining categories, such as message, letter, data, and search notes, accept none of these effects.
###  Push Charges 
`push_charges() → Effect`
Pushes the charges from the Note to its associated Claim in the Revenue module. Has the exact same effect as clicking on the `Push charges` button in the Note footer.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note to update| Yes  
**Note** : `instance_id` must be a valid, existing Note, and its NoteTypeVersion must have `is_billable` = True.
####  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-note-uuid")
            return [note_effect.push_charges()]
    ```
> **Info:** This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found.
To change the charge amount on a claim that already exists, use the [`UpdateClaimLineItem`](/sdk/effect-claims/#updateclaimlineitem) effect. Alternatively, add [BillingLineItems](/sdk/effect-billing-line-items/) to the patient's note and then push charges so the claim is updated appropriately. The FHIR Claim API only supports changing the queue or adding a comment, so charge amounts cannot be edited there.
To move a claim into a specific revenue queue from a plugin — for example, to route contract-based claims that do not go through a clearinghouse into a queue your team works manually — use [`ClaimEffect.move_to_queue()`](/sdk/effect-claims/#move-to-queue).
###  Lock 
`lock() → Effect`
Locks an existing note, preventing further modifications. Has the exact same effect as clicking on the `Lock` button in the Note footer.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note to lock| Yes  
**Note** : `instance_id` must be a valid, existing Note that is not already locked.
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-note-uuid")
            return [note_effect.lock()]
    ```
> **Info:** This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found.
####  Validating before a note is locked or signed 
To conditionally allow or block a note from being locked or signed — for example, requiring that a specific command or CPT code is present, that the signer is on the patient's care team, or that the signer holds a matching state license — use the [`NOTE_STATE_CHANGE_EVENT_PRE_CREATE`](/sdk/effect-event-validation-error/) validation-error effect. When the validation fails, the effect prevents the state change and surfaces an error to the user. See the [`pre-lock-validation` example plugin](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/pre-lock-validation/pre_lock_validation).
For example, to block a lock until the note has a billing line item:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.validation import EventValidationError
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.billing import BillingLineItem, BillingLineItemStatus
    class RequireCptBeforeLock(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_PRE_CREATE)
        def compute(self) -> list[Effect]:
            if self.event.context.get("state") != "LKD":
                return []
            has_line_item = BillingLineItem.objects.filter(
                note__id=self.event.context["note_id"],
                status=BillingLineItemStatus.ACTIVE,
            ).exists()
            if has_line_item:
                return []
            error = EventValidationError()
            error.add_error("Add a CPT code before locking this note.")
            return [error.apply()]
    ```
###  Sign 
`sign() → Effect`
Signs an existing note, marking it as reviewed and approved by the provider. Has the exact same effect as clicking on the `Sign` button in the Note footer.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note to sign| Yes  
**Note** : `instance_id` must be a valid, existing Note that is not already signed.
> **Warning:** A note must be **locked before it can be signed**. Only certain note state transitions are allowed, and `SGN` is not reachable directly from `ULK` or `CVD` — calling `sign()` on an unlocked note raises `ValueError: Invalid state transition`. The Canvas UI combines both actions into the `Sign` button (which is why you'll see two note-state-change events in the audit history). A plugin must do the same and sequence a `lock()` effect before the `sign()` effect.
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-note-uuid")
            return [note_effect.sign()]
    ```
To lock and sign a note in a single plugin action, return the `lock()` effect before the `sign()` effect:
    ```python
    # inside compute()
    note = Note(instance_id="existing-note-uuid")
    return [note.lock(), note.sign()]
    ```
> **Info:** This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found.
###  Unlock 
`unlock() → Effect`
Unlocks a previously locked/signed note, allowing modifications again. Has the exact same effect as clicking on the `Unlock/Amend` button in the Note footer.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note to unlock| Yes  
**Note** : `instance_id` must be a valid, existing Note that is currently locked.
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-note-uuid")
            return [note_effect.unlock()]
    ```
> **Info:** This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found.
###  Check In 
`check_in() → Effect`
Marks a patient as checked in for their appointment. Has the exact same effect as clicking on the `Check In` button in the Appointment note.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note for check-in| Yes  
**Note** : `instance_id` must be a valid, existing Note associated with an appointment.
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-note-uuid")
            return [note_effect.check_in()]
    ```
> **Info:** This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found.
###  No Show 
`no_show() → Effect`
Marks an appointment as a no-show when the patient does not arrive. Has the exact same effect as marking an appointment as `No Show` in the Appointment note.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note to mark no-show| Yes  
**Note** : `instance_id` must be a valid, existing Note associated with an appointment.
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-note-uuid")
            return [note_effect.no_show()]
    ```
> **Info:** This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found.
###  Delete 
`delete() → Effect`
Deletes an existing note. Has the exact same effect as clicking on the `Delete` button in the Note footer.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note to delete| Yes  
**Note** : `instance_id` must be a valid, existing Note whose current state allows deletion (e.g. `NEW`, `CONVERTED`, `UNLOCKED`, `PUSHED`, or `UNDELETED`).
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-note-uuid")
            return [note_effect.delete()]
    ```
> **Info:** This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found.
###  Undelete 
`undelete() → Effect`
Restores a previously deleted note. Has the exact same effect as clicking on the `Restore` button on a deleted note.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note to restore| Yes  
**Note** : `instance_id` must be a valid, existing Note that is currently in the `DELETED` state.
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-note-uuid")
            return [note_effect.undelete()]
    ```
> **Info:** This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found.
###  Discharge 
`discharge() → Effect`
Locks and discharges an inpatient note. Has the exact same effect as clicking on the `Lock and discharge` button in the Inpatient note footer.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the inpatient note to discharge| Yes  
**Note** : `instance_id` must be a valid, existing Note whose `NoteTypeVersion.category` is `INPATIENT`, and whose current state allows discharge (`NEW`, `CONVERTED`, `UNLOCKED`, or `UNDELETED`).
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note_effect = Note(instance_id="existing-inpatient-note-uuid")
            return [note_effect.discharge()]
    ```
> **Info:** This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found.
###  Upsert Metadata 
`upsert_metadata(key: str, value: str) → Effect`
Creates or updates a metadata entry for the specified note. For detailed documentation on note metadata management, see [NoteMetadata Effect](/sdk/effect-note-metadata/).
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the note (set on the `Note` effect)| Yes  
`key`| `str`| Unique identifier for the metadata entry within the note context| Yes  
`value`| `str`| The metadata value to store| Yes  
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.note import Note
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            note = Note(instance_id="existing-note-uuid")
            return [note.upsert_metadata(key="my_plugin:custom_key", value="custom_value")]
    ```
##  ScheduleEvent Effect 
The `ScheduleEvent` effect enables creating, updating, and deleting schedule events for providers, with optional patient association.
Build a `ScheduleEvent` with the attributes the operation needs, then return one of its methods from your handler: `create()`, covered here, or `update()`, `reschedule()`, or `delete()`.
`create() → Effect` creates a schedule event with the attributes below.
> **Info:** Canvas doesn't check the provider's availability when a plugin creates, updates, or reschedules a schedule event. The double booking setting and [Google Calendar Sync](/product-updates/google-calendar-sync/) busy time don't block the effect, so check for conflicts in your plugin before booking.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`note_type_id`| `UUID` or `str`| Identifier for the note type (must be of category `SCHEDULE_EVENT`)| Yes  
`patient_id`| `str` or `None`| Identifier for the patient (if applicable)| Conditional  
`description`| `str` or `None`| Custom description for the event| Conditional  
`start_time`| `datetime.datetime`| Start time of the event| Yes  
`duration_minutes`| `int`| Duration of the event in minutes| Yes  
`practice_location_id`| `UUID` or `str`| Identifier for the practice location| Yes  
`provider_id`| `str`| Identifier for the provider| Yes  
`status`| `AppointmentProgressStatus` or `None`| Status of the event| No  
`external_identifiers`| `list[AppointmentIdentifier]` or `None`| External system identifiers| No  
###  Implementation Details 
  - Validates that the note type exists and is of category `SCHEDULE_EVENT`
  - Ensures patient is provided if the note type requires it
  - Verifies that custom descriptions are only used for note types that allow them
  - Validates that the practice location and provider exist
###  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note.appointment import ScheduleEvent
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            schedule_event_effect = ScheduleEvent(
                note_type_id="schedule-event-note-type-uuid",
                patient_id="patient-uuid",  # Optional depending on note type
                description="Team meeting",  # Optional depending on note type
                start_time=datetime.datetime.now(),
                duration_minutes=30,
                practice_location_id="practice-location-uuid",
                provider_id="provider-uuid"
            )
            return [schedule_event_effect.create()]
    ```
###  Update Schedule Event 
`update() → Effect`
Updates an existing schedule event in place.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the event to update| Yes  
`start_time`| `datetime.datetime`| New start time| No  
`duration_minutes`| `int`| New duration in minutes| No  
`description`| `str` or `None`| Updated description| No  
`practice_location_id`| `UUID` or `str`| New practice location| No  
`provider_id`| `str`| New provider| No  
`status`| `AppointmentProgressStatus` or `None`| Updated status| No  
####  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note import AppointmentIdentifier
    from canvas_sdk.effects.note.appointment import ScheduleEvent
    from canvas_sdk.effects.note.base import AppointmentIdentifier
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            schedule_event_effect = ScheduleEvent(instance_id="existing-event-uuid")
            schedule_event_effect.start_time = datetime.datetime.now() + datetime.timedelta(days=1)
            schedule_event_effect.duration_minutes = 60
            schedule_event_effect.description = "Rescheduled team meeting"
            schedule_event_effect.external_identifiers = [
                AppointmentIdentifier(system="test_system", value="123TEST")
            ]
            return [schedule_event_effect.update()]
    ```
###  Reschedule Schedule Event 
`reschedule() → Effect`
Reschedules an existing schedule event by creating a new event and cancelling the original. This maintains the event history and ensures proper tracking of rescheduled events.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the event to reschedule| Yes  
`start_time`| `datetime.datetime`| New start time| No  
`duration_minutes`| `int`| New duration in minutes| No  
`description`| `str` or `None`| Updated description| No  
`practice_location_id`| `UUID` or `str`| New practice location| No  
`provider_id`| `str`| New provider| No  
`status`| `AppointmentProgressStatus` or `None`| Updated status| No  
`external_identifiers`| `list[AppointmentIdentifier]` or `None`| Updated external identifiers| No  
**Note** : At least one field (besides `instance_id`) must be modified.
####  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note.appointment import ScheduleEvent
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            schedule_event_effect = ScheduleEvent(instance_id="existing-event-uuid")
            schedule_event_effect.start_time = datetime.datetime.now() + datetime.timedelta(hours=3)
            schedule_event_effect.duration_minutes = 45
            return [schedule_event_effect.reschedule()]
    ```
###  Delete Schedule Event 
`delete() → Effect`
Marks a schedule event as cancelled.
####  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note.appointment import ScheduleEvent
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            schedule_event_effect = ScheduleEvent(instance_id="existing-event-uuid")
            return [schedule_event_effect.delete()]
    ```
* * *
##  Appointment Effect 
The `Appointment` effect facilitates creating, updating, and cancelling patient appointments with providers.
Build an `Appointment` with the attributes the operation needs, then return one of its methods from your handler: `create()`, covered here, or `update()`, `reschedule()`, `cancel()`, or `revert()`.
`create() → Effect` creates an appointment with the attributes below.
> **Info:** Canvas doesn't check the provider's availability when a plugin creates, updates, or reschedules an appointment. The double booking setting and [Google Calendar Sync](/product-updates/google-calendar-sync/) busy time don't block the effect, so check for conflicts in your plugin before booking.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`appointment_note_type_id`| `UUID` or `str`| Identifier for the appointment note type (must be of category `ENCOUNTER` and scheduleable)| Yes  
`patient_id`| `str`| Identifier for the patient| Yes  
`meeting_link`| `str` or `None`| Link for virtual appointments| No  
`start_time`| `datetime.datetime`| Start time of the appointment| Yes  
`duration_minutes`| `int`| Duration of the appointment in minutes| Yes  
`practice_location_id`| `UUID` or `str`| Identifier for the practice location| Yes  
`provider_id`| `str`| Identifier for the provider| Yes  
`status`| `AppointmentProgressStatus` or `None`| Status of the appointment| No  
`external_identifiers`| `list[AppointmentIdentifier]` or `None`| External system identifiers| No  
###  Implementation Details 
  - Validates that the appointment note type exists, is of category `ENCOUNTER`, and is scheduleable
  - Ensures the patient exists in the system
  - Verifies that the practice location and provider exist
  - Records one `SCH` (Scheduling) and one `BKD` (Booked) entry in the appointment note's [state history](/sdk/data-note/#notestatechangeevent). Both entries have the user who triggered the effect as their `originator`, or Canvas Bot if no user triggered it. The note's own `originator` is the appointment's provider.
###  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note.appointment import Appointment
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            appointment_effect = Appointment(
                appointment_note_type_id="appointment-note-type-uuid",
                patient_id="patient-uuid",
                meeting_link="https://zoom.us/example-link",  # Optional
                start_time=datetime.datetime.now(),
                duration_minutes=60,
                practice_location_id="practice-location-uuid",
                provider_id="provider-uuid"
            )
            return appointment_effect.create()
    ```
###  Update Appointment 
`update() → Effect`
Updates an existing appointment in place.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of appointment to update| Yes  
`start_time`| `datetime.datetime`| New start time| No  
`duration_minutes`| `int`| New duration in minutes| No  
`meeting_link`| `str` or `None`| Updated meeting link| No  
`practice_location_id`| `UUID` or `str`| New practice location| No  
`provider_id`| `str`| New provider| No  
`status`| `AppointmentProgressStatus` or `None`| Updated status| No  
`external_identifiers`| `list[AppointmentIdentifier]` or `None`| Updated external identifiers| No  
**Note** : `patient_id` cannot be updated after creation.
####  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note import AppointmentIdentifier
    from canvas_sdk.effects.note.appointment import Appointment
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            appointment_effect = Appointment(instance_id="existing-appointment-uuid")
            appointment_effect.start_time = datetime.datetime.now() + datetime.timedelta(hours=2)
            appointment_effect.duration_minutes = 45
            appointment_effect.meeting_link = "https://new-meeting-link.com"
            appointment_effect.external_identifiers = [
                AppointmentIdentifier(system="my_external_system", value="appt-12345")
            ]
            return appointment_effect.update()
    ```
###  Reschedule Appointment 
`reschedule() → Effect`
Reschedules an existing appointment by creating a new appointment and cancelling the original. This maintains the appointment history and ensures proper tracking of rescheduled appointments.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of appointment to reschedule| Yes  
`start_time`| `datetime.datetime`| New start time| No  
`duration_minutes`| `int`| New duration in minutes| No  
`meeting_link`| `str` or `None`| Updated meeting link| No  
`practice_location_id`| `UUID` or `str`| New practice location| No  
`provider_id`| `str`| New provider| No  
`status`| `AppointmentProgressStatus` or `None`| Updated status| No  
`external_identifiers`| `list[AppointmentIdentifier]` or `None`| Updated external identifiers| No  
**Note** : At least one field (besides `instance_id`) must be modified. `patient_id` cannot be updated after creation.
Rescheduling adds a `BKD` (Booked) entry to the appointment note's [state history](/sdk/data-note/#notestatechangeevent). The entry has the user who triggered the effect as its `originator`, or Canvas Bot if no user triggered it.
####  Example Usage 
    ```python
    import datetime
    from canvas_sdk.effects.note.appointment import Appointment
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            appointment_effect = Appointment(instance_id="existing-appointment-uuid")
            appointment_effect.start_time = datetime.datetime.now() + datetime.timedelta(days=1)
            appointment_effect.duration_minutes = 60
            return appointment_effect.reschedule()
    ```
###  Cancel Appointment 
`cancel() → Effect`
Cancels an existing appointment and updates its status.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the appointment to cancel| Yes  
**Note** : `instance_id` must be a valid, existing Appointment whose current state allows cancellation. An appointment can only be cancelled when it is in the `BOOKED` or `REVERTED` state.
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.appointment import Appointment
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            appointment_effect = Appointment(instance_id="existing-appointment-uuid")
            return appointment_effect.cancel()
    ```
###  Revert Appointment 
`revert() → Effect`
Reverts a booked or checked-in appointment back to a state where it can be checked in, cancelled, rescheduled, or marked as no-show.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`instance_id`| `UUID` or `str`| Identifier of the appointment to revert| Yes  
**Note** : `instance_id` must be a valid, existing Appointment whose current state allows reversion. An appointment can only be reverted when it is in the `CANCELLED`, `CONVERTED`, or `NOSHOW` state.
####  Example Usage 
    ```python
    from canvas_sdk.effects.note.appointment import Appointment
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            appointment_effect = Appointment(instance_id="existing-appointment-uuid")
            return appointment_effect.revert()
    ```
##  Managing Appointment Labels 
Canvas supports adding up to 3 labels per appointment for categorization and workflow automation. Labels can be managed programmatically using the appointment label effects.
For detailed documentation on appointment label management, see [Appointment Label Effects](/sdk/effect-appointment-labels/).
###  Quick Example 
    ```python
    from canvas_sdk.effects.note.appointment import AddAppointmentLabel, RemoveAppointmentLabel
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.APPOINTMENT_LABEL_ADDED), EventType.Name(EventType.APPOINTMENT_LABEL_REMOVED)]
        def compute(self):
            # Add labels to an appointment
            add_effect = AddAppointmentLabel(
                appointment_id="appointment-uuid",
                labels={"URGENT", "FOLLOW_UP"}
            )
            # Remove labels from an appointment
            remove_effect = RemoveAppointmentLabel(
                appointment_id="appointment-uuid",
                labels={"CANCELLED"}
            )
            return [add_effect.apply(), remove_effect.apply()]
    ```
* * *
##  Validation 
All effects perform comprehensive validation before execution:
  1. **Entity Existence** : Validates that referenced entities (patients, providers, practice locations, note types) exist in the system
  2. **Type Compatibility** : Ensures note types are appropriate for the intended operation:
     - Visit notes cannot use `APPOINTMENT`, `SCHEDULE_EVENT`, `MESSAGE`, or `LETTER` note types
     - Schedule events must use `SCHEDULE_EVENT` note types
     - Appointments must use `ENCOUNTER` note types that are scheduleable
  3. **Field Requirement Enforcement** : The system validates conditional field requirements based on note type configurations:
     - **Patient Association Requirements** : For note types with `is_patient_required=True`, the system enforces that a valid patient ID is provided. This is particularly important for schedule events that may or may not be associated with specific patients.
     - **Custom Description Validation** : When a note type has `allow_custom_title=False`, the system prevents custom descriptions from being added. This ensures adherence to standardized naming conventions for certain types of appointments and events.
     - **Required Field Validation** : All required fields are checked for proper values and formats before the effect is executed.
  4. **Update Restrictions** : Certain fields cannot be modified after creation:
     - **Notes** : `patient_id` and `note_type_id` are immutable
     - **Appointments** : `patient_id` is immutable
     - **All Effects** : At least one field must be modified for an update operation to succeed

---

# Observation Effect

Source: https://docs.canvasmedical.com/sdk/effect-observation/

The `Observation` effect provides a unified way to create and update clinical observations within the Canvas platform. Observations can include vitals (blood pressure, temperature, etc.), lab results, and other clinical measurements. The effect supports structured coding using standard terminologies (LOINC, SNOMED), components for multi-part measurements, and value codings for interpretation.
Build an `Observation` with the attributes you want to set, then return one of its methods from your handler: `create()`, `update()`, or `enter_in_error()`.
##  Methods 
The examples below share this setup:
    ```python
    import datetime
    from canvas_sdk.effects.observation import Observation, CodingData, ObservationComponentData
    from canvas_sdk.v1.data.observation import Observation as ObservationModel
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.first()
    ```
###  create() → Effect 
Create a new observation record.
####  Validation 
  - `observation_id` must **not** be set (will be generated by the system)
  - `patient_id` is **required**
  - `name` is **required**
  - `effective_datetime` is **required**
  - If `is_member_of_id` is provided, the parent observation must exist
####  Example: Blood Pressure Observation 
    ```python
    # Create a blood pressure observation with components and codings
    bp_observation = Observation(
        patient_id=patient.id,
        name="Blood Pressure",
        category="vital-signs",
        value="120/80",
        units="mmHg",
        effective_datetime=datetime.datetime.now(),
        codings=[
            CodingData(
                code="85354-9",
                display="Blood pressure panel with all children optional",
                system="http://loinc.org",
                version="2.73",
                user_selected=True,
            )
        ],
        components=[
            ObservationComponentData(
                value_quantity="120",
                value_quantity_unit="mmHg",
                name="Systolic Blood Pressure",
                codings=[
                    CodingData(
                        code="8480-6",
                        display="Systolic blood pressure",
                        system="http://loinc.org",
                    )
                ],
            ),
            ObservationComponentData(
                value_quantity="80",
                value_quantity_unit="mmHg",
                name="Diastolic Blood Pressure",
                codings=[
                    CodingData(
                        code="8462-4",
                        display="Diastolic blood pressure",
                        system="http://loinc.org",
                    )
                ],
            ),
        ],
        value_codings=[
            CodingData(
                code="normal",
                display="Normal",
                system="http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
            )
        ],
    )
    effect_create = bp_observation.create()
    ```
####  Example: Simple Lab Result 
    ```python
    # Create a simple lab observation
    glucose = Observation(
        patient_id=patient.id,
        name="Glucose",
        category="laboratory",
        value="95",
        units="mg/dL",
        effective_datetime=datetime.datetime.now(),
        codings=[
            CodingData(
                code="2339-0",
                display="Glucose [Mass/volume] in Blood",
                system="http://loinc.org",
            )
        ],
    )
    effect_create_lab = glucose.create()
    ```
####  Example: Multiple Categories 
    ```python
    # Create an observation that belongs to multiple categories
    comprehensive_assessment = Observation(
        patient_id=patient.id,
        name="Comprehensive Physical Assessment",
        category=["vital-signs", "exam"],  # Multiple categories
        value="Normal",
        effective_datetime=datetime.datetime.now(),
        codings=[
            CodingData(
                code="29545-1",
                display="Physical examination",
                system="http://loinc.org",
            )
        ],
    )
    effect_create_multi = comprehensive_assessment.create()
    ```
###  update() → Effect 
Update an existing observation.
  - Only fields marked dirty (modified on the model) are included in the update.
####  Validation 
  - `observation_id` is **required** and must reference an existing observation
  - All other fields are optional; only dirty (modified) fields are updated
  - If `is_member_of_id` is provided, the parent observation must exist
####  Example 
    ```python
    # Find an existing observation
    existing_obs = ObservationModel.objects.filter(patient_id=patient.id).first()
    # Update the blood pressure values
    updated_bp = Observation(
        observation_id=existing_obs.id,
        value="130/85",
        units="mmHg",
        components=[
            ObservationComponentData(
                value_quantity="130",
                value_quantity_unit="mmHg",
                name="Systolic Blood Pressure",
                codings=[
                    CodingData(
                        code="8480-6",
                        display="Systolic blood pressure",
                        system="http://loinc.org",
                    )
                ],
            ),
            ObservationComponentData(
                value_quantity="85",
                value_quantity_unit="mmHg",
                name="Diastolic Blood Pressure",
                codings=[
                    CodingData(
                        code="8462-4",
                        display="Diastolic blood pressure",
                        system="http://loinc.org",
                    )
                ],
            ),
        ],
    )
    effect_update = updated_bp.update()
    ```
###  enter_in_error() → Effect 
Marks an existing observation as entered in error. Use this when an observation was recorded incorrectly and should be flagged rather than deleted.
  - Only `observation_id` is allowed; setting any other field will raise a validation error.
####  Validation 
  - `observation_id` is **required** and must reference an existing observation
  - All other fields must **not** be set (only `observation_id` is allowed)
  - The observation must not already be entered in error
  - The observation must not belong to a locked note
####  Example 
    ```python
    # Find an observation that was recorded incorrectly
    erroneous_obs = ObservationModel.objects.filter(patient_id=patient.id).first()
    # Mark it as entered in error
    error_observation = Observation(observation_id=erroneous_obs.id)
    effect_error = error_observation.enter_in_error()
    ```
##  Attributes 
Name| Type| Description| Required  
---|---|---|---  
`observation_id`| `str` or `UUID` or `None`| Unique identifier of an existing observation. Must be unset when creating; required when updating.| For `update()` and `enter_in_error()`  
`patient_id`| `str` or `None`| ID of the patient for this observation. Required when creating.| For `create()`  
`is_member_of_id`| `str` or `UUID` or `None`| Reference to a parent observation (for grouping related observations).| No  
`category`| `str` or `list[str]` or `None`| Category of observation (e.g., "vital-signs", "laboratory", "imaging"). Can be a single category or a list of categories.| No  
`units`| `str` or `None`| Unit of measure for the observation value (e.g., "mmHg", "mg/dL").| No  
`value`| `str` or `None`| The observation value as a string.| No  
`note_id`| `int` or `None`| ID of the note associated with this observation.| No  
`name`| `str` or `None`| Human-readable name for the observation. Required when creating.| For `create()`  
`effective_datetime`| `datetime` or `None`| Date and time when the observation was taken. Required when creating.| For `create()`  
`codings`| `list[CodingData]` or `None`| List of standardized codes identifying this observation (e.g., LOINC codes).| No  
`components`| `list[ObservationComponentData]` or `None`| List of components for multi-part observations (e.g., systolic and diastolic BP).| No  
`value_codings`| `list[CodingData]` or `None`| List of coded values for interpretation (e.g., "normal", "abnormal").| No  
##  Helper Classes 
###  `CodingData`
Represents a standardized code from a terminology system (LOINC, SNOMED, etc.).
Name| Type| Description  
---|---|---  
`code`| `str`| The code value from the terminology system.  
`display`| `str`| Human-readable display text for the code.  
`system`| `str`| URI identifying the terminology system (e.g., "http://loinc.org").  
`version`| `str`| Version of the terminology system. Defaults to empty string.  
`user_selected`| `bool`| Whether this code was explicitly selected by the user. Defaults to False.  
###  `ObservationComponentData`
Represents a component of a multi-part observation (e.g., systolic and diastolic blood pressure).
Name| Type| Description  
---|---|---  
`value_quantity`| `str`| The numeric value of this component.  
`value_quantity_unit`| `str`| Unit of measure for this component value.  
`name`| `str`| Name of this component.  
`codings`| `list[CodingData]` or `None`| Standardized codes identifying this component.

---

# Patient Facility Address

Source: https://docs.canvasmedical.com/sdk/effect-patient-facility-address/

The `PatientFacilityAddress` effect enables the creation, updating, and deletion of patient facility address records within Canvas. Patient facility addresses link patients to healthcare facilities, with optional room number information. The address details are automatically populated from the linked facility.
You can either reference an existing facility by ID, or create a new facility inline by providing the facility details.
Build a `PatientFacilityAddress` with the attributes you want to set, then return one of its methods from your handler: `create()`, `update()`, or `delete()`.
##  Methods 
###  create() → Effect 
Creates a patient facility address.
  - `patient_id` is required, and must be the id of an existing patient.
  - Supply either `facility_id` for an existing facility, or the fields to create a new facility (`facility_name`, `facility_city`, `facility_state_code`, and `facility_postal_code`), but not both. See Facility Reference Options.
  - `id` must not be set.
###  update() → Effect 
Updates an existing patient facility address.
  - `id` is required, and must be the id of an existing patient facility address.
###  delete() → Effect 
Deletes an existing patient facility address.
  - `id` is required, and must be the id of an existing patient facility address.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`id`| `str` or `UUID`| ID of the patient facility address| For `update()` and `delete()`  
`patient_id`| `str` or `UUID`| ID of the patient| For `create()`  
`facility_id`| `str` or `UUID`| ID of an existing facility to link| For `create()`, unless creating a new facility  
`facility_name`| `str`| Name of new facility to create| When creating a new facility  
`facility_npi_number`| `str`| NPI number for new facility| No  
`facility_phone_number`| `str`| Phone number for new facility| No  
`facility_fax_number`| `str`| Fax number for new facility| No  
`facility_active`| `bool`| Whether the new facility is active| No  
`facility_line1`| `str`| Street address line 1 for new facility| No  
`facility_line2`| `str`| Street address line 2 for new facility| No  
`facility_city`| `str`| City for new facility| When creating a new facility  
`facility_district`| `str`| District for new facility| No  
`facility_state_code`| `str`| State code for new facility (e.g., "CA", "NY")| When creating a new facility  
`facility_postal_code`| `str`| Postal code for new facility| When creating a new facility  
`room_number`| `str`| Room number at the facility| No  
`address_type`| `AddressType` or `str`| Type of address: "physical" or "both". Defaults to "physical".| No  
##  Facility Reference Options 
When creating a patient facility address, you must either:
  1. **Reference an existing facility** by providing `facility_id`
  2. **Create a new facility inline** by providing facility creation fields (`facility_name`, `facility_city`, `facility_state_code`, `facility_postal_code`)
> **Warning:** You cannot specify both `facility_id` and facility creation fields. Use one approach or the other.
###  Required Fields for Inline Facility Creation 
When creating a new facility inline, the following fields are required:
  - `facility_name`
  - `facility_city`
  - `facility_state_code`
  - `facility_postal_code`
##  Address Type 
The `address_type` field accepts the following values:
Value| Description  
---|---  
`physical`| Physical/street address (default)  
`both`| Both physical and mailing address  
##  Validation 
The effect validates:
  - **Create** : `patient_id` is required and must reference an existing patient
  - **Create** : Either `facility_id` or facility creation fields must be provided (not both)
  - **Create** : If `facility_id` is provided, it must reference an existing facility
  - **Create** : If creating a new facility, all required facility fields must be provided
  - **Update/Delete** : `id` is required and must reference an existing patient facility address
  - **Update** : If updating facility, same rules apply as create (facility_id OR creation fields)
  - `address_type` must be "physical" or "both" if provided
##  Example Usage 
###  Creating with Existing Facility 
    ```python
    from canvas_sdk.effects.patient_facility_address import PatientFacilityAddress, AddressType
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            effect = PatientFacilityAddress(
                patient_id="patient-uuid-here",
                facility_id="facility-uuid-here",
                room_number="101A",
                address_type=AddressType.PHYSICAL,
            )
            return [effect.create()]
    ```
###  Creating with New Facility 
    ```python
    from canvas_sdk.effects.patient_facility_address import PatientFacilityAddress, AddressType
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            effect = PatientFacilityAddress(
                patient_id="patient-uuid-here",
                facility_name="Downtown Medical Center",
                facility_line1="123 Main Street",
                facility_line2="Suite 400",
                facility_city="Boston",
                facility_state_code="MA",
                facility_postal_code="02101",
                facility_phone_number="617-555-1234",
                facility_npi_number="1234567890",
                room_number="Room 205",
                address_type=AddressType.PHYSICAL,
            )
            return [effect.create()]
    ```
###  Updating an Existing Address 
    ```python
    from canvas_sdk.effects.patient_facility_address import PatientFacilityAddress
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            # Update to use a different existing facility
            effect = PatientFacilityAddress(
                id="existing-address-uuid",
                facility_id="new-facility-uuid",
                room_number="202B",
            )
            return [effect.update()]
    ```
###  Deleting an Address 
    ```python
    from canvas_sdk.effects.patient_facility_address import PatientFacilityAddress
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            effect = PatientFacilityAddress(
                id="existing-address-uuid",
            )
            return [effect.delete()]
    ```
##  Notes 
  - The address details (line1, line2, city, state, country, postal_code) displayed for a patient facility address are automatically populated from the linked facility's address information.
  - When a facility's address is updated, all linked patient facility addresses are automatically updated to match. This synchronization happens asynchronously and applies to line1, line2, city, district, state_code, postal_code, and country fields. Non-address changes to the facility (such as name, NPI number, or phone number) do not trigger this cascade.
  - When creating a new facility inline, the facility is created first, then linked to the patient facility address.
  - Room number is optional and can be used to specify the patient's specific room within the facility.

---

# Patient Group

Source: https://docs.canvasmedical.com/sdk/effect-patient-group/

The Canvas SDK provides effects for managing patient membership in groups. These effects are idempotent — adding a patient who is already a member or deactivating a patient who is not an active member will have no effect.
##  PatientGroupEffect 
An effect class for performing actions on a patient group. Instantiate it with a `group_id`, then call methods to add or deactivate members.
###  Methods 
####  add_member(patient_ids: list[str]) → Effect 
Ensures one or more patients are members of the group.
Parameter| Type| Description  
---|---|---  
`patient_ids`| `list[str]`| List of [patient](/sdk/data-patient/) ids to add to the group  
####  deactivate_member(patient_ids: list[str]) → Effect 
Ensures one or more patients are not active members of the group. If a patient is currently locked in the group, this effect will be ignored for that patient.
Parameter| Type| Description  
---|---|---  
`patient_ids`| `list[str]`| List of [patient](/sdk/data-patient/) ids to deactivate from the group  
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`group_id`| `UUID`| The id of the [patient group](/sdk/data-patient-group/)| Yes  
###  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_group import PatientGroupEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Patient, PatientGroup
    class AddMemberHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_UPDATED)
        def compute(self) -> list[Effect]:
            """Add patients to a group."""
            patient = Patient.objects.get(id=self.target)
            group = PatientGroup.objects.first()
            effect = PatientGroupEffect(group_id=str(group.id))
            return [effect.add_member(patient_ids=[str(patient.id)])]
    class DeactivateMemberHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_UPDATED)
        def compute(self) -> list[Effect]:
            """Deactivate a patient from a group."""
            patient = Patient.objects.get(id=self.target)
            group = PatientGroup.objects.first()
            effect = PatientGroupEffect(group_id=str(group.id))
            return [effect.deactivate_member(patient_ids=[str(patient.id)])]
    ```

---

# Patient Identification Card Effect

Source: https://docs.canvasmedical.com/sdk/effect-patient-identification-card/

The `PatientIdentificationCard` effect adds, changes, or deletes an image of a patient's identification card, such as a driver's license, from a plugin. Use it to collect ID images during intake or registration. To read existing cards, see [PatientIdentificationCard](/sdk/data-patient/#patientidentificationcard) on the patient data model.
Build a `PatientIdentificationCard` with the attributes you want to set, then return one of its methods from your handler: `create()`, `update()`, or `delete()`.
##  Methods 
###  create() → Effect 
Creates an identification card for a patient.
  - `patient_id` and `image_upload_key` are required.
  - `card_id` must not be set.
###  update() → Effect 
Changes an existing identification card.
  - `card_id` is required, and must be the `dbid` of an existing card.
  - Only the attributes you set on the effect are changed.
  - `patient_id` cannot be changed, and `active` cannot be set to `None`.
###  delete() → Effect 
Deletes an existing identification card. `card_id` is required.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`card_id`| `int`| The `dbid` of an existing [PatientIdentificationCard](/sdk/data-patient/#patientidentificationcard). Cards have no UUID, so they are identified by `dbid`. Must be unset when creating a card.| For `update()` and `delete()`  
`patient_id`| `str`| The `id` of the [Patient](/sdk/data-patient/#patient) the card belongs to.| For `create()`  
`image_upload_key`| `str`| The upload key of the card image. See Card image.| For `create()`  
`title`| `str` or `None`| A label for the card, such as `"Driver license"`. Up to 255 characters.| No  
`active`| `bool`| Whether the card is active.| No  
##  Card image 
The card image is a PNG or JPEG file that a user uploads to your plugin through a SimpleAPI route declared with `file_uploads="stored"`. Set `image_upload_key` to the `key` of the uploaded `StoredFilePart`. See [Storing uploaded files](/sdk/handlers-simple-api-http/#storing-uploaded-files).
The key must come from a file your plugin uploaded, and the file must be a PNG or JPEG image. When the effect is applied, Canvas copies the file to the card and then deletes the upload, so each key works only once. On `update()`, setting `image_upload_key` replaces the card's image, and a key of `None` keeps the current image.
For working code, see Upload an ID card from a form.
##  Examples 
###  Upload an ID card from a form 
This SimpleAPI route creates an identification card from a `multipart/form-data` request that carries the patient's id, a title, and a photo of the card. The route uses the [API key mixin](/sdk/handlers-simple-api-http/#api-key-1), so declare the `simpleapi-api-key` secret in your manifest and set it on your instance:
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient import PatientIdentificationCard
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPI, api
    class IdentificationCardAPI(APIKeyAuthMixin, SimpleAPI):
        @api.post("/identification-card", file_uploads="stored")
        def identification_card(self) -> list[Response | Effect]:
            form = self.request.form_data()
            image = form["card_image"]
            if image.error:
                return [JSONResponse({"error": "upload failed"}, status_code=HTTPStatus.BAD_GATEWAY)]
            card = PatientIdentificationCard(
                patient_id=form["patient_id"].value,
                image_upload_key=image.key,
                title=form["title"].value,
            )
            return [card.create(), JSONResponse({}, status_code=HTTPStatus.ACCEPTED)]
    ```
Call the route with a `multipart/form-data` POST. Each form field name matches a key the handler reads, the card photo is sent as a file, and the API key goes in the `Authorization` header:
    ```shell
    curl --request POST \
         --url 'https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/identification-card' \
         --header 'Authorization: <api-key>' \
         --form 'patient_id=b80b1cdc2e6a4aca90ccebc02e683f35' \
         --form 'title=Driver license' \
         --form 'card_image=@license.jpg;type=image/jpeg'
    ```
The same request from a Python script, uploading a photo saved on disk, using the [`requests`](https://requests.readthedocs.io/) library:
    ```python
    from pathlib import Path
    import requests
    url = "https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/identification-card"
    image_path = Path("license.jpg")
    with image_path.open("rb") as image:
        response = requests.post(
            url,
            headers={"Authorization": "<api-key>"},
            data={
                "patient_id": "b80b1cdc2e6a4aca90ccebc02e683f35",
                "title": "Driver license",
            },
            files={"card_image": (image_path.name, image, "image/jpeg")},
            timeout=30,
        )
    print(response.status_code)
    ```
The route answers:
  - `202 Accepted` when the photo was stored and the effect was returned.
  - `502 Bad Gateway` when the photo failed to store.
  - `400 Bad Request` when the request isn't `multipart/form-data`.
  - `401 Unauthorized` when the API key is missing or wrong.
###  Deactivate or delete a card 
    ```python
    from canvas_sdk.effects.patient import PatientIdentificationCard
    from canvas_sdk.v1.data.patient import Patient
    patient = Patient.objects.get(id="d7af3e356368446c85b40a5d6ff7288e")
    card = patient.identification_cards.filter(active=True).first()
    # Deactivate a card
    deactivate = PatientIdentificationCard(card_id=card.dbid, active=False).update()
    # Delete a card
    delete = PatientIdentificationCard(card_id=card.dbid).delete()
    ```

---

# PatientMetadata Effect

Source: https://docs.canvasmedical.com/sdk/effect-patient-metadata/

The `PatientMetadata` effect provides a flexible key-value storage system for patient-specific data within the Canvas system. This effect enables the creation and updating of custom metadata entries associated with patient records, allowing for extensible patient information storage beyond standard demographic fields.
##  Overview 
Patient metadata serves as a powerful extension mechanism for storing custom patient-related information that doesn't fit within the standard patient data model. It uses the `.upsert(value)` method to apply a value to the key attributed with the Metadata effect object.
> **Info:** For storing mutable custom patient fields — such as a status or risk score that is not part of the standard Patient data model — the patient metadata key-value effect is the recommended approach rather than questionnaires (a questionnaire creates a new record on each update). You can also surface these values to end users by building a custom form in the demographics section of the profile with the [Patient Metadata Create form effect](/sdk/patient-metadata-create-form-effect/), though displaying the fields is optional — a plugin can set the data without exposing a form.
##  Methods 
###  upsert(value: str) → Effect 
Creates or updates a metadata entry for the specified patient and key combination.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`value`| `str`| The metadata value to store| Yes  
####  Behavior 
  - If a metadata entry with the specified key already exists for the patient, it will be updated with the new value
  - If no entry exists, a new metadata entry will be created
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`patient_id`| `str`| Id of the [Patient](/sdk/data-patient/) record to associate metadata with| Yes  
`key`| `str`| Unique identifier for the metadata entry within the patient context. Maximum 256 characters.| Yes  
##  Implementation Details 
###  Validation 
The effect performs comprehensive validation before execution:
  1. **Patient Existence Validation** : Verifies that the referenced patient exists in the system
  - Queries the patient database to confirm the `patient_id` corresponds to an existing patient record
  - Returns a descriptive error if the patient is not found
  1. **Field Validation** : Ensures all required fields are provided and properly formatted
  - Both `patient_id` and `key` must be non-empty strings
  - The `value` parameter in the `upsert` method must be provided
###  Data Structure 
The effect payload is structured as JSON with the following schema:
    ```json
    {
      "data": {
        "patient_id": "patient-id",
        "key": "metadata-key",
        "value": "metadata-value"
      }
    }
    ```
##  Example Usage 
###  Basic Usage 
    ```python
    from canvas_sdk.effects.patient_metadata import PatientMetadata
    # Create a metadata entry for patient preferences
    metadata = PatientMetadata(
        patient_id="550e8400e29b41d4a716446655440000",
        key="preferred_contact_time"
    )
    # Upsert the metadata value
    effect = metadata.upsert("morning")
    ```
###  Metadata Parsing Example 
    ```python
    import json
    import re
    from canvas_sdk.effects.patient_metadata import PatientMetadata
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.events import EventType
    class NarrativeMetadataExtractor(BaseHandler):
      """
      Extracts structured metadata from clinical narratives.
      """
      RESPONDS_TO = EventType.Name(EventType.PLAN_COMMAND__POST_UPDATE)
      def compute(self):
        patient_id = self.event.context["patient"]["id"]
        narrative = self.event.context.get("fields", {}).get("narrative", "")
        # Extract key-value pairs from narrative text
        # Pattern: key=somekey*value=somevalue
        key_match = re.search(r'key=([^*#_\s]+)', narrative)
        value_match = re.search(r'value=([^*#_\s]+)', narrative)
        if not (key_match and value_match):
          return []
        key = key_match.group(1)
        value = value_match.group(1)
        # Create metadata effect
        metadata = PatientMetadata(
          patient_id=patient_id,
          key=key
        )
        return [metadata.upsert(value)]
    ```
##  Best Practices 
###  Key Naming Conventions 
  1. **Use Descriptive Names** : Choose keys that clearly indicate the purpose of the metadata
  - Good: `external_mrn`, `preferred_pharmacy_id`, `risk_score_diabetes`
  - Avoid: `data1`, `temp`, `misc`
  1. **Namespace Your Keys** : When building integrations or modules, prefix keys to avoid collisions
  - Example: `integration_patient_id`, `module_diabetes_last_a1c_date`
###  Value Storage 
  1. **String Serialization** : All values are stored as strings. For complex data types:
         ```python
         # Storing JSON data
         import json
         from canvas_sdk.effects.patient_metadata import PatientMetadata
         metadata = PatientMetadata(
             patient_id="550e8400e29b41d4a716446655440000",
             key="result"
         )
         complex_data = {"scores": [85, 92, 78], "average": 85.0}
         metadata.upsert(json.dumps(complex_data))
         ```
  2. **Boolean Values** : Store as "true" or "false" strings for consistency
         ```python
         from canvas_sdk.effects.patient_metadata import PatientMetadata
         patient_consented = False
         metadata = PatientMetadata(
             patient_id="550e8400e29b41d4a716446655440000",
             key="boolean_value"
         )
         metadata.upsert("true" if patient_consented else "false")
         ```
##  Notes 
  - Metadata entries are patient-specific and isolated - the same key can have different values for different patients
  - There is no built-in versioning; updating a key overwrites the previous value
  - The system does not enforce any schema on metadata values - validation is the responsibility of the implementing code

---

# Patient Timeline

Source: https://docs.canvasmedical.com/sdk/effect-patient-timeline/

The Canvas SDK allows you to configure which note types a patient's chart shows and which the **New Note** button offers.
Both are controlled by the `PatientTimelineEffect` class, returned in response to the `PATIENT_TIMELINE__GET_CONFIGURATION` event, which fires when a patient's chart is loaded.
Build a `PatientTimelineEffect` with the attributes you want to set, then return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Applies the note type configuration to the patient's chart. No attribute is required.
  - Every UUID, in either attribute, must correspond to an existing [NoteType](/sdk/data-note/#notetype). A note type UUID that does not exist raises a `ValidationError` naming the note type that was not found.
  - Values that are not valid UUIDs also raise a `ValidationError`.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`excluded_note_types`| `list[str]`| A list of [`NoteType.unique_identifier`](/sdk/data-note/#notetype) values (UUIDs) to exclude from the patient's timeline. Defaults to `[]`.| No  
`allowed_new_note_types`| `list[str] \| None`| An allow-list of [`NoteType.unique_identifier`](/sdk/data-note/#notetype) values the **New Note** button may offer. `None` (the default) means no constraint; `[]` offers nothing, which hides the button. See Restricting note creation.| No  
The two attributes differ in scope, and you will usually want only one of them:
| `excluded_note_types`| `allowed_new_note_types`  
---|---|---  
direction| deny-list| allow-list  
existing notes on the timeline| **hidden**|  visible  
timeline's note type filter| type removed| type still offered  
**New Note** button| type removed| restricted to the list  
direct permalink to such a note| permission error| unaffected  
several plugins respond| **unioned**| **unioned**  
##  Excluding Note Types 
###  Example Usage 
The `excluded_note_types` list must contain `unique_identifier` values from the `NoteType` model. Each `NoteType` has a `unique_identifier` (UUID) that you can look up by querying the model:
    ```python
    from canvas_sdk.v1.data.note import NoteType
    # Find the unique_identifier for a note type by name
    note_type = NoteType.objects.get(name="Office visit")
    note_type.unique_identifier  # e.g. UUID("a3b9c1d2-...")
    # Or list all note types with their unique_identifiers
    for nt in NoteType.objects.all():
        print(f"{nt.name}: {nt.unique_identifier}")
    ```
Then use those `unique_identifier` values in the effect:
    ```python
    from canvas_sdk.effects.patient.timeline import PatientTimelineEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.note import NoteType
    class MyHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.PATIENT_TIMELINE__GET_CONFIGURATION)]
        def compute(self):
            # Use unique_identifier
            office_visit = NoteType.objects.get(name="Office visit", is_active=True)
            lab_visit = NoteType.objects.get(name="Lab visit", is_active=True)
            effect = PatientTimelineEffect(
                excluded_note_types=[
                    str(office_visit.unique_identifier),
                    str(lab_visit.unique_identifier),
                ]
            )
            return [effect.apply()]
    ```
###  Behavior 
> **Info:** **Chart Review notes cannot be excluded.** Even if a `CHART_REVIEW` note type is included in the `excluded_note_types` list, it will always be shown on the timeline. The system automatically removes it from any exclusion list.
  - **Permalink access** : If a user tries to directly access a note whose type has been excluded, they will receive a permission error.
  - **Multiple plugins** : If multiple plugins respond to the `PATIENT_TIMELINE__GET_CONFIGURATION` event, the excluded note types from all responses are combined.
  - **Note creation** : An excluded note type is also removed from the patient chart's **New Note** button and from the timeline's note type filter, so users cannot pick that type when creating a note. This governs what the UI offers — it does not reject a note of an excluded type created directly through the API.
> **Info:** **To restrict note creation without hiding existing notes:** `excluded_note_types` hides a patient's existing notes of that type _and_ removes the type from the **New Note** button. If you only want to restrict what the button offers, while leaving the patient's history visible and filterable, use `allowed_new_note_types` instead.
##  Restricting note creation 
`allowed_new_note_types` is an **allow-list** of the note types the **New Note** button may offer. It affects note _creation_ only: existing notes of a withheld type stay on the timeline, and the timeline's note type filter keeps offering that type, so a provider can still see and filter the history they are being stopped from adding to.
A common use is limiting which note types a given provider can originate. An organization might want only certain staff sending text messages to a patient, for example: the **New Note** button offers the Message type to those roles and withholds it from everyone else, while every provider can still read the messages already on the patient's chart and filter the timeline by them.
Inactive and deprecated note types are never offered, whether or not a plugin responds.
The example below allow-lists by the staff member's clinical role, so a nurse can send a message or log a phone call while only a physician is offered an office visit.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient.timeline import PatientTimelineEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.note import NoteType
    from canvas_sdk.v1.data.staff import Staff
    ALLOWED_BY_ROLE = {
        "MD": ["Office visit", "Phone call", "Message"],
        "RN": ["Phone call", "Message"],
    }
    class RestrictNewNoteTypes(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_TIMELINE__GET_CONFIGURATION)
        def compute(self) -> list[Effect]:
            staff = Staff.objects.filter(user__dbid=self.event.actor.id).first()
            role = staff.top_role_abbreviation if staff else None
            allowed_names = ALLOWED_BY_ROLE.get(role or "", ["Message"])
            note_types = NoteType.objects.filter(is_active=True, name__in=allowed_names)
            return [
                PatientTimelineEffect(
                    allowed_new_note_types=[str(nt.unique_identifier) for nt in note_types]
                ).apply()
            ]
    ```
To hide the button entirely, return an empty allow-list:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient.timeline import PatientTimelineEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class HideNewNoteButton(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_TIMELINE__GET_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [PatientTimelineEffect(allowed_new_note_types=[]).apply()]
    ```
###  Behavior 
What your plugin returns| Result  
---|---  
attribute omitted, or `None`| the full note type list, unchanged  
`allowed_new_note_types=[...]`| only those note types are offered  
`allowed_new_note_types=[]`| nothing is offered, so the **New Note** button is hidden entirely  
  - **Multiple plugins** : allow-lists from all responses are combined, the same way exclusions are. Note the consequence: a second plugin returning an allow-list _widens_ what a first one permits, so a restriction is only as tight as the most permissive plugin responding.
  - **Combined with exclusions** : a note type excluded via `excluded_note_types` stays out of the button even if the allow-list names it. Exclusions win because they affect far more — the timeline, the note type filter and permalink access — so they are the safer outcome when a plugin names the same type in both.
  - **Chart Review** : unlike exclusions, `CHART_REVIEW` is _not_ force-allowed here. Force-allowing it would make "nothing available" unreachable and the button could never be hidden.
  - **Plugin failures** : if the plugin runner cannot be reached, the note type list is left unconstrained rather than emptied.
> **Warning:** **This is a workflow guardrail, not an access control.** It governs what the **New Note** button offers. It does not reject a note of a restricted type created directly through the API. Do not rely on it to enforce access to sensitive note types — see [Note Restrictions](/sdk/effect-note-restrictions/) for controlling access to notes.
> **Info:** **Note types are configured per instance.** The names above are illustrative, so check what exists on your instance before matching on `name` — a name that does not exist simply matches nothing, silently shortening your allow-list. A `unique_identifier` is generated per instance too, so it cannot be hard-coded in a plugin meant to run on more than one; look the note types up at runtime and keep the mapping configurable. An identifier that does not exist raises a `ValidationError` rather than failing quietly.

---

# Patient Effect

Source: https://docs.canvasmedical.com/sdk/effect-patient/

The `Patient` effect enables the creation and updating of patient records within the Canvas system. This effect captures demographic information, contact details, and clinical associations necessary for patient registration and updates.
Build a `Patient` with the attributes you want to set, then return one of its two methods from your handler: `create()` for a new patient, or `update()` for an existing one.
##  Methods 
###  create() → Effect 
Creates a new patient record.
  - `first_name` and `last_name` are required.
  - `patient_id` is optional. By default Canvas generates the patient's id; to choose it yourself, see Supplying a patient id on creation.
See Creating a patient for an example.
###  update() → Effect 
Updates an existing patient record.
  - `patient_id` is required, and must be the id of an existing patient.
  - Only the attributes you set on the effect are changed. Attributes you leave unset keep their current values.
See Updating a patient for an example.
Both methods check that `default_location_id` and `default_provider_id`, when set, refer to an existing practice location and staff member.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`first_name`| `str`| Patient's first name| For `create()`  
`last_name`| `str`| Patient's last name| For `create()`  
`middle_name`| `str` or `None`| Patient's middle name| No  
`birthdate`| `datetime.date` or `None`| Patient's date of birth| No  
`prefix`| `str` or `None`| Name prefix (e.g., "Dr.", "Mr.")| No  
`suffix`| `str` or `None`| Name suffix (e.g., "Jr.", "III")| No  
`sex_at_birth`| `PersonSex` or `None`| Patient's sex assigned at birth| No  
`nickname`| `str` or `None`| Patient's preferred name or nickname| No  
`social_security_number`| `str` or `None`| Patient's SSN| No  
`administrative_note`| `str` or `None`| Administrative notes about the patient| No  
`clinical_note`| `str` or `None`| Clinical notes about the patient| No  
`default_location_id`| `str` or `None`| The `id` of the [PracticeLocation](/sdk/data-practicelocation/#practicelocation) to set as the patient's default practice location| No  
`default_provider_id`| `str` or `None`| The `id` of the [Staff](/sdk/data-staff/#staff) member to set as the patient's default provider| No  
`active`| `bool` or `None`| Whether the patient record is active| No  
`deceased`| `bool` or `None`| Whether the patient is deceased| No  
`deceased_datetime`| `datetime.datetime` or `None`| Date and time of patient's death| No  
`deceased_cause`| `str` or `None`| Cause of patient's death| No  
`deceased_comment`| `str` or `None`| Additional comments about patient's death| No  
`biological_race_codes`| `list[str]` or `None`| CDC race codes describing the patient's biological race (e.g., `"2106-3"`)| No  
`cultural_ethnicity_codes`| `list[str]` or `None`| CDC ethnicity codes describing the patient's cultural ethnicity (e.g., `"2186-5"`)| No  
`previous_names`| `list[str]` or `None`| List of patient's previous names| No  
`contact_points`| list[PatientContactPoint] or `None`| Patient's contact information| No  
`contacts`| list[PatientContact] or `None`| The patient's contacts — emergency contacts, next-of-kin, and other related persons. See Managing patient contacts| No  
`external_identifiers`| list[PatientExternalIdentifier] or `None`| Patient's external identifiers| No  
`patient_id`| `str` or `None`| Patient id. Optional on creation, where it must be a 32-character hex string (a UUID4 without hyphens); see Supplying a patient id on creation.| For `update()`  
`addresses`| list[PatientAddress] or `None`| Patient's addresses| No  
`preferred_pharmacies`| list[PatientPreferredPharmacy] or `None`| Patient's preferred pharmacies| No  
`metadata`| list[PatientMetadata] or `None`| Patient metadata| No  
##  PatientContactPoint 
The `PatientContactPoint` dataclass represents various methods of contacting the patient.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`system`| `ContactPointSystem`| Type of contact (e.g., phone, email)| Yes  
`value`| `str`| The contact information value (e.g., phone number, email address)| Yes  
`use`| `ContactPointUse`| Purpose of the contact point (e.g., home, work)| Yes  
`rank`| `int`| Priority order of contact methods| Yes  
`has_consent`| `bool` or `None`| Whether consent has been given to use this contact method| No  
> **Info:** If you have already validated a patient's phone or email in a prior workflow, set `has_consent=True` on the `PatientContactPoint` when creating the patient. This marks the contact point as okay to text or email and suppresses the additional 'click here' verification message that Canvas would otherwise send.
##  PatientContact 
The `PatientContact` dataclass represents one of the patient's contacts — an emergency contact, next-of-kin, or other related person.
A contact identifies its person in one of two ways, and you must supply one of them: either **inline** , by giving a `name` (with optional phone, email and comments), or by **reference** , by pointing `related_patient` at another Canvas patient. The reference form is what links two patients to each other, and Canvas displays such a contact from the referenced patient's own record rather than from the contact row.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`name`| `str` or `None`| The contact's name, when the contact holds the person's details inline| One of `name` or `related_patient`  
`related_patient`| `str`, `uuid.UUID` or `None`| The patient id of an existing Canvas patient this contact refers to, used instead of `name`| One of `name` or `related_patient`  
`contact_identifier`| `str`, `uuid.UUID` or `None`| Identifies an existing contact. Omit it to add a contact; supply it to modify or remove one. See Managing patient contacts| No  
`phone_number`| `str` or `None`| The contact's phone number. Exactly 10 digits| No  
`email`| `str` or `None`| The contact's email address| No  
`comments`| `str` or `None`| Free-text notes about the contact| No  
`categories`| list[PatientContactCategory] or `None`| The contact's relationship categories| No  
`inactive`| `bool` or `None`| Set with `contact_identifier` to remove the contact| No  
##  PatientContactCategory 
The `PatientContactCategory` dataclass expresses a contact's relationship to the patient — emergency contact, next-of-kin, and so on — as a coding.
All three fields are required, and the coding must already exist in the instance. Look one up with the [ContactCategory](/sdk/data-patient/#contactcategory) data model rather than composing a coding by hand; a coding the instance does not have raises a validation error instead of being created.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`code`| `str`| The category code (e.g., `"EMC"` for an emergency contact)| Yes  
`code_system`| `str`| The coding system the code belongs to (e.g., `"INTERNAL"`)| Yes  
`name`| `str`| The category's display name (e.g., `"Emergency contact"`)| Yes  
##  PatientExternalIdentifier 
The `PatientExternalIdentifier` dataclass represents an external identifier (ID) associated with the patient. An example would be the unique patient ID for a third party system integrated with Canvas EMR.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`system`| `str`| URL of the system of origin for the external ID (e.g., `http://hl7.org/fhir/sid/us-ssn`)| Yes  
`value`| `str`| The external ID or membership number/value| Yes  
##  PatientAddress 
The `PatientAddress` dataclass represents a patient's address information.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`line1`| `str`| Street address line 1| Yes  
`line2`| `str` or `None`| Street address line 2| No  
`city`| `str`| City name| Yes  
`state_code`| `str`| State code (e.g., "CA", "NY")| Yes  
`postal_code`| `str`| Postal/ZIP code| Yes  
`country`| `str`| Country code| Yes  
`use`| `AddressUse`| Address type (e.g., home, work)| Yes  
> **Warning:** Address updates are **replace-based**. When updating a patient's addresses, the provided address list will completely replace all existing addresses. If you provide an empty list, all existing addresses will be deleted.
##  PatientPreferredPharmacy 
The `PatientPreferredPharmacy` dataclass represents a patient's preferred pharmacy, and if it's their default pharmacy.
Attribute| Type| Description| Required  
---|---|---|---  
`ncpdp_id`| `str`| The ncpdp ID of the pharmacy| Yes  
`default`| `bool`| True if it's the default pharmacy| Yes  
##  PatientMetadata 
The `PatientMetadata` dataclass represents a custom key-value pair for a patient.
Attribute| Type| Description| Required  
---|---|---|---  
`key`| `str`| The key of the metadata| Yes  
`value`| `str`| The value of the metadata| Yes  
##  Implementation Details 
  - Structures contact information through the `PatientContactPoint` dataclass
  - Structures the patient's contacts through the `PatientContact` dataclass, added or modified per entry according to `contact_identifier` — see Managing patient contacts
  - Structures external identifier through the `PatientExternalIdentifier` dataclass
  - Structures address information through the `PatientAddress` dataclass
  - Structures metadata through the `PatientMetadata` dataclass
##  Example Usage 
###  Creating a patient 
    ```python
    from canvas_sdk.effects.patient import Patient, PatientContactPoint, PatientExternalIdentifier, PatientMetadata
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.common import ContactPointSystem, ContactPointUse, PersonSex
    import datetime
    class MyHandler(BaseHandler):
        def compute(self):
            patient = Patient(
                first_name="Jane",
                last_name="Doe",
                middle_name="Marie",
                birthdate=datetime.date(1980, 1, 15),
                sex_at_birth=PersonSex.SEX_FEMALE,
                nickname="Janie",
                default_location_id="location-uuid",
                default_provider_id="provider-uuid",
                contact_points=[
                    PatientContactPoint(
                        system=ContactPointSystem.PHONE,
                        value="555-123-4567",
                        use=ContactPointUse.MOBILE,
                        rank=1,
                        has_consent=True
                    ),
                    PatientContactPoint(
                        system=ContactPointSystem.EMAIL,
                        value="jane.doe@example.com",
                        use=ContactPointUse.WORK,
                        rank=2,
                        has_consent=True
                    )
                ],
                external_identifiers=[
                    PatientExternalIdentifier(
                        system="http://www.aaa.com",
                        value="pat_id_123456"
                    )
                ],
                metadata = [
                    PatientMetadata(key="source", value="plugin"),
                    PatientMetadata(key="created_on", value=datetime.datetime.now().isoformat())
                ]
            )
            return [patient.create()]
    ```
###  Updating a patient 
    ```python
    from canvas_sdk.effects.patient import Patient, PatientAddress, PatientExternalIdentifier
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.common import AddressUse
    class MyHandler(BaseHandler):
        def compute(self):
            # Update an existing patient
            updated_patient = Patient(
                patient_id="existing-patient-uuid",
                first_name="Jane",
                last_name="Smith",  # Changed last name
                addresses=[
                    PatientAddress(
                        line1="456 Updated Street",
                        line2="Suite 200",
                        city="Updated City",
                        state_code="CA",
                        postal_code="90210",
                        country="US",
                        use=AddressUse.HOME
                    )
                ],
                external_identifiers=[
                    PatientExternalIdentifier(
                        system="http://www.updated-system.com",
                        value="new_patient_id_789"
                    )
                ]
            )
            return [updated_patient.update()]
    ```
###  Marking a Patient as Inactive or Deceased 
    ```python
    from canvas_sdk.effects.patient import Patient
    from canvas_sdk.handlers.base import BaseHandler
    import datetime
    class MyHandler(BaseHandler):
        def compute(self):
            # Mark a patient as inactive
            inactive_patient = Patient(
                patient_id="existing-patient-uuid",
                active=False
            )
            return [inactive_patient.update()]
    class DeceasedPatientHandler(BaseHandler):
        def compute(self):
            # Record a patient's death
            deceased_patient = Patient(
                patient_id="existing-patient-uuid",
                deceased=True,
                deceased_datetime=datetime.datetime(2025, 3, 14, 12, 0, 0),
                deceased_cause="Natural causes",
                deceased_comment="Pronounced at home."
            )
            return [deceased_patient.update()]
    ```
##  Supplying a patient id on creation 
By default, Canvas generates the patient id (`patient_id`) when you create a patient. You can supply your own instead by passing a 32-character hex string (a UUID4 with its hyphens removed) in the `patient_id` parameter of `Patient`. This lets your plugin generate the id up front and reuse it for follow-up, patient-scoped effects — such as notes or commands — in the same plugin execution, without reading the id back first. It works the same way Notes and Commands accept a pre-generated id.
A supplied id must be a well-formed patient id: a 32-character lowercase hex string, which is a UUID4 with its hyphens removed. Use `generate_patient_id()` to produce one rather than building the format by hand. An id in any other format — for example, a hyphenated or uppercase UUID — raises a validation error on `create()`, as does an id that already belongs to an existing patient. Since `generate_patient_id()` returns a fresh, well-formed id, it satisfies both requirements. If you omit `patient_id`, the server generates the id as before, so existing plugins are unaffected.
Because you generate the id up front, you can also return it to the caller from a [SimpleAPI](/sdk/handlers-simple-api-http/) endpoint — so a client creating the patient gets the id back in the response instead of having to look it up afterward. This example authenticates with the [`APIKeyAuthMixin`](/sdk/handlers-simple-api-http/), which expects a `simpleapi-api-key` secret declared in your manifest:
    ```python
    from canvas_sdk.effects.patient import Patient, generate_patient_id
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPIRoute
    class CreatePatientAPI(APIKeyAuthMixin, SimpleAPIRoute):
        PATH = "/patients"
        def post(self) -> list[Response]:
            body = self.request.json()
            new_patient_id = generate_patient_id()
            patient = Patient(
                patient_id=new_patient_id,
                first_name=body["first_name"],
                last_name=body["last_name"],
            )
            # `new_patient_id` can be reused for follow-up patient-scoped effects in
            # the same execution, and is returned so the caller has it immediately
            # without a follow-up lookup.
            return [
                patient.create(),
                JSONResponse({"patient_id": new_patient_id}, status_code=201),
            ]
    ```
##  Managing patient contacts 
The `contacts` field writes the patient's contacts — emergency contacts, next-of-kin, and other related persons. What happens to each entry is decided by **`contact_identifier`** , not by whether you called `create()` or `update()`:
`contact_identifier`| `inactive`| Result  
---|---|---  
omitted| omitted| The contact is **added**  
supplied| omitted| The contact it names is **modified**  
supplied| `True`| The contact it names is **removed**  
omitted| `True`| Validation error — there is no contact to remove  
So `Patient(...).update()` adds a contact to a patient that already exists, which is the usual case for a plugin populating contacts after intake. Re-sending an identical contact matches the existing one rather than adding a second, so a handler that re-emits the same contact on every event will not accumulate duplicates. On an update, a `contact_identifier` that names no contact on that patient is treated as a mistake and raises rather than being added.
Contacts you leave out of the list are **left alone**. Unlike `addresses`, this field is not replace-based: omitting a contact never deletes it, and removal is always explicit through `inactive`.
An update writes only the fields you send, so changing a phone number does not blank the email or the comments. `name` (or `related_patient`) is the exception — every contact that is not a removal needs one, so resend the existing value when you are changing something else. Pass an empty string to clear a stored value deliberately.
    ```python
    from canvas_sdk.effects.patient import Patient, PatientContact, PatientContactCategory
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data import ContactCategory
    class MyHandler(BaseHandler):
        def compute(self):
            # Look the coding up rather than composing one — an unknown coding raises.
            emergency = ContactCategory.objects.get(code="EMC")
            category = PatientContactCategory(
                code=emergency.code,
                code_system=emergency.system,
                name=emergency.name,
            )
            # No contact_identifier, so this adds a contact.
            patient = Patient(
                patient_id="existing-patient-id",
                contacts=[
                    PatientContact(
                        name="Jane Doe",
                        phone_number="5551234567",
                        email="jane@example.com",
                        comments="Primary emergency contact",
                        categories=[category],
                    )
                ],
            )
            return [patient.update()]
    ```
###  Linking one patient to another 
Setting `related_patient` to another patient's key makes that patient the contact. Because your plugin can supply the patient id on creation, it knows the key before the patient exists — so it can create a patient and reference it from a later effect in the same execution:
    ```python
    from canvas_sdk.effects.patient import Patient, PatientContact, generate_patient_id
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            spouse_key = generate_patient_id()
            spouse = Patient(
                patient_id=spouse_key,
                first_name="Alex",
                last_name="Doe",
            )
            # References a patient the previous effect creates. Effects are applied in
            # order, so the key resolves by the time this one is written.
            patient = Patient(
                patient_id="existing-patient-id",
                contacts=[
                    PatientContact(
                        related_patient=spouse_key,
                        comments="Spouse — also a patient in Canvas",
                    )
                ],
            )
            return [spouse.create(), patient.update()]
    ```
A `related_patient` contact carries no name of its own; Canvas shows the referenced patient's details instead.
###  Removing a contact 
A removal needs the `contact_identifier` of the contact to remove and nothing else — no name or related patient, since neither is meaningful on a delete. Read the identifier from the [PatientContactPerson](/sdk/data-patient/#patientcontactperson) data model:
    ```python
    from canvas_sdk.effects.patient import Patient, PatientContact
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data import PatientContactPerson
    class MyHandler(BaseHandler):
        def compute(self):
            patient_key = "existing-patient-key"
            contact = PatientContactPerson.objects.filter(
                patient__id=patient_key, name="Jane Doe"
            ).first()
            if contact is None:
                return []
            patient = Patient(
                patient_id=patient_key,
                contacts=[
                    PatientContact(contact_identifier=str(contact.id), inactive=True)
                ],
            )
            return [patient.update()]
    ```
A single `contacts` list may mix all of these — additions, modifications and removals travel together in one effect.
##  Setting Race and Ethnicity 
`biological_race_codes` and `cultural_ethnicity_codes` each accept a list of code strings drawn from the [CDC Race and Ethnicity CodeSystem (CDCREC)](https://hl7.org/fhir/us/core/STU3.1.1/CodeSystem-cdcrec.html) — the same code set used by the [FHIR Patient API](/api/patient/). You can set both fields when creating or updating a patient, and you can supply more than one code per field.
Canvas recognizes the full CDCREC code set — both the OMB top-level categories below and the more specific detailed codes that roll up to them (for example, the race code `2108-9` "European" rolls up to `2106-3` "White", and the ethnicity code `2148-5` "Mexican" rolls up to `2135-2` "Hispanic or Latino"). The categories below are the most common values; see the CodeSystem for the complete list of detailed codes.
**Race** (`biological_race_codes`) — OMB top-level categories:
Code| Description  
---|---  
`1002-5`| American Indian or Alaska Native  
`2028-9`| Asian  
`2054-5`| Black or African American  
`2076-8`| Native Hawaiian or Other Pacific Islander  
`2106-3`| White  
`2131-1`| Other Race  
**Ethnicity** (`cultural_ethnicity_codes`) — OMB top-level categories:
Code| Description  
---|---  
`2135-2`| Hispanic or Latino  
`2186-5`| Not Hispanic or Latino  
    ```python
    from canvas_sdk.effects.patient import Patient
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            patient = Patient(
                patient_id="existing-patient-uuid",
                biological_race_codes=["2106-3"],      # White
                cultural_ethnicity_codes=["2186-5"]    # Not Hispanic or Latino
            )
            return [patient.update()]
    ```
##  Validation 
The effect performs validation before execution to ensure data integrity:
  1. **Required Fields** :
     - For creation: Validates that mandatory fields like `first_name` and `last_name` are provided
     - For updates: Requires `patient_id` to be provided and verifies the patient exists in the database
  2. **Referenced Entity Validation** : Confirms that any referenced entities exist in the system:
     - Verifies that the specified default practice location exists
     - Ensures that the specified default provider exists
  3. **Data Format Validation** : Ensures that provided values conform to expected formats:
     - Date fields must be valid dates
     - Enumerated types like `PersonSex`, `ContactPointSystem`, and `ContactPointUse` must contain valid values
     - On creation, if `patient_id` is supplied it must be a well-formed patient id (a 32-character hex string); otherwise validation raises
     - On creation, a supplied `patient_id` must not already belong to an existing patient; a duplicate id raises a validation error
  4. **Update-Specific Validation** :
     - Validates that the patient exists before attempting updates
  5. **Contact Validation** (see Managing patient contacts):
     - Every contact that is not a removal must carry either `name` or `related_patient`
     - A removal (`inactive=True`) must carry `contact_identifier`
     - `contact_identifier` and `related_patient` must be UUIDs; on an update, `contact_identifier` must name a contact that belongs to this patient, and `related_patient` must name an existing patient
     - `phone_number` must be exactly 10 digits, and `email` must be a valid email address
     - `PatientContactCategory` requires `code`, `code_system` and `name`, and the coding must already exist in the instance — an unknown coding raises rather than being created

---

# Phone Dial Configuration Effect

Source: https://docs.canvasmedical.com/sdk/effect-phone-dial-configuration/

The `PhoneDialConfiguration` effect turns the phone numbers in a patient chart into clickable links — the click-to-dial affordance. It lets a user click to dial a number, or hand it to a softphone, directly from the chart. Return it in response to the [`PHONE_DIAL__GET_CONFIGURATION`](/sdk/events/#phone-dial-configuration) event, which Canvas fires as a chart loads its phone numbers.
Import the effect and its enums from the submodule:
    ```python
    from canvas_sdk.effects.phone_dial_configuration import (
        PhoneDialClickHandling,
        PhoneDialConfiguration,
        PhoneDialSection,
    )
    ```
Build a `PhoneDialConfiguration` with the attributes you want to set, then return its `apply()` from your handler.
* * *
##  Methods 
###  apply() → Effect 
Makes the listed sections' numbers clickable.
  - `clickable_sections` is required, with at least one section.
##  How it works 
As a patient chart loads phone numbers, Canvas fires `PHONE_DIAL__GET_CONFIGURATION`. A handler subscribed to the event returns one or more `PhoneDialConfiguration` effects, each naming the chart sections it makes clickable and how a click on those sections is handled. If no plugin returns a configuration, every number renders as plain text, except the patient header's primary number when your instance has Dialing Service settings configured. See Dialing Service settings below.
A single effect carries one `click_handling` mode that applies to every section it lists. To handle sections differently — some dialed by the device, some by your plugin — return one effect per handling mode.
A click is either dialed by the device or handed to your plugin, depending on the `click_handling` mode the effect carries.
Two categories of numbers are never affected by this configuration: sections you do not list render as plain text, and fax numbers are always plain text regardless of configuration.
When more than one plugin responds, Canvas merges their configurations:
  - A section is clickable if any plugin lists it.
  - A section is plugin-driven if any plugin asks for `PLUGIN` on it.
  - Among the remaining configurations, the first one that names a `dial_label` supplies the label.
##  Dialing Service settings 
Click-to-dial also exists as an instance setting, independent of any plugin. When both `DIALING_LABEL` and `DIALING_URL_TEMPLATE` are set under Dialing Service, the patient header's primary number becomes clickable on its own, dialed by the device and labeled with `DIALING_LABEL`. Those settings reach only the patient header, so no other section is affected by them.
> **Warning:** A plugin that answers `PHONE_DIAL__GET_CONFIGURATION` replaces the Dialing Service settings rather than adding to them. A responding plugin speaks for every section, including the ones it leaves out, so the patient header stops using `DIALING_URL_TEMPLATE` even if your configuration never mentions the patient section. To keep that behavior, list the patient section in your own configuration.
##  Event payload 
Property| Value| Description  
---|---|---  
`event.target.id`| `str` (UUID)| The id of the [Patient](/sdk/data-patient/#patient) whose chart is loading phone numbers.  
`event.actor`| user| The [logged-in user](/sdk/events/#event-actor) viewing the chart, when available.  
`event.context`| `{}`| Empty — no additional context is provided.  
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`clickable_sections`| list[PhoneDialSection]| The chart sections whose numbers become clickable. Provide at least one — an empty list is rejected.| Yes  
`click_handling`| PhoneDialClickHandling| How a click on the listed sections is handled. Defaults to `DEVICE`.| No  
`dial_label`| `str` | `None`| A display affordance only. When `dial_label` is set, the section shows the number plus a "Dial number with `<label>`" button. When it isn't, the number itself is the link. Where the call actually goes is still the click handler's decision, not the configuration's. Defaults to `None`.| No  
###  PhoneDialSection 
The chart sections you can make clickable:
Member| Value  
---|---  
`PhoneDialSection.PATIENT`| `"patient"`  
`PhoneDialSection.CONTACT`| `"contact"`  
`PhoneDialSection.EXTERNAL_CARE_TEAM`| `"external_care_team"`  
###  PhoneDialClickHandling 
How a click is handled:
Member| Value| What a click does  
---|---|---  
`PhoneDialClickHandling.DEVICE`| `"device"`| Opens a `tel:` link that the device's phone app handles. Your plugin does nothing beyond declaring the section.  
`PhoneDialClickHandling.PLUGIN`| `"plugin"`| Opens nothing locally. Your handler decides what happens, using the [`PHONE_NUMBER_CLICKED`](/sdk/events/#phone-dial-configuration) event.  
`PHONE_NUMBER_CLICKED` fires under either mode, so a plugin can observe clicks even on device-dialed sections.
##  Example 
This handler makes three sections clickable with different handling: contact numbers go to your plugin behind a "Dial number with Zoom" button, patient numbers go to your plugin as a plain link, and external-care-team numbers are dialed by the device.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.phone_dial_configuration import (
        PhoneDialClickHandling,
        PhoneDialConfiguration,
        PhoneDialSection,
    )
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class ConfigurePhoneDialing(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PHONE_DIAL__GET_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [
                PhoneDialConfiguration(
                    clickable_sections=[PhoneDialSection.CONTACT],
                    click_handling=PhoneDialClickHandling.PLUGIN,
                    dial_label="Zoom",
                ).apply(),
                PhoneDialConfiguration(
                    clickable_sections=[PhoneDialSection.PATIENT],
                    click_handling=PhoneDialClickHandling.PLUGIN,
                ).apply(),
                PhoneDialConfiguration(
                    clickable_sections=[PhoneDialSection.EXTERNAL_CARE_TEAM],
                    click_handling=PhoneDialClickHandling.DEVICE,
                ).apply(),
            ]
    ```
###  Dial a plugin-handled section 
A `PLUGIN` section does not dial anything on its own — the click only fires `PHONE_NUMBER_CLICKED`. To send the number to a softphone, subscribe to that event and return a [Redirect](/sdk/effect-redirect/) effect that navigates to the softphone's dial URL. `PHONE_NUMBER_CLICKED` carries the clicking user as `event.actor`, so the redirect has a browser to navigate — see [Event Actor](/sdk/events/#event-actor). The click event's context carries the number as `phone_number` and the chart section it came from as `source`, which is one of `patient`, `contact` or `external_care_team`, matching `PhoneDialSection`. Read it with `.get("source")` rather than indexing, since the key is left out when no section is sent.
> **Warning:** Set `target` to `RedirectEffect.TargetType.SAME_TAB` — the only usable target here. The redirect arrives over a subscription rather than inside the click, so a `NEW_TAB` target would be treated as an unrequested popup and blocked.
> **Warning:** The dial URL must be listed in the plugin's `REDIRECT_ALLOWLIST_EXTERNAL` secret. An unset allowlist denies everything. An entry needs both a scheme and a host, so authority-style URIs work (`zoomus://`, `msteams://`, `rcmobile://`, `https://`) but scheme-only URIs are rejected (`sip:`, `callto:`, `skype:`, `sms:`). A `tel:` link is unaffected because `DEVICE` handling opens it natively rather than through a redirect.
This handler reads the base of your softphone's dial URL from a plugin secret named `ZOOM_DIAL_URL_BASE`, rather than hard-coding it, then composes the dial URL with an f-string. Set that secret to the value from your Zoom Phone account.
    ```python
    from urllib.parse import quote
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.redirect import RedirectEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class DialClickedNumber(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PHONE_NUMBER_CLICKED)
        def compute(self) -> list[Effect]:
            zoom_dial_url_base = self.secrets["ZOOM_DIAL_URL_BASE"]
            phone_number = self.event.context["phone_number"]
            # source names the chart section the click came from, e.g. "contact".
            source = self.event.context.get("source")
            return [
                RedirectEffect(
                    url=f"{zoom_dial_url_base}?number={quote(phone_number)}",
                    target=RedirectEffect.TargetType.SAME_TAB,
                ).apply()
            ]
    ```
Declare both keys under `variables` in your plugin's [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#variables) so an admin can set them — an undeclared variable has nowhere to receive a value, so the secret read and the redirect both fail silently:
    ```json
    {
      "variables": [
        { "name": "REDIRECT_ALLOWLIST_EXTERNAL" },
        { "name": "ZOOM_DIAL_URL_BASE" }
      ]
    }
    ```
Add `zoomus://` (or your softphone's scheme and host) to `REDIRECT_ALLOWLIST_EXTERNAL` so the redirect is permitted. See [Redirect](/sdk/effect-redirect/#security--allowlist) for how the allowlist is declared and set.

---

# Protocol Card

Source: https://docs.canvasmedical.com/sdk/effect-protocol-cards/

Protocol cards appear on the right-hand-side of a patient's chart, and can be accessed by clicking on the Protocols filter button in the filter menu.
![protocol card](/assets/images/protocol-card.png)
A Protocol card consists of three main parts:
  - A title, which appears at the top in bold
  - A narrative, which appears just below the title to add any additional clarifying information
  - A list of recommendations, which each have a title and optionally a button that can either:
    - open a new tab and navigate to another site
    - insert commands into a note
Build a `ProtocolCard` with the attributes you want to set, add any recommendations, then return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Creates the protocol card, or updates the existing card with the same patient and `key`.
  - `key` is required.
  - Exactly one of `patient_id` or `patient_filter` is required.
  - The existing card is matched on patient, `key`, and the plugin that sends it, so two plugins using the same `key` each get their own card.
  - Re-applying replaces every field on the card. To change a card's `status`, for example from `DUE` to `SATISFIED`, send the whole card again with the new status.
###  add_recommendation(title: str = "", button: str = "", href: str | None = None, commands: list | None = None) → None 
Appends a recommendation to the card's `recommendations`.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`patient_id`| `str`| The id of the [patient](/sdk/data-patient/).| One of `patient_id` or `patient_filter`  
`patient_filter`| `dict`| A [patient filter](/sdk/effect-banner-alerts/#patient-filters) that applies the effect to every matching patient. For example, `{"active": True}` applies the effect to all active patients.| One of `patient_id` or `patient_filter`  
`key`| `str`| A unique identifier for the protocol card.| Yes  
`title`| `str`| The title for the protocol card, which appears at the top in bold.| No  
`narrative`| `str`| The narrative for the protocol card, which appears just below the title.| No  
`can_be_snoozed`| `bool`| Whether the protocol card can be snoozed. Defaults to `False`.| No  
`status`| `Status`| The status of the protocol card. Defaults to `Status.DUE`.| No  
`recommendations`| `list[``Recommendation``]`| The recommendations to appear in the protocol card.| No  
`feedback_enabled`| `bool`| Whether users can provide feedback for the protocol card in Settings. Defaults to `False`.| No  
`due_in`| `int`| The number of days until the protocol card will be considered due for the patient. Defaults to `-1`, already due.| No  
##  Recommendation 
Attribute| Type| Description| Required  
---|---|---|---  
`title`| `str`| The description of the recommendation| No  
`button`| `str`| The text to appear on the button| No  
`href`| `str`| The url for the button to navigate to| No  
`commands`| list[[Command](/sdk/commands/)]| The commands to be inserted| No  
##  Status 
Enum| Value  
---|---  
`DUE`| due  
`SATISFIED`| satisfied  
`NOT_APPLICABLE`| not_applicable  
`PENDING`| pending  
`NOT_RELEVANT`| not_relevant  
##  Example 
To include a command recommendation you can:
  - import the command from the [commands module](/sdk/commands/), instantiate the command with all the values you wish to populate, and then call `.recommend(title: str = "", button: str | None)` on the command to generate the recommendation that you can append to the protocol card's recommendations. Any command can be inserted; see Supported Commands.
  - instantiate the command as above, and then pass it in a list to the `commands` attribute of a recommendation.
</br> </br>
For non-command recommendations, you can either use the `Recommendation` class, or the `.add_recommendation(title: str = "", button: str = "", href: str | None)` method on the protocol card.
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from datetime import date
    from canvas_sdk.effects.protocol_card import ProtocolCard, Recommendation
    from canvas_sdk.commands import AssessCommand, PlanCommand
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_UPDATED)
        def compute(self):
            assess = AssessCommand(
                icd10_code="I10",
                background="feeling bad for many years",
                approximate_date_of_onset=date(2020, 1, 1),
                narrative="still not great",
            )
            plan = PlanCommand(
                narrative="Follow up in 2 weeks",
            )
            p = ProtocolCard(
                patient_id=self.target,
                key="testing-protocol-cards",
                title="This is a ProtocolCard title",
                narrative="this is the narrative",
                status=ProtocolCard.Status.DUE,
                recommendations=[
                  Recommendation(title="this recommendation has no action, just words!"),
                  Recommendation(title="this recommendation inserts multiple commands", button="add commands", commands=[assess, plan])
                ],
            )
            p.add_recommendation(
                title="this is a recommendation", button="go here", href="https://canvasmedical.com/"
            )
            p.recommendations.append(assess.recommend(title="this inserts an assess command"))
            p.recommendations.append(title="new recommendation", button="start", commands=[assess])
            return [p.apply()]
    ```
To apply the effect to all active patients on plugin create and plugin update, you would include the plugin create and update events in `RESPONDS_TO`. And when responding to one of the plugin events you would use `patient_filter` instead of `patient_id` for the ProtocolCard.
    ```python
    from canvas_sdk.effects.protocol_card import ProtocolCard, Recommendation
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from datetime import date
    from canvas_sdk.effects.protocol_card import ProtocolCard, Recommendation
    from canvas_sdk.commands import AssessCommand
    class MyHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.PATIENT_UPDATED),
            EventType.Name(EventType.PLUGIN_CREATED),
            EventType.Name(EventType.PLUGIN_UPDATED),
        ]
        def compute(self):
            p = ProtocolCard(
                key="testing-protocol-cards",
                title="This is a ProtocolCard title",
                narrative="this is the narrative",
                can_be_snoozed=True,
                recommendations=[
                    Recommendation(title="this recommendation has no action, just words!")
                ],
            )
            p.add_recommendation(
                title="this is a recommendation", button="go here", href="https://canvasmedical.com/"
            )
            assess = AssessCommand(
                icd10_code="I10",
                background="feeling bad for many years",
                approximate_date_of_onset=date(2020, 1, 1),
                narrative="still not great",
            )
            p.recommendations.append(assess.recommend(title="this inserts an assess command"))
            if self.event.type in [EventType.PLUGIN_CREATED, EventType.PLUGIN_UPDATED]:
                p.patient_filter = {"active": True}
            else:
                p.patient_id = self.target
            return [p.apply()]
    ```
##  Supported Commands 
Any command in the [commands module](/sdk/commands/) can be inserted from a protocol card recommendation.
Validate Coding Gap has no class in the commands module. Recommend it with `add_recommendation(command="validateCodingGap", context={"detected_issue_id": ...})`, passing the coding gap's [DetectedIssue](/sdk/data-detected-issue/#detectedissue) `dbid`. The inserted command opens with that detected issue selected. See [Improve HCC Coding Accuracy](/guides/improve-hcc-coding-accuracy/) for a full plugin.
    ```python
    card.add_recommendation(
        title="E11.9 (Type 2 diabetes)",
        button="Validate",
        command="validateCodingGap",
        context={"detected_issue_id": coding_gap.dbid},
    )
    ```
> **Info:** Commands inserted from a protocol card recommendation populate their fields the same way as a command originated directly from a plugin — the values you set when instantiating the command (for example `image_code`, `diagnosis_codes`, `comment`) carry through to the inserted command.

---

# Questionnaires

Source: https://docs.canvasmedical.com/sdk/effect-questionnaires/

Questionnaires are a structured set of questions that guide collecting answers from end users. A plugin can ship one with its manifest, create one while it runs, and score a completed one.
##  Creating a Questionnaire 
There are two ways to create a questionnaire, and both describe it with the same field reference:
  - **A manifest YAML template** — the simplest path when the questionnaire's shape is fixed as you build the plugin. Define the template and reference it in your [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#questionnaires) file.
  - **The`CreateQuestionnaire` effect** — for a shape that is not fixed at build time, such as one assembled from external data, user input, or per-instance configuration. Also the path to take when the questions change often enough that a plugin release per change is impractical.
    - This is the route to pair with a [SimpleAPI](/sdk/handlers-simple-api-http/) route to stand up your own create-questionnaire endpoint, where a caller posts the questionnaire it wants and your plugin publishes it. See Publishing from a SimpleAPI route.
###  Field reference 
Both paths describe the same questionnaire and the same JSON schema validates both. In a manifest template these keys are YAML; in Python they are the `QuestionnaireConfig` dictionary the effect takes.
`QuestionnaireConfig` is a `TypedDict`, so a plain dictionary satisfies it and the import is only needed to annotate the definition you build. `Question`, `Response`, and `EnabledCondition` annotate the nested levels:
    ```python
    from canvas_sdk.questionnaires.utils import (
        EnabledCondition,
        Question,
        QuestionnaireConfig,
        Response,
    )
    ```
These are the config shapes, not the data models. `Question` here is the question you are about to write, while [Question](/sdk/data-questionnaire/#question) in `canvas_sdk.v1.data` is a question already saved, so importing both in one file needs an alias.
Two rules hold at every level, on both paths:
  - **Unknown keys are rejected** , rather than dropped. A misspelled key fails validation instead of silently losing the setting it was meant to carry.
  - **Types are matched strictly.** A score is the string `"0"` rather than the integer `0`, which is why the YAML examples below quote their values.
####  Top level 
Key| Required| Type| Description  
---|---|---|---  
`name`| Yes| str| Name of the questionnaire, up to 241 characters. The limit leaves room for the `<name> (v<id>)` rename a supersede applies.  
`form_type`| Yes| str| One of the form types.  
`code_system`| Yes| str| One of the code systems.  
`code`| Yes| str| The code for the questionnaire, up to 100 characters, for example `72109-2`.  
`can_originate_in_charting`| Yes| bool| Whether a user can start this questionnaire from charting.  
`questions`| Yes| list| At least one question.  
`prologue`| No| str| Text shown at the start of the questionnaire, for context.  
`display_results_in_social_history_section`| No| bool| Whether completion shows in the Social History section. Defaults to `False`.  
####  questions[] 
Key| Required| Type| Description  
---|---|---|---  
`code_system`| Yes| str| One of the code systems.  
`code`| Yes| str| The code for the question, up to 100 characters and non-empty. A question's coding, `code_system` plus `code`, must be unique within the questionnaire.  
`content`| Yes| str| The question text, up to 1024 characters.  
`responses_code_system`| Yes| str| One of the code systems.  
`responses_type`| Yes| str| One of the response types.  
`responses`| Yes| list| At least one response.  
`code_description`| No| str| A description of the code, up to 255 characters.  
`display_result_in_social_history_section`| No| bool| Whether this answer shows in the Social History section. Defaults to `False`.  
`enabled_behavior`| No| str| One of the enablement behaviors, when the question carries more than one condition.  
`enabled_conditions`| No| list| Conditions that enable this question.  
####  responses[] 
Key| Required| Type| Description  
---|---|---|---  
`name`| Yes| str| Up to 1024 characters. The displayed text for `SING` and `MULT`. Use `"TXT"` on a `TXT` question and `"DATE"` on a `DATE` question.  
`code`| Yes| str| Up to 100 characters. Must be non-empty and unique within the question, except on `TXT` and `DATE`.  
`code_description`| No| str| A description of the code, up to 255 characters.  
`value`| No| str| Up to 1000 characters. The score for `SING` and `MULT`, or default text for `TXT`. Not used for `DATE`.  
A `TXT` or `DATE` question still needs exactly one entry in `responses`, carrying a placeholder: `{"name": "TXT", "code": "<code>"}` or `{"name": "DATE", "code": "<code>"}`. A placeholder response is exempt from the response-code rules, both the non-empty check and the uniqueness check.
`value` is the score for a single answer, not a total. Canvas stores it against the response and does not add anything up, so turning a completed questionnaire into a score on the chart means summing the answers yourself and emitting CreateQuestionnaireResult.
On a `TXT` question, `value` carries default text for the answer rather than a score, so it is how you prompt the person answering. A Review of Systems or Physical Exam note then lists that answer only once it differs from the default. Give the placeholder response a `value` to use this:
    ```python
    {
        "content": "Describe anything else you would like us to know",
        "code_system": "INTERNAL",
        "code": "other-notes",
        "responses_code_system": "INTERNAL",
        "responses_type": "TXT",
        "responses": [
            {"name": "TXT", "code": "other-notes-text", "value": "No additional concerns"},
        ],
    }
    ```
**Question toggle default:** For Physical Exam (`EXAM`) questionnaires, the per-question enable/disable toggle cannot be set to default-untoggled through the YAML (setting the response `value` to `0` does not control the toggle). To start a question toggled off, set up a plugin that listens for the command origination event and uses the [toggle-questions feature](/sdk/commands/#toggle-questions-feature) to disable the question.
####  enabled_conditions[] 
Key| Required| Type| Description  
---|---|---|---  
`question_code`| Yes| str| The `code` of the question whose answer is tested. It must match exactly one question in this questionnaire.  
`operator`| Yes| str| One of the enablement operators.  
`value_code`| No| str or None| The response `code` to match, for a `SING` or `MULT` question.  
`value_string`| No| str or None| A free text value to match, up to 255 characters.  
A condition names its question by bare `code`, with no code system, so two questions sharing a code under different code systems make the reference ambiguous and validation rejects it.
Pair `=` and `!=` with `value_code` on a `SING` or `MULT` question, or with `value_string` on a `TXT` one. `exists` and `not_exists` take neither, since they test only whether the question was answered:
    ```python
    # Enable when an earlier question was answered "Yes".
    {"question_code": "travel-recent", "operator": "=", "value_code": "travel-recent-yes"}
    # Enable for every answer except "None".
    {"question_code": "symptoms", "operator": "!=", "value_code": "symptoms-none"}
    # Enable once the earlier question has an answer, whatever it is.
    {"question_code": "current-medications", "operator": "exists"}
    # Enable only while the earlier question is unanswered.
    {"question_code": "pharmacy-preference", "operator": "not_exists"}
    # Enable when a free text answer matches exactly.
    {"question_code": "employment-status", "operator": "=", "value_string": "Retired"}
    ```
A question carrying more than one condition needs `enabled_behavior` to pick between them. Here a `MULT` symptoms question feeds two conditions, and either one is enough:
    ```python
    {
        "content": "How long have you had these symptoms?",
        "code_system": "INTERNAL",
        "code": "symptom-duration",
        "responses_code_system": "INTERNAL",
        "responses_type": "SING",
        "responses": [
            {"name": "Under a week", "code": "symptom-duration-short", "value": "0"},
            {"name": "A week or more", "code": "symptom-duration-long", "value": "1"},
        ],
        # "all" would require the patient to have reported both a cough and a fever.
        "enabled_behavior": "any",
        "enabled_conditions": [
            {"question_code": "symptoms", "operator": "=", "value_code": "symptoms-cough"},
            {"question_code": "symptoms", "operator": "=", "value_code": "symptoms-fever"},
        ],
    }
    ```
Every `question_code` and `value_code` above has to resolve inside the same questionnaire. A `value_code` that is not a response of the question it names is rejected when the effect is applied, rather than quietly dropping the branching.
####  Value sets 
The tables above reference these by name. They are enforced by the JSON schema, so an unlisted value is rejected when the effect is applied.
#####  Code systems 
Taken by `code_system` at both the questionnaire and question level, and by `responses_code_system`.
Value| Meaning  
---|---  
`SNOMED`| SNOMED CT codes.  
`LOINC`| LOINC codes.  
`ICD-10`| ICD-10 codes.  
`CPT`| CPT codes.  
`INTERNAL`| A coding of your own, when the questionnaire has no code from a published system.  
#####  Form types 
Value| Meaning  
---|---  
`QUES`| Questionnaire.  
`SA`| Structured assessment.  
`EXAM`| Physical exam.  
`ROS`| Review of systems.  
#####  Response types 
Value| Answer  
---|---  
`SING`| Single select. One response from `responses`.  
`MULT`| Multi select. One or more responses from `responses`.  
`TXT`| Free text. Takes a single placeholder response.  
`DATE`| A calendar date, entered as `YYYY-MM-DD`. Takes a single placeholder response.  
The [question types](/sdk/data-questionnaire/#question-types) a saved question can carry also include `INT` and `DEC`. Neither is in this value set, so a questionnaire created through the effect cannot use them.
#####  Enablement operators 
Value| Condition is met when  
---|---  
`=`| the answer matches `value_code` or `value_string`.  
`!=`| the answer does not match `value_code` or `value_string`.  
`exists`| the question has any answer.  
`not_exists`| the question has no answer.  
#####  Enablement behaviors 
Value| Meaning  
---|---  
`all`| Every condition must be met.  
`any`| One condition is enough.  
###  Manifest YAML template 
Shipping a questionnaire with your plugin takes two files: the YAML template that defines it, and the manifest entry that points at it.
    ```text
    example_questionnaire/
    ├── CANVAS_MANIFEST.json
    └── templates/
        └── example_questionnaire.yml
    ```
####  The template file 
`templates/example_questionnaire.yml` holds the questionnaire itself, written with the keys in the field reference. This one has a single select, a multi select, a free text and a date question:
    ```yaml
    name: Example Name
    form_type: QUES
    code_system: LOINC
    code: QUES_EXAMPLE_NAME
    can_originate_in_charting: true
    prologue: This is an example of a structured assessment with single select, multiselect, free text, and date responses.
    questions:
      - content: "This is question #1"
        code_system: CPT
        code: H0005
        responses_code_system: INTERNAL
        responses_type: SING
        display_result_in_social_history_section: true
        responses:
          - name: "Single select response #1"
            code: QUES_EXAMPLE_NAME_Q1_A1
            value: "1"
          - name: "Single select response #2"
            code: QUES_EXAMPLE_NAME_Q1_A2
            value: "0"
          - name: "Single select response #3"
            code: QUES_EXAMPLE_NAME_Q1_A3
            value: "0"
      - content: "This is question #2"
        code_system: INTERNAL
        code: QUES_EXAMPLE_NAME_Q2
        responses_code_system: ICD-10
        responses_type: MULT
        display_result_in_social_history_section: true
        responses:
          - name: "Multi select response #1"
            code: F1910
            value: "0"
          - name: "Multi select response #2"
            code: QUES_EXAMPLE_NAME_Q1_A1
            value: "2"
          - name: "Multi select response #3"
            code: QUES_EXAMPLE_NAME_Q1_A2
            value: "0"
      - content: "This is question #3"
        code_system: INTERNAL
        code: QUES_EXAMPLE_NAME_Q3
        responses_code_system: INTERNAL
        responses_type: TXT
        display_result_in_social_history_section: true
        responses:
          - name: "Free text response"
            code: QUES_EXAMPLE_NAME_Q3_A1
            value: "This is a default pre-populated free text response."
      - content: "This is question #4"
        code_system: INTERNAL
        code: QUES_EXAMPLE_NAME_Q4
        responses_code_system: INTERNAL
        responses_type: DATE
        display_result_in_social_history_section: true
        responses:
          - name: "DATE"
            code: QUES_EXAMPLE_NAME_Q4_A1
    ```
The [JSON schema](https://raw.githubusercontent.com/canvas-medical/canvas-plugins/main/schemas/questionnaire.json) is the authority on these keys.
####  Referencing it from the manifest 
Add the template's path to the `questionnaires` section of `CANVAS_MANIFEST.json`. `template` is relative to the plugin package:
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "example_questionnaire",
        "description": "Ships a structured assessment questionnaire.",
        "components": {
            "handlers": [],
            "commands": [],
            "content": [],
            "effects": [],
            "views": [],
            "questionnaires": [
                {
                    "template": "templates/example_questionnaire.yml"
                }
            ]
        },
        "variables": [],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
####  Example with branching 
A template using `enabled_conditions` to show questions only once an earlier answer calls for them:
    ```yaml
    name: Branching Example
    form_type: QUES
    code_system: INTERNAL
    code: QUES_BRANCHING_EXAMPLE
    can_originate_in_charting: true
    prologue: This questionnaire demonstrates conditional logic with enabled_conditions and enabled_behavior.
    questions:
      - content: "Do you have any allergies?"
        code_system: INTERNAL
        code: QUES_BRANCH_Q1
        responses_code_system: INTERNAL
        responses_type: SING
        responses:
          - name: "Yes"
            code: QUES_BRANCH_Q1_YES
          - name: "No"
            code: QUES_BRANCH_Q1_NO
      - content: "Please describe your allergies"
        code_system: INTERNAL
        code: QUES_BRANCH_Q2
        responses_code_system: INTERNAL
        responses_type: TXT
        enabled_conditions:
          - question_code: QUES_BRANCH_Q1
            operator: "="
            value_code: QUES_BRANCH_Q1_YES
        responses:
          - name: "TXT"
            code: QUES_BRANCH_Q2_A1
      - content: "How severe are your allergies?"
        code_system: INTERNAL
        code: QUES_BRANCH_Q3
        responses_code_system: INTERNAL
        responses_type: SING
        enabled_behavior: all
        enabled_conditions:
          - question_code: QUES_BRANCH_Q1
            operator: "="
            value_code: QUES_BRANCH_Q1_YES
          - question_code: QUES_BRANCH_Q2
            operator: exists
        responses:
          - name: "Mild"
            code: QUES_BRANCH_Q3_MILD
          - name: "Moderate"
            code: QUES_BRANCH_Q3_MODERATE
          - name: "Severe"
            code: QUES_BRANCH_Q3_SEVERE
    ```
In this example:
  - **Q1** is always visible.
  - **Q2** only appears if Q1 is answered "Yes" (using `=` with `value_code`).
  - **Q3** only appears if Q1 is "Yes" **and** Q2 has been answered (using `enabled_behavior: all` with two conditions).
Only the comparison operators `=`, `!=`, `exists`, and `not_exists` are supported. Numeric comparison operators (`<`, `>`, `<=`, `>=`) are not supported because question responses are stored as strings (free text, single select, and multi select), so there are no numeric values to compare.
####  Loading a definition from YAML 
`questionnaire_from_yaml` reads a template out of your plugin package and returns it as a `QuestionnaireConfig`, validated against the schema on the way:
    ```python
    from canvas_sdk.questionnaires import questionnaire_from_yaml
    config = questionnaire_from_yaml("templates/example_questionnaire.yml")
    ```
A leading `/` on the path is stripped during resolution. It raises `FileNotFoundError` when the file is not in the plugin, `PermissionError` when the path resolves outside the plugin directory, and a `ValidationError` when the template does not match the schema.
Because it returns the shape the effect takes, a template can seed a questionnaire built at runtime: load it, adjust it in Python, and hand it to the CreateQuestionnaire effect.
###  CreateQuestionnaire Effect 
Creates a questionnaire while your plugin runs.
    ```python
    from canvas_sdk.effects.questionnaire import CreateQuestionnaire
    ```
Build a `CreateQuestionnaire` with the questionnaire definition, then return its `apply()` from your handler:
    ```python
    CreateQuestionnaire(questionnaire=config).apply()
    ```
####  Methods 
#####  apply() → Effect 
Creates the questionnaire, superseding any questionnaire with the same name (see Versioning).
  - `questionnaire` is required, and must pass the checks under Validation.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`questionnaire`| QuestionnaireConfig| The questionnaire definition to create.| Yes  
####  Validation 
Call `.apply()` to emit the effect. Validation runs at that point and raises one pydantic `ValidationError` listing every problem it found, rather than stopping at the first.
Beyond the JSON schema, it checks that:
  - Each question's coding (`code_system` plus `code`) is unique within the questionnaire, and each response `code` is unique within its question. Question and response codes are also non-empty, since branching logic attaches to them. `TXT` and `DATE` responses carry a placeholder code and are exempt from the response-code rules.
  - Every `enabled_conditions` entry resolves within the same questionnaire: its `question_code` matches exactly one question, and its `value_code`, when present, is a response of that question.
  - `name` is at most 241 characters, leaving room to rename a superseded questionnaire `<name> (v<id>)` within the 255-character column.
Validation runs plugin-side because a failure raised on the Canvas server goes to Sentry rather than back to your plugin. For the same reason, a clean `.apply()` is not confirmation that the questionnaire was created.
There is also no event to wait on: no [event type](/sdk/events/) fires when a questionnaire is created or updated. `INTERVIEW_CREATED` and `INTERVIEW_UPDATED` cover a questionnaire being filled out rather than the questionnaire itself, and the `QUESTIONNAIRE_COMMAND__*` events cover the command in a note. To confirm a questionnaire was created, read `canvas logs`, or query it back through the [Questionnaire](/sdk/data-questionnaire/) data model with `Questionnaire.objects.filter(name=...)`.
####  Versioning 
Questionnaire names are globally unique, so emitting the effect with a name already in use:
  - archives the existing questionnaire and renames it `<name> (v<id>)`,
  - then creates a new questionnaire in its place.
Each emission publishes a new version rather than editing the current one, so repeated emissions leave a chain of superseded versions. That is what keeps completed interviews intact: their responses stay attached to the questions they were answered against, which editing a questionnaire in place would change underneath them.
> **Warning:** Drive this effect from an explicit trigger, such as a SimpleAPI route. A handler on a recurring event supersedes the questionnaire every time it fires.
To read the branching logic back after publishing, see the [Question](/sdk/data-questionnaire/#question) and [QuestionEnablementCondition](/sdk/data-questionnaire/#questionenablementcondition) data models.
####  Examples 
#####  Branching on an earlier answer 
`enabled_conditions` wires a question to an answer given earlier in the same questionnaire. Here the second question appears only once the first is answered "Yes":
    ```python
    questions = [
        {
            "content": "Have you traveled outside the country in the last 30 days?",
            "code_system": "INTERNAL",
            "code": "travel-recent",
            "responses_code_system": "INTERNAL",
            "responses_type": "SING",
            "responses": [
                {"name": "Yes", "code": "travel-recent-yes"},
                {"name": "No", "code": "travel-recent-no"},
            ],
        },
        {
            "content": "Which countries did you visit?",
            "code_system": "INTERNAL",
            "code": "travel-countries",
            "responses_code_system": "INTERNAL",
            "responses_type": "TXT",
            "responses": [{"name": "TXT", "code": "travel-countries-text"}],
            "enabled_conditions": [
                {
                    "question_code": "travel-recent",
                    "operator": "=",
                    "value_code": "travel-recent-yes",
                },
            ],
        },
    ]
    ```
See enabled_conditions[] for the other operators and for a question gated on more than one condition.
#####  Publishing from a SimpleAPI route 
A [SimpleAPI](/sdk/handlers-simple-api-http/) route gives you a create-questionnaire endpoint of your own: the caller posts a shape you define, and the route translates it. Canvas's schema stays on your side of the boundary, and changing the questions becomes a different request body rather than a plugin release.
This route takes a title, a code, and a list of questions:
    ```json
    {
      "title": "Daily Wellness Check",
      "code": "daily-wellness-check",
      "questions": [
        {
          "prompt": "How are you feeling today?",
          "choices": ["Good", "Not good"]
        },
        {
          "prompt": "Anything else you would like us to know?",
          "type": "text"
        }
      ]
    }
    ```
Each question in the body becomes a question in the config, with its choices scored by position and codes generated as it goes. [`APIKeyAuthMixin`](/sdk/handlers-simple-api-http/#api-key) handles authentication, which needs a `simpleapi-api-key` secret declared in the manifest and set on the instance:
    ```python
    from typing import Any
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.questionnaire import CreateQuestionnaire
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPIRoute
    from canvas_sdk.questionnaires.utils import Question, QuestionnaireConfig
    class PublishQuestionnaire(APIKeyAuthMixin, SimpleAPIRoute):
        PATH = "/publish-questionnaire"
        def post(self) -> list[Response | Effect]:
            try:
                config = self._build_config(self.request.json())
                # A pydantic ValidationError subclasses ValueError, so the except below returns the
                # caller a 400 naming the problem instead of letting it fail out of sight on the
                # Canvas side.
                effect = CreateQuestionnaire(questionnaire=config).apply()
            except KeyError as error:
                return [JSONResponse({"error": f"Missing field {error}"}, status_code=400)]
            except ValueError as error:
                return [JSONResponse({"error": str(error)}, status_code=400)]
            return [
                JSONResponse({"created": config["name"], "questions": len(config["questions"])}),
                effect,
            ]
        def _build_config(self, body: dict[str, Any]) -> QuestionnaireConfig:
            return {
                "name": body["title"],
                "form_type": "QUES",
                "code_system": "INTERNAL",
                "code": body["code"],
                "can_originate_in_charting": True,
                "questions": [
                    self._build_question(index, item)
                    for index, item in enumerate(body["questions"], start=1)
                ],
            }
        def _build_question(self, index: int, item: dict[str, Any]) -> Question:
            code = f"Q{index}"
            if item.get("type") == "text":
                return {
                    "content": item["prompt"],
                    "code_system": "INTERNAL",
                    "code": code,
                    "responses_code_system": "INTERNAL",
                    "responses_type": "TXT",
                    # A typed answer still needs one option to hang the response on.
                    "responses": [{"name": "TXT", "code": f"{code}A1"}],
                }
            return {
                "content": item["prompt"],
                "code_system": "INTERNAL",
                "code": code,
                "responses_code_system": "INTERNAL",
                "responses_type": "SING",
                "responses": [
                    {"name": choice, "code": f"{code}A{position + 1}", "value": str(position)}
                    for position, choice in enumerate(item["choices"])
                ],
            }
    ```
Scoring each choice by its position is the kind of thing that is tedious to maintain in a static template and trivial to compute here, which is the case for building the questionnaire in Python rather than declaring it.
The [`example_sdk_effect_create_questionnaire`](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/example_sdk_effect_create_questionnaire) reference plugin goes further: it maps a caller's own question types onto `SING`, `MULT`, `TXT`, and `DATE`, wires a follow-up question to an earlier answer through `enabled_conditions`, and reads the questionnaire back with its branching.
##  Creating a Questionnaire Result 
`CreateQuestionnaireResult` applies your own scoring to a questionnaire. The result:
  - adds a narrative to the command in the UI.
  - appears in the Social Determinants section on the left of the chart, when the questionnaire is configured to show there. Questionnaires covers the `display_result_in_social_history_section` setting.
> **Info:** The `narrative` property is the customer-facing string shown alongside the result — it is separate from the numeric `score`. Use `score` to store the calculated numeric value and `narrative` to provide a more user-friendly description, for example `'Score: {score}'` or `'A score of {score} indicates {result}'`, giving providers context for how to react to the score.
> **Info:** Whether a result appears in the Social Determinants section depends on how the questionnaire itself is configured to display there, not on the effect alone: the SDK YAML `display_results_in_social_history_section` / `display_result_in_social_history_section` attributes, the **Display in Social Determinants** checkbox in the Questionnaire Builder, or the `use_in_shx` column when uploading via Google Sheets.
Build a `CreateQuestionnaireResult` with the attributes below, then return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Records the result against the interview.
  - `interview_id`, `score`, `code_system`, and `code` are required, and `interview_id` must be the id of an existing interview.
  - `code_system` and `code` are required because a questionnaire result also creates an [Observation](/sdk/data-observation/) record, and they are what tell one result's observations from another's.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`interview_id`| `str`| The id of the interview to associate the result with.| Yes  
`score`| `float`| The numerical score of the questionnaire result.| Yes  
`abnormal`| `bool`| Whether the result is considered abnormal. Defaults to `False`.| No  
`narrative`| `str`| A text description of the result and any recommended follow-up actions. Defaults to an empty string.| No  
`code_system`| `str`| The code system used to identify the questionnaire, for example `"INTERNAL"`.| Yes  
`code`| `str`| The code identifying the questionnaire within the code system, for example `"mchat_scoring"`.| Yes  
###  Examples 
####  Summing the answers 
The simplest scoring is a total of every answer's `value`. This handler runs when a questionnaire command is committed, checks the questionnaire is the one it scores, and adds the answers up:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.questionnaire_result import CreateQuestionnaireResult
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.command import Command
    # A TXT or DATE answer is typed rather than chosen from a list, so it carries no score.
    UNSCORED_TYPES = ["TXT", "DATE"]
    class QuestionnaireScore(BaseHandler):
        """Score a committed questionnaire by totalling its answers."""
        RESPONDS_TO = [EventType.Name(EventType.QUESTIONNAIRE_COMMAND__POST_COMMIT)]
        QUESTIONNAIRE_CODE_SYSTEM = "LOINC"
        QUESTIONNAIRE_CODE = "93025-5"
        SCORE_CODE_SYSTEM = "INTERNAL"
        SCORE_CODE = "questionnaire-score"
        def compute(self) -> list[Effect]:
            # The interview is the anchor object on the questionnaire command.
            command = Command.objects.get(id=self.event.target.id)
            interview = command.anchor_object
            # The event fires for every questionnaire, so ignore the ones this handler does not score.
            questionnaire = interview.questionnaires.first()
            if (
                questionnaire.code != self.QUESTIONNAIRE_CODE
                or questionnaire.code_system != self.QUESTIONNAIRE_CODE_SYSTEM
            ):
                return []
            scorable = questionnaire.questions.exclude(
                response_option_set__type__in=UNSCORED_TYPES
            ).count()
            answers = interview.interview_responses.exclude(
                response_option__response_option_set__type__in=UNSCORED_TYPES
            )
            # A part-answered questionnaire totals lower than a complete one, so publishing a score
            # for it would understate the result.
            if answers.count() != scorable:
                return []
            # An option left unscored has an empty value and contributes nothing.
            score = sum(int(answer.response_option.value or 0) for answer in answers)
            effect = CreateQuestionnaireResult(
                interview_id=str(interview.id),
                score=score,
                narrative=f"Score of {score}.",
                code_system=self.SCORE_CODE_SYSTEM,
                code=self.SCORE_CODE,
            )
            return [effect.apply()]
    ```
Set `QUESTIONNAIRE_CODE_SYSTEM` and `QUESTIONNAIRE_CODE` to the questionnaire you are scoring, and `SCORE_CODE_SYSTEM` and `SCORE_CODE` to the coding you want the result's [Observation](/sdk/data-observation/) to carry.
####  Banding the score into a narrative 
A total on its own tells a reader little. This M-CHAT example sums the answers the same way, then turns the total into a risk band with the follow-up it calls for, and marks the result abnormal.
**Note:** This example assumes an M-CHAT questionnaire is already created and loaded into the Canvas instance.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.questionnaire_result import CreateQuestionnaireResult
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.command import Command
    class MChatQuestionnaireResult(BaseHandler):
        """
        Return a CreateQuestionnaireResult effect in response to a committed Questionnaire Command that
        contains questions coded for the M-CHAT questionnaire.
        """
        RESPONDS_TO = [EventType.Name(EventType.QUESTIONNAIRE_COMMAND__POST_COMMIT)]
        MCHAT_CODE_SYSTEM = "INTERNAL"
        MCHAT_CODE = "mchat_scoring"
        def compute(self) -> list[Effect]:
            # Get the interview object, which will be the anchor object on the Questionnaire command.
            command = Command.objects.get(id=self.event.target.id)
            interview = command.anchor_object
            if not interview.committer:
                return []
            # Return no effects if the interview has no questions that are coded as M-CHAT questions
            if not any(
                q.code == self.MCHAT_CODE and q.code_system == self.MCHAT_CODE_SYSTEM
                for q in interview.questionnaires.all()
            ):
                return []
            # sum up the numerical value of each answered questionnaire
            score = 0
            for response in interview.interview_responses.all():
                score = score + int(response.response_option.value)
            # Determine the narrative and whether the result is abnormal
            if score >= 0 and score <= 2:
                abnormal = False
                narrative = (
                    "The score is LOW risk. Child has screened negative. No immediate follow-up is "
                    "needed. However, the child should be rescreened at 24 months or after 3 months "
                    "have passed if they are younger than 2 years. Monitoring the child's "
                    "development remains important."
                )
            elif score >= 3 and score <= 7:
                abnormal = True
                narrative = (
                    "The score is MODERATE risk. Administer the M-CHAT-R Follow-Up items that "
                    "correspond to the at-risk responses. Only those items which were scored at risk "
                    "need to be completed. If 2 or more items continue to be at-risk, refer the "
                    "child immediately for (a) early intervention and (b) diagnostic evaluation."
                )
            elif score >= 8 and score <= 20:
                abnormal = True
                narrative = (
                    "The score is HIGH risk. It is not necessary to complete the M-CHAT-R Follow-Up "
                    "at this time. Bypass Follow-Up, and refer immediately for (a) early "
                    "intervention and (b) diagnostic evaluation."
                )
            else:
                abnormal = True
                narrative = "Error occurred trying to score questionnaire."
            # Create and return the effect
            effect = CreateQuestionnaireResult(
                interview_id=str(interview.id),
                score=score,
                abnormal=abnormal,
                narrative=narrative,
                code_system=self.MCHAT_CODE_SYSTEM,
                code=self.MCHAT_CODE,
            )
            return [effect.apply()]
    ```

---

# Record Patient Consent

Source: https://docs.canvasmedical.com/sdk/effect-record-patient-consent/

Use the `RecordPatientConsent` effect to record a patient's consent decision on their chart. For example, a plugin can record the decision after the patient completes an intake form. The effect sets the consent's state and effective date, and it can file the signed document with the consent.
Each patient has one [PatientConsent](/sdk/data-patient-consent/) record per consent coding. The first decision for a coding creates the record. A later decision updates it only when its `effective_date` is on or after the recorded one. See How Canvas records the decision.
Build a `RecordPatientConsent` with the attributes you want to set, then return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Records the patient's decision on one consent.
  - `patient_id`, `consent`, `state`, and `effective_date` are required.
  - `patient_id` must be the id of an existing patient.
  - `consent` must match exactly one [PatientConsentCoding](/sdk/data-patient-consent/#patientconsentcoding).
  - `rejection_reason` can be set only when `state` is `REJECTED` or `REJECTED_VIA_PORTAL`, and it must match exactly one [PatientConsentRejectionCoding](/sdk/data-patient-consent/#patientconsentrejectioncoding).
  - `document.content` must be a PDF file, base64 encoded. Line breaks in the encoded content are allowed. The decoded content must start with the PDF signature `%PDF-`, so another file type, such as a PNG, fails validation.
##  Attributes 
###  RecordPatientConsent 
Attribute| Type| Description| Required  
---|---|---|---  
`patient_id`| `str`| The id of the [patient](/sdk/data-patient/).| Yes  
`consent`| ConsentCodingReference| The consent coding the decision applies to.| Yes  
`state`| [PatientConsentStatus](/sdk/data-patient-consent/#patientconsentstatus)| The patient's decision.| Yes  
`effective_date`| `datetime.date`| The date the decision takes effect. It is also the date of the attached document.| Yes  
`rejection_reason`| ConsentCodingReference| The reason the patient rejected the consent. Set it only with a rejected state.| No  
`document`| ConsentDocument| The signed consent document to file with the consent.| No  
The attributes are strictly typed. `state` takes a `PatientConsentStatus` member, not a string, and `effective_date` takes a `datetime.date`, not a `datetime.datetime`.
###  ConsentCodingReference 
Identifies a consent coding or a rejection coding.
Attribute| Type| Description| Required  
---|---|---|---  
`system`| `str`| The coding system, such as `LOINC` or `INTERNAL`.| Yes  
`code`| `str`| The coding's code.| If `display` is empty  
`display`| `str`| The coding's display text. Used to find the coding only when `code` is empty.| If `code` is empty  
When `code` is set, the effect finds the coding by `system` and `code`. Otherwise it finds the coding by `system` and `display`. The effect fails validation when the reference matches no coding or more than one. If a reference by `code` matches more than one coding, delete the duplicate coding in Canvas. If a reference by `display` matches more than one, reference the coding by its `code` instead.
###  ConsentDocument 
The signed copy of the consent.
Attribute| Type| Description| Required  
---|---|---|---  
`filename`| `str`| The file name to store the document under, such as `telehealth.pdf`. It can be at most 255 characters and must not contain a path.| Yes  
`content`| `str`| The bytes of a PDF file, base64 encoded. Other file types fail validation.| Yes  
##  How Canvas records the decision 
  - **Earlier-dated decisions:** The decision with the latest `effective_date` sets the consent's state, dates, and rejection reason. A decision dated before the recorded one leaves the consent as it is, but Canvas still files its document. Use this to add an older signed copy without changing the current decision.
  - **Expiration date:** Canvas computes the consent's expiration date from `effective_date` and the coding's [expiration rule](/sdk/data-patient-consent/#patientconsentexpirationrule).
  - **Rejection reason:** A decision that updates the consent replaces its rejection reason. A decision without `rejection_reason`, including any accepted decision, clears the earlier reason.
  - **Signed documents:** Each document you attach is added to the consent's [signed documents](/sdk/data-patient-consent/#signed-consent-documents) with `effective_date` as its date. The document with the latest date becomes the consent's `active_document`, and earlier signed copies stay on the chart. Canvas codes each document LOINC `59284-0` (Consent Document), the same [document type](/sdk/data-patient-administrative-document/) as a consent document staff upload, and its [DocumentReference](/sdk/data-document-reference/) `type` carries that coding.
  - **Other consents:** The effect changes only the consent you name. A consent the patient did not answer keeps its current state.
##  Example 
This handler records an accepted telehealth consent and attaches the signed PDF:
    ```python
    import base64
    import datetime
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_consent import (
        ConsentCodingReference,
        ConsentDocument,
        RecordPatientConsent,
    )
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data import PatientConsentStatus
    class RecordTelehealthConsent(BaseHandler):
        def compute(self) -> list[Effect]:
            # Replace with the bytes of the PDF the patient signed.
            signed_pdf = b"%PDF-1.7 ..."
            effect = RecordPatientConsent(
                # The handler responds to an event whose target is the patient.
                patient_id=self.event.target.id,
                consent=ConsentCodingReference(system="INTERNAL", code="TELEHEALTH"),
                state=PatientConsentStatus.ACCEPTED_VIA_PORTAL,
                effective_date=datetime.date.today(),
                document=ConsentDocument(
                    filename="telehealth.pdf",
                    content=base64.b64encode(signed_pdf).decode(),
                ),
            )
            return [effect.apply()]
    ```
To record a rejection, pass a rejected state and, optionally, the reason:
    ```python
    import datetime
    from canvas_sdk.effects.patient_consent import ConsentCodingReference, RecordPatientConsent
    from canvas_sdk.v1.data import PatientConsentStatus
    effect = RecordPatientConsent(
        patient_id="1eed3ea2a8d546a1b681a2a45de1d790",
        consent=ConsentCodingReference(system="LOINC", code="59284-0"),
        state=PatientConsentStatus.REJECTED,
        effective_date=datetime.date.today(),
        rejection_reason=ConsentCodingReference(system="INTERNAL", display="Patient declined"),
    )
    effect.apply()
    ```

---

# Redirect

Source: https://docs.canvasmedical.com/sdk/effect-redirect/

The `RedirectEffect` tells the Canvas frontend to navigate the browser to a destination. The plugin returns the effect from a handler and the frontend performs a full-page navigation. In the patient portal, portal pages change in place instead (see Redirects in the patient portal). The headline use case is sending a user onward after a note is signed — for example, navigating back to a work queue to pick up the next patient.
A redirect is delivered only to the **acting user** who triggered the handler — and only to that user's browser. Because of that, it takes effect only when the handler runs in the context of a real user with an active browser session. Return it from user-initiated handlers — a note state-change (sign/lock) handler, an action-button handler, an application handler, or an authenticated [SimpleAPI](/sdk/handlers-simple-api/) call. If a handler has no user actor — for example a `CronTask`, other background processing, or any event whose actor defaults to canvas-bot — there is no browser to navigate and the redirect is silently ignored. See [Event Actor](/sdk/events/#event-actor) for which events carry an actor.
Provide **exactly one** destination:
  - `url` — a full URL string the plugin composes in Python (it may include patient/note ids). Either an external URL (`https://...`) or an internal Canvas path (`/panel`, `/patient/{id}?noteId=...`).
  - `application_id` — the identifier of a Canvas application to open.
By default the navigation replaces the current tab. Set `target` to `RedirectEffect.TargetType.NEW_TAB` to open a `url` destination in a new tab instead.
> **Internal navigation must be a root-relative path that starts with`/`** — e.g. `url="/schedule"` (or `/panel`, `/patient/{id}?noteId=...`). A leading-slash path is the _only_ form treated as internal navigation. A bare page name like `schedule` will **not** work: anything that doesn't start with `/` is treated as an external URL and is rejected unless it's a full `https://...` URL (protocol-relative `//...` and backslash `/\...` values are always rejected). The matching `REDIRECT_ALLOWLIST_INTERNAL` entries must likewise be leading-slash paths (e.g. `/schedule`).
For staff, an internal `url` can be any Canvas path, including its query string. The paths staff use most, such as the patient chart, schedule, patient list, and revenue pages, are listed in [Pages a pane sees](/sdk/handlers-embedded-applications/#pages-a-pane-sees). For patients, internal paths are limited to the portal routes.
Build a `RedirectEffect` and return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Redirects the user.
  - Provide exactly one of `url` or `application_id`. An `application_id` must identify an existing application.
  - `target` defaults to `SAME_TAB`.
##  Attributes 
Name| Type| Description| Required  
---|---|---|---  
`url`| `str`| A full external URL (`https://...`) or an internal Canvas path that **must start with`/`** (e.g. `/schedule`, `/patient/{id}`), composed by the plugin. Non-empty. For common staff paths, see [Pages a pane sees](/sdk/handlers-embedded-applications/#pages-a-pane-sees). For patients, see the portal routes.| Exactly one of `url` or `application_id`  
`application_id`| `str`| The identifier of a Canvas application to open. Must exist and be enabled.| Exactly one of `url` or `application_id`  
`target`| `TargetType`| Where to open a `url` destination. Defaults to `TargetType.SAME_TAB`.| No  
##  `TargetType`
A `StrEnum` of the supported navigation targets. You can also pass the string value.
Member| Value| Behavior  
---|---|---  
`RedirectEffect.TargetType.SAME_TAB`| `"same_tab"`| Replaces the current EHR view (full-page navigation). The default.  
`RedirectEffect.TargetType.NEW_TAB`| `"new_tab"`| Opens the destination in a new browser tab.  
##  Security & Allowlist 
Every destination is validated **on the server** before the browser navigates — the frontend is never trusted to decide whether a target is allowed. This blocks open-redirect abuse and accidental leakage of PHI through query parameters. **Targets are denied by default.**
The allowlist governs only _where a plugin may send a user_ — it does **not** change what that user is allowed to see, and cannot be used to bypass their permissions. A redirect performs an ordinary browser navigation, so the destination still enforces the user's own access: redirecting a user to a page or application they lack permission for behaves exactly as if they navigated there themselves (they're denied by that destination), and never elevates their access.
The allowlist is configured **per instance by an administrator** via three plugin secrets. Your plugin declares the keys in its [manifest `variables`](/sdk/canvas_manifest/#variables); the admin sets each value on the Plugin admin page, or from the CLI with [`canvas config set`](/sdk/canvas_cli/#canvas-config-set). (This redirect allowlist is separate from the manifest's `url_permissions` field, which allow-lists iframe and script domains for layout effects — the two are unrelated.) Each value is a list with **one entry per line** — entries are newline-delimited, not comma-separated, because URLs and paths can legitimately contain commas (e.g. `?q=1,2,3`):
Secret key| Value (one entry per line)| Permits  
---|---|---  
`REDIRECT_ALLOWLIST_INTERNAL`| `/patients`  
`/panel`  
`/patient`| those path roots and anything the plugin composes under them, matched at a path boundary (`/patient/{id}?noteId=...`).  
`REDIRECT_ALLOWLIST_EXTERNAL`| `https://app.example.com`| those origins/prefixes (**include the scheme**), matched **case-insensitively** at an origin/path boundary — so it does **not** match `https://app.example.com.evil.com`, and a differing port (e.g. `https://app.example.com:8443/...`) is not a match.  
`REDIRECT_ALLOWLIST_APPLICATION`| `my_plugin.applications.app:MyApp`| redirecting to those applications by id (matched exactly; the app must exist and be enabled).  
Declare the keys in your manifest so the admin can fill them:
    ```json
    {
      "variables": [
        { "name": "REDIRECT_ALLOWLIST_INTERNAL" },
        { "name": "REDIRECT_ALLOWLIST_EXTERNAL" },
        { "name": "REDIRECT_ALLOWLIST_APPLICATION" }
      ]
    }
    ```
Both steps are required, and both default to "blocked": if you don't **declare** a key in the manifest, the admin has no field to fill; if the admin doesn't **set** a value, that key's allowlist is empty. An empty or absent secret allows nothing — so each redirect category (internal / external / application) only works once its key is declared _and_ an admin has given it a value. A freshly installed plugin can therefore redirect nowhere until an admin opts it in.
Set a value from the CLI with your shell's newline quoting so each entry stays on its own line (see [`canvas config set`](/sdk/canvas_cli/#canvas-config-set)):
    ```console
    $ canvas config set acme__my_plugin $'REDIRECT_ALLOWLIST_INTERNAL=/panel\n/patient' --instance acme-staging
    ```
Non-allowlisted destinations are dropped, and the platform logs only the plugin name and the blocked host (never the full URL/path). Protocol-relative (`//host`) and backslash (`/\host`) targets are always rejected.
##  Redirects in the patient portal 
A plugin can also redirect a patient who is signed in to the patient portal. Use it to move the patient from a plugin page to their next step, such as their messages, lab results, or another portal application. The redirect works from portal menu item applications, landing page widgets, and other plugin pages shown in the portal. Return the effect from an endpoint authenticated with `PatientSessionAuthMixin`, using the same pattern as Redirect from an application iframe.
Every portal redirect must first pass the plugin's allowlist (see Security & Allowlist). When the acting user is a patient, Canvas then checks the destination against the portal's own rules:
Destination| Portal rule  
---|---  
Internal `url`| Must be `/app` or a portal route that is turned on for the instance (see the table below). Any other internal path, including `/app/application/...`, is blocked.  
`application_id`| Must identify a `portal_menu_item` [application](/sdk/handlers-applications/). Open portal applications this way, not by URL.  
External `url`| No extra rule. A URL that passes `REDIRECT_ALLOWLIST_EXTERNAL` opens in the same tab, or in a new tab with `TargetType.NEW_TAB`.  
These are the portal routes a plugin can redirect to. Each one works only while its portal page is turned on through its `PATIENT_APP_*` setting, managed by Canvas Support (see [Managing the Patient Portal](https://canvas-medical.help.usepylon.com/articles/7348270931-managing-the-patient-portal)):
Route| Setting  
---|---  
`/app/appointments`| `PATIENT_APP_APPOINTMENTS`  
`/app/messaging`| `PATIENT_APP_MESSAGING`  
`/app/payments`| `PATIENT_APP_PAYMENTS`  
`/app/labs`| `PATIENT_APP_LABS`  
`/app/contact`| `PATIENT_APP_CONTACT`  
`/app/records`| `PATIENT_APP_RECORDS`  
`/app/my-health`| `PATIENT_APP_MY_HEALTH`  
The plugin's `REDIRECT_ALLOWLIST_INTERNAL` secret must also include the path, for example `/app/messaging` or `/app`.
The portal changes routes and opens applications in place, without reloading the page. The browser's Back button returns the patient to the plugin page. `target` has no effect on these destinations. An application opens with its portal menu item selected.
When the portal rules block a redirect, the patient stays on the current page. The plugin logs record the plugin name and either the application identifier or `<internal>` for a blocked path. The path itself is never logged.
Staff users, including staff who also have a patient record, use the Canvas EHR. Their redirects follow the staff rules described earlier on this page, not the portal rules.
##  Example Usage 
###  Redirect to a work queue after a note is signed 
Requires `/panel` in the plugin's `REDIRECT_ALLOWLIST_INTERNAL` secret.
    ```python
    from canvas_sdk.effects.redirect import RedirectEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.note import CurrentNoteStateEvent, NoteStates
    class RedirectAfterSign(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self):
            state = CurrentNoteStateEvent.objects.values_list("state", flat=True).get(
                id=self.event.target.id
            )
            if state != NoteStates.LOCKED:
                return []
            # Send the provider back to their work queue to grab the next patient.
            return [RedirectEffect(url="/panel").apply()]
    ```
###  Open an external URL in a new tab from an action button 
Requires `https://app.example.com` in the plugin's `REDIRECT_ALLOWLIST_EXTERNAL` secret.
    ```python
    return [
        RedirectEffect(
            url="https://app.example.com/orders/next",
            target=RedirectEffect.TargetType.NEW_TAB,
        ).apply()
    ]
    ```
###  Redirect to an application by id 
Requires the identifier in the plugin's `REDIRECT_ALLOWLIST_APPLICATION` secret.
    ```python
    return [RedirectEffect(application_id="my_plugin.applications.app:MyApp").apply()]
    ```
###  Send a patient to their messages from a portal page 
Requires `/app/messaging` in the plugin's `REDIRECT_ALLOWLIST_INTERNAL` secret, and the portal's messaging page turned on.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.redirect import RedirectEffect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import PatientSessionAuthMixin, SimpleAPI, api
    class PortalPageAPI(PatientSessionAuthMixin, SimpleAPI):
        @api.post("/go-to-messages")
        def go_to_messages(self) -> list[Response | Effect]:
            return [
                RedirectEffect(url="/app/messaging").apply(),
                JSONResponse({"ok": True}),
            ]
    ```
###  Redirect from an application iframe 
An application iframe can't return an effect directly. The clean pattern is to expose a [SimpleAPI](/sdk/handlers-simple-api/) endpoint on your plugin that returns a `RedirectEffect`, and have the iframe `fetch()` it. Because a SimpleAPI request is authenticated as the acting user, the returned effect is validated and delivered through the **exact same** interpreter → allowlist → per-user path as an action-button or note-sign redirect — there is no iframe-specific code path to reason about.
> **Why an API call and not`postMessage`?** An iframe could `postMessage` its parent window to request a redirect (the way the close-modal workflow does), but we recommend against it here. A redirect already has to make a server round-trip for allowlist validation, so routing the request through the parent window and a dedicated mutation would add a second mechanism that buys nothing. Having the iframe call your own API that returns the effect is cleaner:
> 
>   - **One mechanism, one mental model.** The iframe reuses the same effect pipeline as every other redirect — no separate frontend bridge, no dedicated mutation, and target validation lives in exactly one place (the interpreter).
>   - **Secure by construction.** The plugin whose allowlist is checked is _intrinsic_ : it's the plugin that owns the API endpoint. Nothing frontend-supplied has to be trusted or proven un-spoofable — a `postMessage` bridge would first have to attribute the message to an owning application before it could even pick which allowlist to apply.
>   - **Composable.** Your endpoint can do real work first — persist state, branch on the patient/note, decide _where_ to send the user — and then return the redirect alongside a normal JSON response.
> 
**The endpoint** returns the `RedirectEffect` (optionally with a response body for the `fetch`):
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.redirect import RedirectEffect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin, api
    class MyAppAPI(StaffSessionAuthMixin, SimpleAPI):
        @api.post("/redirect")
        def redirect(self) -> list[Response | Effect]:
            # ...optionally do work first (persist data, decide the destination)...
            return [
                RedirectEffect(url="/panel").apply(),  # or application_id="my_plugin.applications.app:MyApp"
                JSONResponse({"ok": True}),
            ]
    ```
**The iframe** calls it with a credentialed, same-origin request:
    ```js
    // inside the plugin application iframe
    fetch('/plugin-io/api/my_plugin/redirect', {
      method: 'POST',
      credentials: 'same-origin',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ destination: 'panel' })
    });
    ```
**How the redirect arrives.** The navigation does **not** come back in the `fetch()` response body. The effect is broadcast to the acting user and applied by the frontend's redirect subscription, exactly as for any other `RedirectEffect` — so the `fetch` response is just your endpoint's acknowledgement, and the browser navigates a moment later when the effect is delivered.
**Requirements & gotchas**
  - The endpoint must authenticate the request **as a specific Canvas user** — that user is the actor the redirect targets. Use [`StaffSessionAuthMixin`](/sdk/handlers-simple-api/) (as above) or `PatientSessionAuthMixin`, which resolve the acting user from the Canvas session, or another scheme that identifies a specific user (for example an OAuth token tied to a user). A **shared-secret** scheme — `BasicAuthMixin` or `APIKeyAuthMixin` — authenticates the _request_ but establishes no acting user, so a redirect returned from it has no browser to target and is silently dropped.
  - For the session mixins, the request must be **same-origin and credentialed** (`credentials: 'same-origin'`) so the session is sent and the server can identify the acting user. Plugin-served iframes — rendered from `LaunchModalEffect` content or a plugin-served URL — are same-origin. An **unauthenticated** request has no acting user either, so the redirect is silently dropped.
  - The target still has to be **allowlisted** (see Security & Allowlist); the API path enforces the identical gate.
  - `target` (new tab) applies only to `url` destinations; an `application_id` always opens in-app.
##  Validation 
Construction is validated by Pydantic and will raise a `ValidationError` for:
  - Providing neither `url` nor `application_id`, or providing both.
  - An empty `url`.
  - A `target` that is not a member of `TargetType`.
  - An `application_id` that does not resolve to an existing application.

---

# Reload Action Buttons Effect

Source: https://docs.canvasmedical.com/sdk/effect-reload-action-buttons/

The reload action button effects let a plugin tell Canvas to recompute and re-render its [action buttons](/sdk/handlers-action-buttons/) without the user reloading the page. This is useful after your plugin changes state that a button's `visible()` method, title, or color depends on, so the displayed buttons reflect the new state.
There are two effects, one for each scope:
  - `ReloadNoteActionButtonsEffect` — reloads the action buttons for a single note.
  - `ReloadPatientActionButtonsEffect` — reloads the action buttons for a patient.
Emit one from any handler's `compute()` or `handle()` — not only from an `ActionButton`. The effect re-fires the relevant [`SHOW_*_BUTTON`](/sdk/events/#action-buttons-events) events, so every button in that location recomputes `visible()` from scratch: the button set is rebuilt, not patched.
##  When to reload 
A button's `visible()` result, its title, and its color are all computed from live data each time the location is evaluated. Reloading is how you push those changes to the footer or header without a full page refresh. Common cases:
  - **The button has done its job.** Once a button is clicked and its action completes, it often no longer applies — reload so its `visible()` re-evaluates to `False` and the button drops out of the set instead of lingering as a stale, re-clickable control.
  - **The label or color should change.** When a button reflects state — a title that shows a count of outstanding items, or a color that turns green once a task is complete — reload after that state changes so the button re-renders with its new title and color.
  - **Data the button depends on changed elsewhere.** After a command is committed, a note transitions to a new state, or related records are updated by another handler, reload the location so every button recomputes against the current data.
* * *
##  ReloadNoteActionButtonsEffect 
To reload a note's action buttons, build a `ReloadNoteActionButtonsEffect` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Re-evaluates the note's action buttons in the `NOTE_HEADER`, `NOTE_FOOTER`, and `NOTE_HEADER_DROPDOWN` locations. It also re-reads the note's [footer configuration](/sdk/effect-note-footer-configuration/) (by re-firing `NOTE_FOOTER__GET_CONFIGURATION`), so a plugin that toggles `hide_default_state_buttons` can refresh whether Canvas's native footer buttons are hidden without a full page reload.
  - `id` is required, and must be the id of an existing note.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`id`| `str \| UUID`| The external id of a [Note](/sdk/data-note/#note) (`Note.id`). The note must exist, or the effect raises a validation error.| Yes  
> **Warning:** The `note_id` carried by a [`SHOW_*_BUTTON`](/sdk/events/#action-buttons-events) context is the note's **database id** (`dbid`), while this effect is keyed by the note's **external id**. Resolve between them through the [`Note`](/sdk/data-note/#note) data model — for example `Note.objects.filter(dbid=...).first().id`.
###  Example 
This handler reloads a note's footer whenever any command is committed, so a button that hides while the note has uncommitted commands reappears the moment the last one is committed:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.action_button import ReloadNoteActionButtonsEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.command import Command
    class ReloadFooterOnCommandCommit(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(value)
            for value in EventType.values()
            if EventType.Name(value).endswith("_COMMAND__POST_COMMIT")
        ]
        def compute(self) -> list[Effect]:
            command = Command.objects.filter(id=self.event.target.id).first()
            if not command or not command.note:
                return []
            return [ReloadNoteActionButtonsEffect(id=str(command.note.id)).apply()]
    ```
##  ReloadPatientActionButtonsEffect 
To reload a patient's action buttons, build a `ReloadPatientActionButtonsEffect` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Re-evaluates the patient's action buttons in the `CHART_PATIENT_HEADER` location.
  - `id` is required, and must be the id of an existing patient.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`id`| `str`| The id of a [Patient](/sdk/data-patient/#patient). The patient must exist, or the effect raises a validation error.| Yes  
###  Example 
This handler refreshes a patient's header buttons whenever one of their tasks changes, so a `CHART_PATIENT_HEADER` button that shows a live count of open tasks stays current as tasks are created or completed:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.action_button import ReloadPatientActionButtonsEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class ReloadPatientButtonsOnTaskChange(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.TASK_CREATED),
            EventType.Name(EventType.TASK_UPDATED),
        ]
        def compute(self) -> list[Effect]:
            patient_id = (self.event.context.get("patient") or {}).get("id")
            if not patient_id:
                return []
            return [ReloadPatientActionButtonsEffect(id=patient_id).apply()]
    ```

---

# Send Contact Verification

Source: https://docs.canvasmedical.com/sdk/effect-send-contact-verification/

The `SendContactVerificationEffect` instructs Canvas to send a verification (for example, an email or SMS code) to a specific Patient Contact Point. Use it to verify a patient's email address or phone number — for example, before relying on that channel for outbound communications, or before enabling patient-portal features that require a verified contact channel. It applies to any patient contact point; it isn't tied to the patient portal.
Build a `SendContactVerificationEffect` and return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Sends a verification to the contact point.
  - `contact_point_id` is required, and must be the id of an existing patient contact point.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`contact_point_id`| `str` or `UUID`| The id of the [`PatientContactPoint`](/sdk/effect-patient/#patientcontactpoint) to verify.| Yes  
##  Validation & Errors 
When an effect is prepared, the model validates inputs and returns structured error details if something is invalid.
  - **Contact Point Exists** — The effect verifies the provided `contact_point_id` maps to an existing `PatientContactPoint` record. If no matching record exists the effect will include an error detail with message: `Patient Contact Point does not exist`.
##  Caveats 
  - Emitting this effect will trigger a save to the associated `PatientContactPoint`. If your plugin sends `SendContactVerification` in direct response to a `PATIENT_CONTACT_POINT_UPDATED` event, the save triggered by the effect can cause the same event to fire again, producing an infinite event loop. To avoid this, debounce or detect origin (for example, ignore updates originating from the plugin runner or set a transient flag on the model) before emitting the effect in response to contact point update events.
##  Example Usage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.send_contact_verification import SendContactVerificationEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CONTACT_POINT_CREATED)
        def compute(self) -> list[Effect]:
            contact_point_id = self.event.target.id
            verification_effect = SendContactVerificationEffect(contact_point_id=contact_point_id)
            return [verification_effect.apply()]
    ```
##  Notes 
  - This effect only triggers a verification send for the contact point. It does not mark the contact as verified — verification completion is handled by the platform when the patient completes the challenge.
  - The effect relies on `PatientContactPoint` existing in the database. If your integration creates contact points in the same operation, ensure they are persisted before emitting this effect.

---

# Service Provider Effects

Source: https://docs.canvasmedical.com/sdk/effect-service-provider/

The Service Provider effects let a plugin build and maintain its own directory of external providers. Providers created this way are readable through the [ServiceProvider](/sdk/data-serviceprovider/) data model — where they are flagged with `is_customer_managed` — and can be offered in the provider-search surfaces by [handling those searches yourself](/guides/customize-search-results/#offering-your-own-providers-alongside-the-directory).
Build a `ServiceProvider` with the attributes you want to set, then return one of its methods from your handler: `create()`, `update()`, or `deactivate()`.
##  Methods 
###  create() → Effect 
Creates a service provider, or updates a matching one; see Calling create more than once.
  - `first_name`, `specialty`, and `business_address` are required, and reject empty strings.
  - `id` must not be set.
###  update() → Effect 
Updates the provider with the given `id`.
  - `id` is required, and must be the id of an existing provider.
  - Only the attributes you set on the effect are changed, so an update never clears a field you did not mention. `first_name` and `specialty` cannot be set to `None`.
  - Set `is_active=True` to reactivate a deactivated provider. Nothing else reactivates one.
###  deactivate() → Effect 
Deactivates a provider without deleting it, so anything referencing it keeps working.
  - `id` is required, and must be the id of an existing provider.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`id`| `str` or `UUID`| The id of the provider. Must not be set on create| For `update()` and `deactivate()`  
`first_name`| `str`| Provider name, or the organization name| For `create()`  
`specialty`| `str`| Free text| For `create()`  
`business_address`| `str`| Business address| For `create()`  
`last_name`| `str` or `None`| Omit for organizations| No  
`practice_name`| `str` or `None`| Practice or organization name| No  
`business_phone`| `str` or `None`| Business phone number| No  
`business_fax`| `str` or `None`| Business fax number| No  
`npi`| `str` or `None`| Exactly 10 digits| No  
`direct_address`| `str` or `None`| Up to 512 characters| No  
`notes`| `str` or `None`| Free-text notes| No  
`is_active`| `bool`| Defaults to `True`| No  
##  Calling create more than once 
Creating never produces a duplicate. These four fields together identify a provider:
  - `first_name`
  - `last_name`
  - `specialty`
  - `business_address`
If a provider already exists with the same values for all four, the create updates that provider rather than adding a second one. Only a provider that differs on at least one of them is created as a new record.
When an existing provider is matched:
  - only the fields you sent are written; the rest keep their current values
  - a deactivated provider stays deactivated unless you send `is_active=True`
Because of this, the same create is safe to run repeatedly — on a schedule, on every plugin install, or as a re-import of a directory you already loaded. An omitted or empty `last_name` is treated as the empty string when matching, so repeated creates for an organization resolve to the same record.
##  Example Usage 
###  Creating providers 
    ```python
    from canvas_sdk.effects.service_provider import ServiceProvider
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class ProviderLoader(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.PLUGIN_CREATED)]
        def compute(self):
            return [
                ServiceProvider(
                    first_name="Jane",
                    last_name="Doe",
                    specialty="Cardiology",
                    business_address="123 Main St",
                    business_fax="5555550100",
                    npi="1234567890",
                    direct_address="jane.doe@direct.example.org",
                ).create(),
                # An organization has no last name.
                ServiceProvider(
                    first_name="Acme Imaging Center",
                    specialty="Radiology",
                    business_address="1 Hospital Way",
                ).create(),
            ]
    ```
###  Updating a provider 
    ```python
    ServiceProvider(id="d2194110-5c9a-4842-8733-ef09ea5ead11", notes="Prefers fax").update()
    ```
###  Reactivating a provider 
    ```python
    ServiceProvider(id="d2194110-5c9a-4842-8733-ef09ea5ead11", is_active=True).update()
    ```
###  Deactivating a provider 
    ```python
    ServiceProvider(id="d2194110-5c9a-4842-8733-ef09ea5ead11").deactivate()
    ```
##  Reading providers back 
Use the [ServiceProvider data module](/sdk/data-serviceprovider/), and `is_customer_managed` to read only the providers your plugin created:
    ```python
    from canvas_sdk.v1.data.service_provider import ServiceProvider
    ServiceProvider.objects.filter(is_customer_managed=True, is_active=True)
    ```
To surface them in the Refer, Imaging Order, Order DME, fax recipient, or external care team searches, see [Offering your own providers alongside the directory](/guides/customize-search-results/#offering-your-own-providers-alongside-the-directory).
To offer them in a provider search, see [`as_search_result` and `as_search_contact`](/sdk/data-serviceprovider/#search-results).

---

# StaffExternalIdentifier

Source: https://docs.canvasmedical.com/sdk/effect-staff-external-identifier/

Manage external identifiers on a staff member from a plugin. `StaffExternalIdentifier` is a single effect class with three methods — `.create()`, `.update()`, and `.delete()` — and which fields are required depends on the operation.
##  Methods 
###  create() → Effect 
Creates a new external identifier on the specified staff member.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`staff_id`| `str` / `UUID`| UUID of the [Staff](/sdk/data-staff/) record.| Yes  
`value`| `str`| The identifier value (e.g. an employee ID).| Yes  
`system`| `str`| The system the identifier belongs to (typically a URL).| No  
####  Validation 
  - `staff_id` must reference an existing Staff record, or the effect raises a descriptive error.
  - `id` must not be set on `create()` — the UUID is assigned server-side. Supplying it fails validation.
  - `value` and `staff_id` are required.
####  Server-side defaults 
Canvas applies these defaults on `create()`:
  - `use` → `"usual"`
  - `issued_date` → `"1970-01-01"`
  - `expiration_date` → `"2100-12-31"`
####  Example 
    ```python
    from canvas_sdk.effects.staff import StaffExternalIdentifier
    effect = StaffExternalIdentifier(
        staff_id="4150cd20de8a470aa570a852859ac87e",
        system="https://hr.example.com/",
        value="EMP-001234",
    ).create()
    ```
###  update() → Effect 
Updates fields on an existing external identifier. Only the fields you set on the effect are written; unset fields keep their existing values.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`id`| `str` / `UUID`| UUID of the identifier to update.| Yes  
`value`| `str`| New identifier value. Only written if supplied.| No  
`system`| `str`| New system value. Only written if supplied.| No  
####  Validation 
  - `id` is required and must reference an existing StaffExternalIdentifier record, or the effect raises a descriptive error.
####  Example 
    ```python
    from canvas_sdk.effects.staff import StaffExternalIdentifier
    effect = StaffExternalIdentifier(
        id="00000000-0000-0000-0000-000000000001",
        value="EMP-005678",
    ).update()
    ```
###  delete() → Effect 
Deletes the external identifier identified by `id`.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`id`| `str` / `UUID`| UUID of the identifier to delete.| Yes  
####  Validation 
  - `id` is required and must reference an existing StaffExternalIdentifier record, or the effect raises a descriptive error.
####  Example 
    ```python
    from canvas_sdk.effects.staff import StaffExternalIdentifier
    effect = StaffExternalIdentifier(
        id="00000000-0000-0000-0000-000000000001",
    ).delete()
    ```

---

# StaffMetadata Effect

Source: https://docs.canvasmedical.com/sdk/effect-staff-metadata/

The `StaffMetadata` effect provides a flexible key-value storage system for staff-specific data within the Canvas system, letting plugins attach extensible information beyond the standard staff data model.
##  Overview 
`StaffMetadata` exposes `.upsert(value)` to write or replace a metadata entry, and `.delete()` to remove one. The same key may be used across many staff members; the `(staff, key)` pair is unique per staff member.
##  Methods 
###  upsert(value: str) → Effect 
Creates or updates a metadata entry for the specified staff and key combination.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`value`| `str`| The metadata value to store| Yes  
####  Behavior 
  - If a metadata entry with the specified key already exists for the staff member, it will be updated with the new value.
  - If no entry exists, a new metadata entry will be created.
  - Metadata entries are isolated per staff member — the same key can hold different values for different staff members.
  - Values are stored as strings with no schema enforcement; the plugin is responsible for validating its own values.
####  Key Naming Conventions 
  1. **Use descriptive names**. Choose keys that clearly indicate the purpose of the metadata.
     - Good: `department`, `cost_center`, `external_employee_id`
     - Avoid: `data1`, `temp`, `misc`
  2. **Namespace your keys**. Prefix keys for integrations or modules to avoid collisions.
     - Example: `hr.employee_id`, `payroll.cost_center`
####  Value Storage 
  1. **String serialization**. All values are stored as strings. For complex data:
         ```python
         import json
         from canvas_sdk.effects.staff_metadata import StaffMetadata
         metadata = StaffMetadata(
             staff_id="4150cd20de8a470aa570a852859ac87e",
             key="hr.profile",
         )
         complex_data = {"hire_date": "2020-01-15", "department": "cardiology"}
         metadata.upsert(json.dumps(complex_data))
         ```
  2. **Boolean values**. Store as `"true"` or `"false"` strings for consistency.
####  Examples 
    ```python
    from canvas_sdk.effects.staff_metadata import StaffMetadata
    # Tag a provider with their primary department
    metadata = StaffMetadata(
        staff_id="4150cd20de8a470aa570a852859ac87e",
        key="department",
    )
    effect = metadata.upsert("cardiology")
    ```
Mirroring an HR system from a handler:
    ```python
    from canvas_sdk.effects.staff_metadata import StaffMetadata
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.events import EventType
    class StaffHRSync(BaseHandler):
        """Sync select fields from an HR webhook payload onto Canvas staff."""
        RESPONDS_TO = EventType.Name(EventType.STAFF_UPDATED)
        def compute(self):
            staff_id = self.event.context["staff"]["id"]
            hr_record = self.event.context.get("fields", {}).get("hr_record", {})
            return [
                StaffMetadata(staff_id=staff_id, key=f"hr.{key}").upsert(str(value))
                for key, value in hr_record.items()
            ]
    ```
###  delete() → Effect 
Removes the metadata entry identified by `(staff_id, key)`.
####  Behavior 
  - Removes the row that matches both `staff_id` and `key`. Returns success even if no row was present (idempotent).
  - Does not affect other metadata entries for the same staff member with different keys.
####  Example 
    ```python
    from canvas_sdk.effects.staff_metadata import StaffMetadata
    # Clear the department tag for a staff member
    effect = StaffMetadata(
        staff_id="4150cd20de8a470aa570a852859ac87e",
        key="department",
    ).delete()
    ```
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`staff_id`| `str`| Id of the [Staff](/sdk/data-staff/) record to associate metadata with| Yes  
`key`| `str`| Unique identifier for the metadata entry within the staff context| Yes  
##  Validation 
The effect validates before execution:
  - **Staff existence** : the `staff_id` must correspond to an existing Staff record, or the effect raises a descriptive error.
  - **Required fields** : `staff_id` and `key` must be non-empty strings, and `.upsert(...)` requires a `value`.

---

# Surescripts Effects

Source: https://docs.canvasmedical.com/sdk/effect-surescripts/

> **Warning:** **This feature must be enabled by Canvas.** To use the Surescripts effects, [contact Canvas Support](https://portal.usepylon.com/canvas-medical/forms/standard) to have these Surescripts effects enabled for your instance. Until it is enabled, these effects will not send requests.
Surescripts effects let plugins query insurance eligibility, benefits, and medication history through Surescripts. Eligibility and benefits requests receive responses asynchronously as corresponding events; medication history is handled by Canvas without a plugin-facing response.
##  Eligibility 
Check a patient's insurance coverage and plan details. Send a request with `SendSurescriptsEligibilityRequestEffect`, then handle the `SURESCRIPTS_ELIGIBILITY_RESPONSE` event when the response arrives.
###  SendSurescriptsEligibilityRequestEffect 
Sends an eligibility request to Surescripts to check a patient's insurance coverage. The response arrives as a `SURESCRIPTS_ELIGIBILITY_RESPONSE` event.
Build a `SendSurescriptsEligibilityRequestEffect` and return its `apply()` from your handler.
####  Methods 
#####  apply() → Effect 
Sends the eligibility request.
  - `patient_id` and `staff_id` are required.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`patient_id`| `str`| The Canvas [Patient](/sdk/data-patient/#patient) ID for whom to check eligibility.| Yes  
`staff_id`| `str`| The Canvas [Staff](/sdk/data-staff/#staff) ID initiating the request.| Yes  
`correlation_id`| `str`| A unique identifier for matching the response to this request. Auto-generated if not provided. Read this value after instantiation and store it for later use.| No  
####  Correlation ID 
Each eligibility request includes a `correlation_id` that echoes back in the corresponding `SURESCRIPTS_ELIGIBILITY_RESPONSE` event. Use this to match responses to their originating requests when handling multiple concurrent eligibility checks.
By default, the effect auto-generates a unique `correlation_id` (a UUID hex string). You can pass your own value if you need to thread external state through the request-response cycle.
> **Note:** The `correlation_id` is required for receiving response events. The platform only delivers `SURESCRIPTS_ELIGIBILITY_RESPONSE` events to plugins that sent a request with a valid `correlation_id`.
####  Example 
    ```python
    from canvas_sdk.effects.surescripts.surescripts_messages import SendSurescriptsEligibilityRequestEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class CheckEligibilityOnAppointment(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.APPOINTMENT_CREATED)]
        def compute(self):
            patient_id = self.event.target.get("id")
            staff_id = self.event.context.get("created_by", {}).get("id")
            effect = SendSurescriptsEligibilityRequestEffect(
                patient_id=patient_id,
                staff_id=staff_id,
            )
            # Store the correlation_id to match the response later
            # For example, save it to custom data or cache
            correlation_id = effect.correlation_id
            return [effect.apply()]
    ```
###  Handling Eligibility Responses 
When Surescripts returns an eligibility response, the platform fires a `SURESCRIPTS_ELIGIBILITY_RESPONSE` event. Use the typed data classes from `canvas_sdk.events.surescripts` to parse the response.
> **Important:** To prevent infinite loops, you cannot return a `SendSurescriptsEligibilityRequestEffect` from a handler that responds to `SURESCRIPTS_ELIGIBILITY_RESPONSE` events.
####  Response Data Classes 
#####  SurescriptsEligibilityResponse 
The top-level response object containing eligibility results.
Name| Type| Description  
---|---|---  
`correlation_id`| `str`| The correlation ID from the originating request.  
`patient_id`| `str`| The Canvas [Patient](/sdk/data-patient/#patient) ID for this eligibility check.  
`plans`| EligibilityPlan[]| List of insurance plans returned in the response.  
`error`| `str` or `None`| Error message if the request failed, otherwise `None`.  
#####  EligibilityPlan 
Represents a single insurance plan from the eligibility response.
Name| Type| Description  
---|---|---  
`pbm_name`| `str`| Name of the Pharmacy Benefit Manager.  
`payer_id`| `str`| Identifier for the insurance payer ([Transactor](/sdk/data-coverage/#transactor)).  
`member_id`| `str`| The patient's member ID for this plan.  
`plan_network_id`| `str` or `None`| Network identifier for the plan.  
`group_number`| `str` or `None`| Group number for the plan.  
`drug_formulary_number`| `str` or `None`| Drug formulary identifier.  
`coverage_id`| `str` or `None`| [Coverage](/sdk/data-coverage/#coverage) identifier.  
`description`| `str` or `None`| Human-readable description of the plan.  
`rejected`| `bool`| `True` if the eligibility check was rejected for this plan.  
`reject_reason`| `str` or `None`| Reason for rejection, if applicable.  
`service_types`| `list[str]`| List of service types covered (e.g., "MEDICAL", "RX").  
####  Response Handler Example 
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.events.surescripts import EligibilityPlan, SurescriptsEligibilityResponse
    from canvas_sdk.handlers.base import BaseHandler
    from logger import log
    class HandleEligibilityResponse(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.SURESCRIPTS_ELIGIBILITY_RESPONSE)]
        def compute(self):
            # Parse the event context into a typed response object
            response = SurescriptsEligibilityResponse.from_context(self.event.context)
            log.info(f"Received eligibility response for correlation_id: {response.correlation_id}")
            log.info(f"Patient ID: {response.patient_id}")
            if response.error:
                log.error(f"Eligibility check failed: {response.error}")
                return []
            for plan in response.plans:
                if plan.rejected:
                    log.warning(f"Plan rejected: {plan.pbm_name} - {plan.reject_reason}")
                else:
                    log.info(f"Active plan: {plan.pbm_name}, Member ID: {plan.member_id}")
                    if plan.service_types:
                        log.info(f"  Service types: {', '.join(plan.service_types)}")
            return []
    ```
##  Benefits 
Retrieve formulary and coverage details for a specific medication. Send a request with `SendSurescriptsBenefitsRequestEffect`, then handle the `SURESCRIPTS_BENEFITS_RESPONSE` event when the response arrives.
###  SendSurescriptsBenefitsRequestEffect 
Sends a benefits request to Surescripts to retrieve formulary and coverage details for a specific medication. The response arrives as a `SURESCRIPTS_BENEFITS_RESPONSE` event.
Build a `SendSurescriptsBenefitsRequestEffect` and return its `apply()` from your handler.
####  Methods 
#####  apply() → Effect 
Sends the benefits request.
  - `patient_id`, `staff_id`, `medication_description`, `medication_ndc`, and `plan` are required.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`patient_id`| `str`| The Canvas [Patient](/sdk/data-patient/#patient) ID for whom to check benefits.| Yes  
`staff_id`| `str`| The Canvas [Staff](/sdk/data-staff/#staff) ID initiating the request.| Yes  
`medication_description`| `str`| A human-readable description of the medication (e.g., "Lipitor 10 mg tablet").| Yes  
`medication_ndc`| `str`| The NDC of the medication to check.| Yes  
`plan`| `str`| The plan or PBM to check benefits against.| Yes  
`correlation_id`| `str`| A unique identifier for matching the response to this request. Auto-generated if not provided. Read this value after instantiation and store it for later use.| No  
####  Correlation ID 
As with eligibility requests, each benefits request includes a `correlation_id` that echoes back in the corresponding `SURESCRIPTS_BENEFITS_RESPONSE` event. Use this to match responses to their originating requests when handling multiple concurrent benefits checks.
By default, the effect auto-generates a unique `correlation_id` (a UUID hex string). You can pass your own value if you need to thread external state through the request-response cycle.
> **Note:** The `correlation_id` is required for receiving response events. The platform only delivers `SURESCRIPTS_BENEFITS_RESPONSE` events to plugins that sent a request with a valid `correlation_id`.
####  Example 
    ```python
    from canvas_sdk.effects.surescripts.surescripts_messages import SendSurescriptsBenefitsRequestEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class CheckBenefitsOnPrescription(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.PRESCRIBE_COMMAND__POST_ORIGINATE)]
        def compute(self):
            patient_id = self.event.target.get("id")
            staff_id = self.event.context.get("created_by", {}).get("id")
            effect = SendSurescriptsBenefitsRequestEffect(
                patient_id=patient_id,
                staff_id=staff_id,
                medication_description="Lipitor 10 mg tablet",
                medication_ndc="00071015523",
                plan="Acme PBM",
            )
            # Store the correlation_id to match the response later
            correlation_id = effect.correlation_id
            return [effect.apply()]
    ```
###  Handling Benefits Responses 
When Surescripts returns a benefits response, the platform fires a `SURESCRIPTS_BENEFITS_RESPONSE` event. Use the typed data classes from `canvas_sdk.events.surescripts` to parse the response.
> **Important:** To prevent infinite loops, you cannot return a `SendSurescriptsBenefitsRequestEffect` from a handler that responds to `SURESCRIPTS_BENEFITS_RESPONSE` events.
####  Response Data Classes 
#####  SurescriptsBenefitsResponse 
The top-level response object containing benefits results.
Name| Type| Description  
---|---|---  
`correlation_id`| `str`| The correlation ID from the originating request.  
`patient_id`| `str`| The Canvas [Patient](/sdk/data-patient/#patient) ID for this benefits check.  
`medication_ndc`| `str`| The NDC of the medication that was checked.  
`coverages`| BenefitCoverage[]| List of coverage results returned in the response.  
`error`| `str` or `None`| Error message if the request failed, otherwise `None`.  
#####  BenefitCoverage 
Represents a single coverage result from the benefits response.
Name| Type| Description  
---|---|---  
`pbm_name`| `str`| Name of the Pharmacy Benefit Manager.  
`payer_id`| `str`| Identifier for the insurance payer ([Transactor](/sdk/data-coverage/#transactor)).  
`formulary_status`| `str` or `None`| Formulary status of the medication (e.g., "On Formulary").  
`prior_authorization_required`| `bool`| `True` if prior authorization is required.  
`step_therapy_required`| `bool`| `True` if step therapy is required.  
`quantity_limits`| `list[str]`| Human-readable quantity limits (e.g., "30 fills per 1 calendar year").  
`copays`| `list[str]`| Human-readable copay descriptions (e.g., "Tier 2: $25.00").  
`alternatives`| TherapeuticAlternative[]| Therapeutic alternatives for the requested medication.  
`rejected`| `bool`| `True` if the benefits check was rejected for this coverage.  
`reject_reason`| `str` or `None`| Reason for rejection, if applicable.  
#####  TherapeuticAlternative 
Represents a therapeutic alternative suggested for the requested medication.
Name| Type| Description  
---|---|---  
`ndc`| `str`| The NDC of the alternative medication.  
`description`| `str` or `None`| Human-readable description of the alternative.  
`brand_or_generic`| `str` or `None`| Whether the alternative is "Brand" or "Generic".  
`rx_or_otc`| `str` or `None`| Whether the alternative is "Rx" or "OTC".  
`formulary_status`| `str` or `None`| Formulary status of the alternative.  
`prior_authorization_required`| `bool`| `True` if prior authorization is required.  
`step_therapy_required`| `bool`| `True` if step therapy is required.  
`quantity_limits`| `list[str]`| Human-readable quantity limits.  
`copays`| `list[str]`| Human-readable copay descriptions.  
####  Response Handler Example 
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.events.surescripts import (
        BenefitCoverage,
        SurescriptsBenefitsResponse,
        TherapeuticAlternative,
    )
    from canvas_sdk.handlers.base import BaseHandler
    from logger import log
    class HandleBenefitsResponse(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.SURESCRIPTS_BENEFITS_RESPONSE)]
        def compute(self):
            # Parse the event context into a typed response object
            response = SurescriptsBenefitsResponse.from_context(self.event.context)
            log.info(f"Received benefits response for correlation_id: {response.correlation_id}")
            log.info(f"Medication NDC: {response.medication_ndc}")
            if response.error:
                log.error(f"Benefits check failed: {response.error}")
                return []
            for coverage in response.coverages:
                if coverage.rejected:
                    log.warning(f"Coverage rejected: {coverage.pbm_name} - {coverage.reject_reason}")
                    continue
                log.info(f"{coverage.pbm_name} formulary status: {coverage.formulary_status}")
                if coverage.prior_authorization_required:
                    log.info("  Prior authorization required")
                for copay in coverage.copays:
                    log.info(f"  Copay: {copay}")
                for alternative in coverage.alternatives:
                    log.info(f"  Alternative: {alternative.description} ({alternative.ndc})")
            return []
    ```
##  Medication History 
Request a patient's medication history from Surescripts.
Unlike eligibility and benefits, this effect has **no paired response event** — Canvas retrieves the medication history and processes it on the platform side; the results are not delivered back to your plugin. There is no `correlation_id` and no `SURESCRIPTS_MEDICATION_HISTORY_RESPONSE` event to handle.
###  SendSurescriptsMedicationHistoryRequestEffect 
Sends a medication history request to Surescripts for the patient. Canvas requests the patient's recent fill history (currently the trailing 12 months).
Build a `SendSurescriptsMedicationHistoryRequestEffect` and return its `apply()` from your handler.
####  Methods 
#####  apply() → Effect 
Sends the medication history request.
  - `patient_id` and `staff_id` are required.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`patient_id`| `str`| The Canvas [Patient](/sdk/data-patient/#patient) ID whose medication history to request.| Yes  
`staff_id`| `str`| The Canvas [Staff](/sdk/data-staff/#staff) ID initiating the request.| Yes  
####  Example 
    ```python
    from canvas_sdk.effects.surescripts.surescripts_messages import SendSurescriptsMedicationHistoryRequestEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class RequestMedicationHistoryOnAppointment(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.APPOINTMENT_CREATED)]
        def compute(self):
            patient_id = self.event.target.get("id")
            staff_id = self.event.context.get("created_by", {}).get("id")
            return [
                SendSurescriptsMedicationHistoryRequestEffect(
                    patient_id=patient_id,
                    staff_id=staff_id,
                ).apply()
            ]
    ```
##  Imports 
    ```python
    # Effects for sending requests
    from canvas_sdk.effects.surescripts.surescripts_messages import (
        SendSurescriptsBenefitsRequestEffect,
        SendSurescriptsEligibilityRequestEffect,
        SendSurescriptsMedicationHistoryRequestEffect,
    )
    # Data classes for parsing responses
    from canvas_sdk.events.surescripts import (
        BenefitCoverage,
        EligibilityPlan,
        SurescriptsBenefitsResponse,
        SurescriptsEligibilityResponse,
        TherapeuticAlternative,
    )
    ```

---

# TaskMetadata Effect

Source: https://docs.canvasmedical.com/sdk/effect-task-metadata/

The `TaskMetadata` effect provides a flexible key-value storage system for task-specific data within the Canvas system. This effect enables the creation and updating of custom metadata entries associated with task records, allowing for extensible task information storage beyond standard task fields.
##  Overview 
Task metadata serves as a powerful extension mechanism for storing custom task-related information that doesn't fit within the standard task data model.
##  Methods 
###  upsert(value: str) → Effect 
Creates or updates a metadata entry for the specified task and key combination.
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`value`| `str`| The metadata value to store| Yes  
####  Returns 
An `Effect` object configured for upserting task metadata.
####  Behavior 
  - If a metadata entry with the specified key already exists for the task, it will be updated with the new value
  - If no entry exists, a new metadata entry will be created
  - The operation is idempotent - repeated calls with the same key and value will not create duplicate entries
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`task_id`| `str`| Id of the task record to associate metadata with| Yes  
`key`| `str`| Unique identifier for the metadata entry within the task context| Yes  
##  Implementation Details 
###  Validation 
The effect performs comprehensive validation before execution:
  1. **Task Existence Validation** : Verifies that the referenced task exists in the system
  - Queries the task database to confirm the `task_id` corresponds to an existing task record
  - Returns a descriptive error if the task is not found
  1. **Field Validation** : Ensures all required fields are provided and properly formatted
  - Both `task_id` and `key` must be non-empty strings
  - The `value` parameter in the `upsert` method must be provided
###  Data Structure 
The effect payload is structured as JSON with the following schema:
    ```json
    {
      "data": {
        "task_id": "task-id",
        "key": "metadata-key",
        "value": "metadata-value"
      }
    }
    ```
##  Example Usage 
###  Basic Usage 
    ```python
    from canvas_sdk.effects.task import TaskMetadata
    # Create a metadata entry for task tracking
    metadata = TaskMetadata(
        task_id="550e8400e29b41d4a716446655440000",
        key="external_system_id"
    )
    # Upsert the metadata value
    effect = metadata.upsert("EXT-12345")
    ```
###  Task Integration Example 
    ```python
    import json
    from canvas_sdk.effects.task import TaskMetadata
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.events import EventType
    class TaskMetadataHandler(BaseHandler):
      """
      Adds metadata to tasks based on task properties.
      """
      RESPONDS_TO = EventType.Name(EventType.TASK_CREATED)
      def compute(self):
        task_id = self.context["task"]["id"]
        task_labels = self.context.get("task", {}).get("labels", [])
        effects = []
        # Store task creation source
        metadata = TaskMetadata(
          task_id=task_id,
          key="creation_source"
        )
        effects.append(metadata.upsert("protocol"))
        # Store label information as JSON
        if task_labels:
          labels_metadata = TaskMetadata(
            task_id=task_id,
            key="original_labels"
          )
          effects.append(labels_metadata.upsert(json.dumps(task_labels)))
        return effects
    ```
##  Best Practices 
###  Key Naming Conventions 
  1. **Use Descriptive Names** : Choose keys that clearly indicate the purpose of the metadata
  - Good: `external_system_id`, `workflow_stage`, `integration_source`
  - Avoid: `data1`, `temp`, `misc`
  1. **Namespace Your Keys** : When building integrations or modules, prefix keys to avoid collisions
  - Example: `integration_task_id`, `workflow_current_stage`, `automation_trigger_id`
###  Value Storage 
  1. **String Serialization** : All values are stored as strings. For complex data types:
         ```python
         # Storing JSON data
         import json
         from canvas_sdk.effects.task import TaskMetadata
         metadata = TaskMetadata(
             task_id="550e8400e29b41d4a716446655440000",
             key="workflow_state"
         )
         complex_data = {"stage": "review", "approvers": ["user1", "user2"], "timestamp": "2025-01-15T10:30:00Z"}
         metadata.upsert(json.dumps(complex_data))
         ```
  2. **Boolean Values** : Store as "true" or "false" strings for consistency
         ```python
         from canvas_sdk.effects.task import TaskMetadata
         needs_followup = True
         metadata = TaskMetadata(
             task_id="550e8400e29b41d4a716446655440000",
             key="requires_followup"
         )
         metadata.upsert("true" if needs_followup else "false")
         ```
##  Notes 
  - Metadata entries are task-specific and isolated - the same key can have different values for different tasks
  - There is no built-in versioning; updating a key overwrites the previous value
  - The system does not enforce any schema on metadata values - validation is the responsibility of the implementing code

---

# Tasks

Source: https://docs.canvasmedical.com/sdk/effect-tasks/

The Canvas SDK includes functionality to create, update and add comments to tasks in Canvas.
##  Adding a Task 
To add a task, build an `AddTask` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Creates the task.
  - `title` is required.
  - `id` is optional. Canvas generates one when it is omitted; set it yourself to reference the new task from another effect in the same handler, as in Creating a task and a comment together.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
id| string or UUID| Task unique UUID. If none is supplied, one is generated automatically.| No  
assignee_id| string| The id of the [staff](/sdk/data-staff/) the task should be assigned to.| No  
team_id| string| The id of the [team](/sdk/data-team/) the task should be assigned to.| No  
patient_id| string| The id of the [patient](/sdk/data-patient/) the task is associated with.| No  
title| string| The title of the task. This is displayed at the top of a task card in the Canvas UI.| Yes  
due| datetime| A date/time when the task is due.| No  
status| TaskStatus| A status of `OPEN`, `CLOSED` or `COMPLETED`. Defaults to `OPEN` if not supplied.| No  
priority| TaskPriority| A priority of `STAT`, `URGENT`, or `ROUTINE`. Defaults to no priority if not supplied.| No  
labels| list[string]| A list of labels that will be added at the bottom of a task card in the Canvas UI.| No  
author_id| string or UUID| Author's id to set task creator, defaults to CanvasBot.| No  
linked_object_id| string or UUID| Linked object id of linked object.| No  
linked_object_type| LinkableObjectType| Type of the LinkedObject| No  
###  Enumeration Types 
####  Linked Object Type 
Value| Description  
---|---  
REFERRAL| REFERRAL  
IMAGING| IMAGING  
####  TaskPriority 
Value| Description  
---|---  
STAT| The request should be actioned immediately — highest possible priority. E.g. an emergency.  
URGENT| The request should be actioned promptly — higher priority than routine.  
ROUTINE| The request has normal priority.  
###  Example 
An example of adding a task:
    ```python
    import arrow
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.task import AddTask, AddTaskComment, UpdateTask, TaskPriority, TaskStatus
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.lab import LabReport
    from canvas_sdk.v1.data.staff import Staff
    from canvas_sdk.v1.data.team import Team
    from canvas_sdk.v1.data.referral import Referral
    class MyHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.LAB_REPORT_CREATED),
        ]
        def compute(self) -> list[Effect]:
            lab_report = LabReport.objects.get(id=self.target)
            staff_assignee = Staff.objects.get(last_name="Weed")
            team = Team.objects.get(name="Labs")
            linked_task_type = AddTask.LinkableObjectType.REFERRAL
            referral = Referral.objects.get(id="d2194110-5c9a-4842-8733-ef09ea5ead11")
            if lab_report.patient:
                add_task = AddTask(
                    assignee_id=staff_assignee.id,
                    author_id=staff_assignee.id,
                    team_id = team.id,
                    patient_id=lab_report.patient.id,
                    title="Please call the patient with their test results.",
                    due=arrow.utcnow().shift(days=5).datetime,
                    status=TaskStatus.OPEN,
                    priority=TaskPriority.URGENT,
                    labels=["call"],
                    linked_object_id=referral.id,
                    linked_object_type=linked_task_type,
                )
                return [add_task.apply()]
            return []
    ```
##  Updating a Task 
To update an existing task, build an `UpdateTask` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Updates the task.
  - `id` is required, and must be the id of an existing task.
  - Only the attributes you set on the effect are changed. Attributes you leave unset keep their current values.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
id| string| The id of the task being updated.| Yes  
assignee_id| string| The id of the [staff](/sdk/data-staff/) the task should be assigned to.| No  
team_id| string| The id of the [team](/sdk/data-team/) the task should be assigned to.| No  
patient_id| string| The id of the [patient](/sdk/data-patient/) the task is associated with.| No  
title| string| The title of the task. This is displayed at the top of a task card in the Canvas UI.| No  
due| datetime| A date/time when the task is due.| No  
status| TaskStatus| A status of `OPEN`, `CLOSED` or `COMPLETED`.| No  
priority| TaskPriority| A priority of `STAT`, `URGENT`, or `ROUTINE`. See TaskPriority.| No  
labels| list[string]| A list of labels that will be added at the bottom of a task card in the Canvas UI.| No  
###  Example 
An example of updating a task to a status of `COMPLETED`:
    ```python
    from canvas_sdk.effects.task import UpdateTask, TaskStatus
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        def compute(self):
            update_task = UpdateTask(
                id="d06276ba-85c5-471b-87c0-9c9805f4ca6f",
                status=TaskStatus.COMPLETED,
            )
            return [update_task.apply()]
    ```
##  Adding a comment to a task 
To add a comment to a task, build an `AddTaskComment` and return its `apply()` from your handler.
###  Methods 
####  apply() → Effect 
Adds the comment to the task.
  - `task_id` and `body` are required. To comment on a task created in the same handler, see Creating a task and a comment together.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
task_id| string| The id of the task the comment is added to.| Yes  
body| string| The comment body.| Yes  
author_id| string or UUID| Author's id to set task comment creator, defaults to CanvasBot.| No  
###  Example 
    ```python
    from canvas_sdk.effects.task import AddTaskComment
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.staff import Staff
    class MyHandler(BaseHandler):
        def compute(self):
            author = Staff.objects.get(last_name="Weed")
            add_task_comment = AddTaskComment(
                task_id="d06276ba-85c5-471b-87c0-9c9805f4ca6f",
                body="I tried to call the patient but did not get an answer.",
                author_id=author.id
            )
            return [add_task_comment.apply()]
    ```
##  Creating a task and a comment together 
`AddTaskComment` requires the `task_id` of an existing task. To create a brand new task **and** add a comment to it in a single `compute()` return, supply your own `id` to `AddTask` and reuse that same value as the `task_id` on `AddTaskComment`. Because the `id` on `AddTask` is optional and is generated for you when omitted, the trick is simply to generate it yourself so you can reference it on the comment.
There is no need to create the task first and listen for a follow-up event — just return both effects from the same handler, with the `AddTask` effect before the `AddTaskComment` effect.
    ```python
    import uuid
    import arrow
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.task import AddTask, AddTaskComment, TaskStatus
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.LAB_REPORT_CREATED),
        ]
        def compute(self) -> list[Effect]:
            # Generate the task id up front so the comment can reference it.
            task_id = str(uuid.uuid4())
            add_task = AddTask(
                id=task_id,
                title="Please call the patient with their test results.",
                due=arrow.utcnow().shift(days=1).datetime,
                status=TaskStatus.OPEN,
            )
            add_task_comment = AddTaskComment(
                task_id=task_id,
                body="Results flagged abnormal — follow up today.",
            )
            # Order matters: the task must be created before the comment.
            return [add_task.apply(), add_task_comment.apply()]
    ```
> **Note:** The effects are applied in the order they are returned, so the `AddTask` effect must come before the `AddTaskComment` effect that references it. Both effects must be returned from the same handler — don't split them across separate handlers or plugins, and don't defer either effect, since that breaks the ordering the comment relies on.

---

# Effects

Source: https://docs.canvasmedical.com/sdk/effects/

Effects are instructions that plugins can return in order to perform an action in the Canvas EMR. This makes it possible to define workflows that create commands, show notifications, modify search results, etc.
Effects have a `type` and a `payload`. The `type` determines the action that will be performed with the data provided in the `payload`.
##  Using Effects 
###  Basic Usage 
Effects are returned as a list from the `compute` method of a plugin that inherits from `BaseHandler`. For example:
    ```python
    import json
    from canvas_sdk.events import EventType
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.handlers.base import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.MEDICATION_STATEMENT__MEDICATION__POST_SEARCH)
        def compute(self):
            results = self.context.get("results")
            post_processed_results = []
            ## custom results-modifying code here
            ...
            return [
                Effect(
                    type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS,
                    payload=json.dumps(post_processed_results),
                )
            ]
    ```
In the above example, the `Effect` object is constructed manually, with the `type` and `payload` set directly.
Some effects have helper classes that assist you by providing payload validation and constructing the effect object for you. The example below shows the [`PatientChartSummaryConfiguration`](/sdk/layout-effect/#patient-summary) class in use:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.effects.patient_chart_summary_configuration import PatientChartSummaryConfiguration
    class CustomChartLayout(BaseHandler):
        """
        This event handler rearranges the patient summary section and hides those
        not used by the installation's organization.
        """
        # This event fires when a patient's chart summary section is loading.
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION)
        def compute(self):
            layout = PatientChartSummaryConfiguration(sections=[
              PatientChartSummaryConfiguration.Section.SOCIAL_DETERMINANTS,
              PatientChartSummaryConfiguration.Section.ALLERGIES,
              PatientChartSummaryConfiguration.Section.VITALS,
              PatientChartSummaryConfiguration.Section.MEDICATIONS,
              PatientChartSummaryConfiguration.Section.CONDITIONS,
              PatientChartSummaryConfiguration.Section.IMMUNIZATIONS,
            ])
            return [layout.apply()]
    ```
###  Async Execution 
By default, effects returned from a plugin's `compute` method are executed inline as part of the request that triggered them. Any `Effect` can be opted into asynchronous execution by chaining `.set_async()` on it, in which case the platform will run the effect as an asynchronous task instead of inline. This is useful for effects that should run on a delay, that are tolerant of retries, or that you don't want to block the originating request.
    ```python
    from canvas_sdk.effects.claim import ClaimEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self):
            claim_id = self.event.context["claim_id"]
            return [
                ClaimEffect(claim_id=claim_id)
                .add_comment("Reviewed by automation.")
                .set_async(delay_seconds=60, max_retries=3)
            ]
    ```
`set_async()` returns the same `Effect` so it can be chained directly off any effect-producing call (e.g. `ClaimEffect(...).add_comment(...)`, `Response(...).apply()`, or a manually-constructed `Effect(...)`).
####  Parameters 
Parameter| Type| Description| Required  
---|---|---|---  
`delay_seconds`| `int`| Number of seconds to wait before running the effect. Must be non-negative. `0` schedules the effect to run asynchronously as soon as possible.| No  
`max_retries`| `int`| Maximum number of retry attempts on failure. Must be non-negative. When omitted, the platform default is applied. Pass `0` to explicitly disable retries.| No  
Both parameters are keyword-only. Calling `.set_async()` with neither argument is a no-op and returns the effect unchanged.
####  Implementation Details 
  - Negative values or non-integer values for `delay_seconds` or `max_retries` raise `TypeError` / `ValueError`.
###  Disallowed Effect/Event Combinations 
Canvas prevents certain combinations of events and effects to avoid infinite loops that could occur when an effect triggers the same event that generated it. The following combinations are specifically disallowed:
Event Type| Disallowed Effect Types  
---|---  
`PATIENT_CHART__CONDITIONS`| `ADD_BANNER_ALERT`  
`ADD_OR_UPDATE_PROTOCOL_CARD`  
`PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION`| `ADD_BANNER_ALERT`  
`ADD_OR_UPDATE_PROTOCOL_CARD`  
For example, if you have a plugin that responds to `PATIENT_CHART__CONDITIONS` events, you cannot return `ADD_BANNER_ALERT` or `ADD_OR_UPDATE_PROTOCOL_CARD` effects from that plugin, as this could create an infinite loop where the effect triggers another conditions event.
##  Effect Classes 
[ Appointment LabelsProgrammatically manage labels on appointments for categorization and automation. ](/sdk/effect-appointment-labels/)[ Appointment MetadataInteract with appointment metadata. ](/sdk/effect-appointment-metadata/)[ Appointment Metadata Create FormEffect for dynamically displaying forms when scheduling an appointment. ](/sdk/appointment-metadata-create-form-effect/)[ AppointmentsCreate, update, and cancel patient appointments. ](/sdk/effect-notes/#appointment-effect)[ Application Notification BadgeDisplay and update a notification badge count on an application icon. ](/sdk/effect-application-notification-badge/)[ Banner AlertsContextual information in a patient's chart. ](/sdk/effect-banner-alerts/)[ Batch Originate CommandsEfficiently insert multiple commands into a note in a single batch operation. ](/sdk/effect-batch-originate/)[ Billing Line ItemsAdd, modify, or remove billing codes on a note. ](/sdk/effect-billing-line-items/)[ C-CDA ExportCreate a C-CDA (Consolidated Clinical Document Architecture) document for a patient. ](/sdk/effect-create-ccda-export/)[ Charge Stored CardCharge a patient's stored payment card on file. ](/sdk/effect-charge-stored-card/)[ ClaimsManage labels, update line items, move to a queue, or post a payment. ](/sdk/effect-claims/)[ Command MetadataAttach custom key-value metadata to command records. ](/sdk/effect-command-metadata/)[ Configure Command ButtonsHide or disable command buttons in specific patient chart locations. ](/sdk/effect-configure-command-buttons/)[ Command Metadata Create formAdds additional fields to commands that are stored as command metadata. ](/sdk/command-metadata-create-form-effect/)[ Command ValidationValidate commands and return structured error messages to users. ](/sdk/effect-command-validation/)[ Compound MedicationsCreate or update compound medications. ](/sdk/effect-compound-medication/)[ CoverageCreate, update, expire, remove, and reorder a patient's insurance coverages. ](/sdk/effect-coverage/)[ Create CalendarCreate a calendar for a provider. ](/sdk/calendar-create-effect/)[ Create Patient Preferred PharmaciesCreate preferred pharmacies for a patient. ](/sdk/effect-create-patient-preferred-pharmacies/)[ Custom HTML and Django TemplatesRender custom HTML using Django templates. ](/sdk/layout-effect/#custom-html-and-django-templates)[ Data IntegrationManage documents in the Data Integration queue. ](/sdk/effect-data-integration/)[ Default HomepageSet a provider's default homepage in Canvas. ](/sdk/default-homepage-effect/)[ Event Validation ErrorEffect for blocking event creation with a validation error message. ](/sdk/effect-event-validation-error/)[ External EventsCreate or update external clinical events from ADT feeds. ](/sdk/effect-external-event/)[ FaxFax a note, referral, imaging order, lab order or letter. ](/sdk/effect-fax/)[ HTTP RequestHave the platform issue an HTTP request on behalf of a plugin. ](/sdk/effect-http-request/)[ Lab ReportCreate, update, enter-in-error, and attach results to a lab report. ](/sdk/effect-lab-report/)[ Layout EffectsModify or interact with the layout in Canvas. ](/sdk/layout-effect/)[ Manage Calendar EventsManage calendar events. ](/sdk/calendar-event-management-effects/)[ MessagesInteract with messages in Canvas. ](/sdk/effect-messages/)[ Note Custom ContentRender custom HTML blocks inside a clinical note. ](/sdk/effect-note-custom-content/)[ Note Footer ConfigurationConfigure a note's footer — for example, hide Canvas's default state-transition buttons. ](/sdk/effect-note-footer-configuration/)[ Note MetadataAttach custom key-value metadata to note records. ](/sdk/effect-note-metadata/)[ Note RestrictionsControl access to notes in real time — restrict editing, blur content, and show banners via plugin-driven effects. ](/sdk/effect-note-restrictions/)[ NotesInteract with notes in Canvas. ](/sdk/effect-notes/)[ ObservationsCreate or update clinical observations. ](/sdk/effect-observation/)[ PatientInteract with patient data. ](/sdk/effect-patient/)[ Patient Chart GroupEffect for grouping items on a patient chart section. ](/sdk/patient-chart-group-effect/)[ Patient Chart Summary Custom SectionServe content for a custom section in the patient chart summary. ](/sdk/patient-chart-summary-custom-section-effect/)[ Patient ConsentRecord a patient's decision on a consent and file the signed document. ](/sdk/effect-record-patient-consent/)[ Patient External IDCreate a new external identifier for a patient. ](/sdk/effect-create-patient-external-identifier/)[ Patient Facility AddressCreate, update, or delete patient facility address associations. ](/sdk/effect-patient-facility-address/)[ Patient GroupInteract with patient group data. ](/sdk/effect-patient-group/)[ Patient Identification CardCreate, update, or delete a patient's identification card images. ](/sdk/effect-patient-identification-card/)[ Patient MetadataInteract with patient metadata. ](/sdk/effect-patient-metadata/)[ Patient Metadata Create FormEffect for dynamically displaying forms in the Patient profile. ](/sdk/patient-metadata-create-form-effect/)[ Patient PortalCustomize your Patient Portal. ](/sdk/patient-portal/)[ Patient TimelineConfigure a patient's timeline by excluding specific note types. ](/sdk/effect-patient-timeline/)[ Payment ProcessorEffects returned by custom payment processors. ](/sdk/payment-processor-effect/)[ Phone Dial ConfigurationMake patient-chart phone numbers clickable for device or plugin dialing. ](/sdk/effect-phone-dial-configuration/)[ Protocol CardsCalls to action in a patient's chart, commonly used for decision support intervention. ](/sdk/effect-protocol-cards/)[ QuestionnairesInteract with questionnaires and interviews. ](/sdk/effect-questionnaires/)[ RedirectNavigate the Canvas frontend to an allowlisted URL, page, or application. ](/sdk/effect-redirect/)[ Reload Action ButtonsRe-evaluate a note's or patient's action buttons in real time. ](/sdk/effect-reload-action-buttons/)[ Send Contact VerificationSend an email or SMS verification to a patient contact point. ](/sdk/effect-send-contact-verification/)[ ServiceProviderCreate, update, and soft-deactivate providers in a customer-managed provider directory. ](/sdk/effect-service-provider/)[ Staff External IDCreate, update, or delete an external identifier for a staff member. ](/sdk/effect-staff-external-identifier/)[ Staff MetadataInteract with staff metadata. ](/sdk/effect-staff-metadata/)[ SurescriptsQuery insurance eligibility, medication history, and benefits through Surescripts. ](/sdk/effect-surescripts/)[ Task MetadataInteract with Task metadata. ](/sdk/effect-task-metadata/)[ TasksCreate or update tasks. ](/sdk/effect-tasks/)[ CommandsThe building blocks of many end-user workflows in Canvas, including nearly all clinical workflows for documentation. ](/sdk/commands/)
##  Effect Types 
The following effects are available to be applied in Canvas.
###  Banner Alerts & Protocol Cards 
Effect| Description  
---|---  
ADD_BANNER_ALERT| Can be used to [add a banner alert](/sdk/effect-banner-alerts/#adding-a-banner-alert) to a patient's chart.  
REMOVE_BANNER_ALERT| Can be used to [remove a banner alert](/sdk/effect-banner-alerts/#removing-a-banner-alert) from a patient's chart.  
ADD_OR_UPDATE_PROTOCOL_CARD| Can be used to generate a ProtocolCard in the Canvas UI. Use the [ProtocolCard](/sdk/effect-protocol-cards/) class in the effects module.  
###  Layout & Navigation 
Effect| Description  
---|---  
SHOW_PATIENT_CHART_SUMMARY_SECTIONS| Can be used to reorder or hide the summary sections in a patient chart. Check out [this effect class](/sdk/layout-effect/#patient-summary).  
PATIENT_CHART_SUMMARY__CUSTOM_SECTION| Can be used to serve content for a custom patient chart summary section. Check out [Patient Chart Summary Custom Section](/sdk/patient-chart-summary-custom-section-effect/).  
SHOW_PATIENT_PROFILE_SECTIONS| Can be used to reorder or hide sections in the patient profile. Check out [Layout Effects](/sdk/layout-effect/#patient-profile).  
SHOW_PANEL_SECTIONS| Can be used to reorder or hide sections in the side panel. Check out [Layout Effects](/sdk/layout-effect/#panel-configuration).  
SHOW_PATIENT_NOTE_HEADER_DROPDOWN_SECTIONS| Can be used to hide items in the note header triple dot button dropdown. Check out [this effect class](/sdk/layout-effect/#patient-note-header-dropdown-configuration).  
SHOW_PROVIDER_MENU_ITEMS| Can be used to hide items in the provider (hamburger) menu. Check out [Layout Effects](/sdk/layout-effect/#provider-menu-configuration).  
PATIENT_CHART__GROUP_ITEMS| Can be used to group items within a specific patient chart section. Check out [Patient Chart Group](/sdk/patient-chart-group-effect/).  
PATIENT_TIMELINE__CONFIGURATION| Can be used to configure the patient timeline display. Check out [Patient Timeline](/sdk/effect-patient-timeline/).  
HOMEPAGE_CONFIGURATION| Can be used to configure the homepage layout. Check out [Default Homepage](/sdk/default-homepage-effect/).  
SHOW_ACTION_BUTTON| Can be used to show an action button. Check out [Action Buttons](/sdk/handlers-action-buttons/) and [LaunchModalEffects](/sdk/layout-effect/#modals).  
RELOAD_ACTION_BUTTONS| Can be used to refresh a note's or patient's action buttons so they re-evaluate against the latest data. Check out [Reload Action Buttons](/sdk/effect-reload-action-buttons/).  
SHOW_APPLICATION| Can be used to show a custom application. Check out [Applications](/sdk/handlers-applications/) and [LaunchModalEffects](/sdk/layout-effect/#modals).  
SET_APPLICATION_NOTIFICATION_BADGE| Can be used to display or update a notification badge count on an application icon. Check out [Application Notification Badge](/sdk/effect-application-notification-badge/).  
REDIRECT_CONTEXT| Returned from a [`SSO__GET_POST_LOGIN_REDIRECT`](/sdk/events/) handler to override the URL the user lands on after SAML SSO login. See [SSO Capabilities](/sdk/sso/#redirect_context).  
REDIRECT| Navigate the browser to an allowlisted external URL, internal Canvas page, or application from any handler (e.g. after a note is signed). Check out [Redirect](/sdk/effect-redirect/).  
PHONE_DIAL__CONFIGURATION| Make the phone numbers in a patient chart clickable so a plugin can dial them or handle the click. Check out [Phone Dial Configuration](/sdk/effect-phone-dial-configuration/).  
PATIENT_CHART__CONFIGURE_COMMAND_BUTTONS| Can be used to hide or disable command buttons in specific patient chart locations. Check out [Configure Command Buttons](/sdk/effect-configure-command-buttons/).  
###  Search Results 
Effect| Description  
---|---  
AUTOCOMPLETE_SEARCH_RESULTS| Can be used to modify search results by re-ordering or adding text annotations to individual result records. To see how you can put this to use, check out [this guide](/guides/customize-search-results/).  
PATIENT_PROFILE__ADD_PHARMACY__POST_SEARCH_RESULTS| Can be used to modify pharmacy results when adding pharmacies in the patient profile.  
###  Annotations 
Check out [this guide](/guides/improve-hcc-coding-accuracy/#adding-annotations-to-conditions-and-detected-issues) for examples of using annotation effects.
Effect| Description  
---|---  
ANNOTATE_CLAIM_CONDITION_RESULTS| Add annotations to conditions appearing in a claim's detail view.  
ANNOTATE_PATIENT_CHART_CONDITION_RESULTS| Add an annotation to a condition within the patient summary.  
ANNOTATE_PATIENT_CHART_DETECTED_ISSUE_RESULTS| Add an annotation to a detected issue within the patient summary.  
###  Billing Line Items 
Check out the [Billing Line Items](/sdk/effect-billing-line-items/) effect class documentation.
Effect| Description  
---|---  
ADD_BILLING_LINE_ITEM| Generate a Billing Line Item in a note footer.  
UPDATE_BILLING_LINE_ITEM| Update an existing Billing Line Item in a note footer.  
REMOVE_BILLING_LINE_ITEM| Remove a Billing Line Item from a note footer.  
###  Tasks 
Check out the [Task Effects](/sdk/effect-tasks/) and [Task Metadata](/sdk/effect-task-metadata/) documentation.
Effect| Description  
---|---  
CREATE_TASK| Create a task from a plugin.  
UPDATE_TASK| Update an existing task.  
CREATE_TASK_COMMENT| Add a comment to an existing task.  
UPSERT_TASK_METADATA| Add or update metadata on a task.  
###  Command Metadata & Validation 
Effect| Description  
---|---  
UPSERT_COMMAND_METADATA| Add or update metadata on a command. Check out [Command Metadata](/sdk/effect-command-metadata/).  
SET_COMMAND_CUSTOM_HTML| Set or clear custom HTML content on a staged command. Check out [set_custom_html](/sdk/commands/#set_custom_html).  
COMMAND_AVAILABLE_ACTIONS_RESULTS| Sort or filter command available actions. Check out [Command Actions](/sdk/commands/#command-actions).  
COMMAND_VALIDATION_ERRORS| Return validation errors for commands. Check out [Command Validation](/sdk/effect-command-validation/).  
EVENT_VALIDATION_ERROR| Return validation errors for events. Check out [Event Validation Error](/sdk/effect-event-validation-error/).  
BATCH_ORIGINATE_COMMANDS| Originate multiple commands in a note at once. Check out [Batch Originate](/sdk/effect-batch-originate/).  
COMMAND__FORM__CREATE_ADDITIONAL_FIELDS| Returns additional fields to be displayed on a command and stored as command metadata. Check out [Command Metadata Create Form](/sdk/command-metadata-create-form-effect/).  
###  Notes 
Check out the [Note Effects](/sdk/effect-notes/) documentation.
Effect| Description  
---|---  
CREATE_NOTE| Create a note.  
UPDATE_NOTE| Update a note.  
LOCK_NOTE| Lock a note.  
UNLOCK_NOTE| Unlock a note.  
SIGN_NOTE| Sign a note.  
CHECK_IN_NOTE| Check in a note.  
NO_SHOW_NOTE| Mark a note as no-show.  
DELETE_NOTE| Delete a note.  
UNDELETE_NOTE| Restore a deleted note.  
DISCHARGE_NOTE| Lock and discharge an inpatient note.  
FAX_NOTE| Fax a note to an external recipient.  
PUSH_NOTE_CHARGES| Push note charges for billing.  
UPSERT_NOTE_METADATA| Add or update metadata on a note.  
GENERATE_FULL_CHART_PDF| Generate a full chart PDF for a patient.  
NOTE_RESTRICTIONS| Communicate whether a note is restricted for the requesting user, whether its content should be blurred, or what banner message to display. See [Note Restrictions](/sdk/effect-note-restrictions/).  
NOTE_RESTRICTIONS_UPDATED| Signal that note restrictions have changed, triggering an immediate real-time permission refetch on all users currently viewing that note. See [Note Restrictions](/sdk/effect-note-restrictions/).  
NOTE_FOOTER__CONFIGURATION| Configure a note's footer — for example, hide Canvas's default state-transition buttons so a plugin can supply its own. See [Note Footer Configuration](/sdk/effect-note-footer-configuration/).  
NOTE__CUSTOM_CONTENT| Render a custom content block inside a note, above the note body or within a note section. Available on instances in the [revamped note beta program](/product-updates/note-revamp/). See [Note Custom Content](/sdk/effect-note-custom-content/).  
###  Faxes 
Check out the [Fax Effects](/sdk/effect-fax/) documentation.
Effect| Description  
---|---  
FAX_NOTE| Fax a note to an external recipient.  
FAX_REFERRAL| Fax a referral and its attachments.  
FAX_IMAGING_ORDER| Fax an imaging order.  
FAX_LAB_ORDER| Fax a lab order's requisition form.  
FAX_LETTER| Fax a letter and its attachments.  
###  Appointments 
Check out the [Appointment Effects](/sdk/effect-notes/#appointment-effect), [Appointment Labels](/sdk/effect-appointment-labels/), and [Appointment Metadata](/sdk/effect-appointment-metadata/) documentation.
Effect| Description  
---|---  
CREATE_APPOINTMENT| Create an appointment.  
UPDATE_APPOINTMENT| Update an appointment.  
RESCHEDULE_APPOINTMENT| Reschedule an appointment.  
CANCEL_APPOINTMENT| Cancel an appointment.  
REVERT_APPOINTMENT| Revert a cancelled, converted, or no-showed appointment back to the booked state.  
ADD_APPOINTMENT_LABEL| Add one or more labels to an appointment (max 3 total).  
REMOVE_APPOINTMENT_LABEL| Remove one or more labels from an appointment.  
UPSERT_APPOINTMENT_METADATA| Add or update metadata on an appointment.  
###  Appointment Scheduling Form 
Check out the [Appointment Metadata Create Form](/sdk/appointment-metadata-create-form-effect/) documentation.
Effect| Description  
---|---  
APPOINTMENT__FORM__PROVIDERS__PRE_SEARCH_RESULTS| Modify the list of providers before a search.  
APPOINTMENT__FORM__LOCATIONS__PRE_SEARCH_RESULTS| Modify the list of locations before a search.  
APPOINTMENT__FORM__VISIT_TYPES__PRE_SEARCH_RESULTS| Modify the list of visit types before a search.  
APPOINTMENT__FORM__DURATIONS__PRE_SEARCH_RESULTS| Modify the list of durations before a search.  
APPOINTMENT__FORM__REASON_FOR_VISIT__PRE_SEARCH_RESULTS| Modify the reason for visit field before a search.  
APPOINTMENT__FORM__PROVIDERS__POST_SEARCH_RESULTS| Modify the list of providers after a search.  
APPOINTMENT__FORM__LOCATIONS__POST_SEARCH_RESULTS| Modify the list of locations after a search.  
APPOINTMENT__FORM__VISIT_TYPES__POST_SEARCH_RESULTS| Modify the list of visit types after a search.  
APPOINTMENT__FORM__DURATIONS__POST_SEARCH_RESULTS| Modify the list of durations after a search.  
APPOINTMENT__FORM__REASON_FOR_VISIT__POST_SEARCH_RESULTS| Modify the reason for visit field after a search.  
APPOINTMENT__FORM__CREATE_ADDITIONAL_FIELDS| Show additional fields on the appointment scheduling form.  
APPOINTMENT__SLOTS__POST_SEARCH_RESULTS| Modify slot availability when scheduling an appointment.  
###  Schedule Events 
Check out the [Schedule Event Effects](/sdk/effect-notes/#scheduleevent-effect) documentation.
Effect| Description  
---|---  
CREATE_SCHEDULE_EVENT| Create a schedule event.  
UPDATE_SCHEDULE_EVENT| Update a schedule event.  
DELETE_SCHEDULE_EVENT| Delete a schedule event.  
RESCHEDULE_SCHEDULE_EVENT| Reschedule a schedule event.  
###  Calendar 
Check out the [Create Calendar](/sdk/calendar-create-effect/) and [Manage Calendar Events](/sdk/calendar-event-management-effects/) documentation.
Effect| Description  
---|---  
CALENDAR__CREATE| Create a calendar.  
CALENDAR__EVENT__CREATE| Create a calendar event.  
CALENDAR__EVENT__UPDATE| Update a calendar event.  
CALENDAR__EVENT__DELETE| Delete a calendar event.  
###  Patients 
Check out the [Patient Effects](/sdk/effect-patient/), [Patient Metadata](/sdk/effect-patient-metadata/), [Patient External ID](/sdk/effect-create-patient-external-identifier/), [Patient Facility Address](/sdk/effect-patient-facility-address/), [Patient Identification Card](/sdk/effect-patient-identification-card/), and [Record Patient Consent](/sdk/effect-record-patient-consent/) documentation.
Effect| Description  
---|---  
CREATE_PATIENT| Create a patient.  
UPDATE_PATIENT| Update a patient.  
UPDATE_USER| Update a user.  
PATIENT_METADATA__CREATE_ADDITIONAL_FIELDS| Show additional fields on the patient profile section.  
UPSERT_PATIENT_METADATA| Add or update metadata on a patient.  
CREATE_PATIENT_EXTERNAL_IDENTIFIER| Create an external identifier for a patient.  
CREATE_PATIENT_PREFERRED_PHARMACIES| Set preferred pharmacies for a patient.  
CREATE_PATIENT_FACILITY_ADDRESS| Create a facility address for a patient.  
UPDATE_PATIENT_FACILITY_ADDRESS| Update a facility address for a patient.  
DELETE_PATIENT_FACILITY_ADDRESS| Delete a facility address for a patient.  
RECORD_PATIENT_CONSENT| Record a patient's decision on a consent and file the signed document.  
CREATE_PATIENT_IDENTIFICATION_CARD| Add an identification card image for a patient.  
UPDATE_PATIENT_IDENTIFICATION_CARD| Change a patient's identification card.  
DELETE_PATIENT_IDENTIFICATION_CARD| Delete a patient's identification card.  
###  Coverage 
Check out the [Coverage Effect](/sdk/effect-coverage/) documentation.
Effect| Description  
---|---  
CREATE_COVERAGE| Create an insurance coverage for a patient, with optional card images.  
UPDATE_COVERAGE| Change an existing coverage.  
EXPIRE_COVERAGE| End a coverage on a given date.  
REMOVE_COVERAGE| Move a coverage to the removed stack.  
REMOVE_COVERAGE_PHOTO| Remove the front or back card image from a coverage.  
REORDER_COVERAGE| Change the rank and stack of a patient's coverages.  
###  Patient Groups 
Check out the [Patient Group](/sdk/effect-patient-group/) documentation.
Effect| Description  
---|---  
PATIENT_GROUP__ADD_MEMBER| Add a member to a patient group.  
PATIENT_GROUP__DEACTIVATE_MEMBER| Deactivate a member from a patient group.  
###  Staff 
Effect| Description  
---|---  
[UPSERT_STAFF_METADATA](/sdk/effect-staff-metadata/)| Insert or update a key/value metadata entry on a staff member.  
[DELETE_STAFF_METADATA](/sdk/effect-staff-metadata/)| Remove a key/value metadata entry from a staff member.  
[CREATE_STAFF_EXTERNAL_IDENTIFIER](/sdk/effect-staff-external-identifier/)| Create a new external identifier on a staff member.  
[UPDATE_STAFF_EXTERNAL_IDENTIFIER](/sdk/effect-staff-external-identifier/)| Update fields on an existing external identifier.  
[DELETE_STAFF_EXTERNAL_IDENTIFIER](/sdk/effect-staff-external-identifier/)| Delete an external identifier from a staff member.  
###  Messages 
Check out the [Message Effects](/sdk/effect-messages/) documentation.
Effect| Description  
---|---  
CREATE_MESSAGE| Create a message.  
SEND_MESSAGE| Send a message.  
CREATE_AND_SEND_MESSAGE| Create and send a message in one step.  
EDIT_MESSAGE| Edit a message.  
[ASSIGN_MESSAGE_TEAM](/sdk/effect-messages/#assigning-a-message-to-a-team)| Assign a message to a team, change its team, or unassign it.  
###  Observations 
Check out the [Observation Effects](/sdk/effect-observation/) documentation.
Effect| Description  
---|---  
CREATE_OBSERVATION| Create an observation.  
UPDATE_OBSERVATION| Update an observation.  
ENTER_IN_ERROR_OBSERVATION| Mark an observation as entered in error.  
###  Lab Reports 
Check out the [Lab Report Effects](/sdk/effect-lab-report/) documentation.
Effect| Description  
---|---  
CREATE_LAB_REPORT| Create a lab report decoupled from its results (no order, PDF, or values required).  
UPDATE_LAB_REPORT| Update lab report metadata, such as its name or effective date.  
ENTER_IN_ERROR_LAB_REPORT| Mark a lab report as entered in error.  
ATTACH_LAB_REPORT_RESULTS| Attach lab tests and values to an existing report (additive).  
###  Questionnaire 
Check out the [Questionnaire Effects](/sdk/effect-questionnaires/) documentation.
Effect| Description  
---|---  
CREATE_QUESTIONNAIRE| Create a questionnaire at runtime from a plugin.  
CREATE_QUESTIONNAIRE_RESULT| Create a questionnaire result.  
###  Compound Medications 
Check out the [Compound Medication Effects](/sdk/effect-compound-medication/) documentation.
Effect| Description  
---|---  
CREATE_COMPOUND_MEDICATION| Create a compound medication.  
UPDATE_COMPOUND_MEDICATION| Update a compound medication.  
###  Service Providers 
Check out the [Service Provider Effects](/sdk/effect-service-provider/) documentation.
Effect| Description  
---|---  
CREATE_SERVICE_PROVIDER| Create a service provider, or update a matching one.  
UPDATE_SERVICE_PROVIDER| Update a service provider.  
DEACTIVATE_SERVICE_PROVIDER| Deactivate a service provider without deleting it.  
###  External Events 
Check out the [External Event Effects](/sdk/effect-external-event/) documentation.
Effect| Description  
---|---  
CREATE_EXTERNAL_EVENT| Create an external event.  
UPDATE_EXTERNAL_EVENT| Update an external event.  
###  CCDA 
Check out the [C-CDA Export](/sdk/effect-create-ccda-export/) documentation.
Effect| Description  
---|---  
CREATE_CCDA| Create a CCDA document.  
###  Claims 
Check out the [Claims Effects](/sdk/effect-claims/) documentation.
Effect| Description  
---|---  
POST_CLAIM_PAYMENT| Post a payment to a claim.  
MOVE_CLAIM_TO_QUEUE| Move a claim to a different queue.  
ADD_CLAIM_LABEL| Add a label to a claim.  
REMOVE_CLAIM_LABEL| Remove a label from a claim.  
ADD_CLAIM_COMMENT| Add a comment to a claim.  
ADD_CLAIM_BANNER_ALERT| Add a banner alert to a claim.  
REMOVE_CLAIM_BANNER_ALERT| Remove a banner alert from a claim.  
UPDATE_CLAIM_PROVIDER| Update the provider on a claim.  
UPSERT_CLAIM_METADATA| Add or update metadata on a claim.  
UPDATE_CLAIM_LINE_ITEM| Update a line item on a claim.  
###  Patient Portal 
Check out the [Patient Portal](/sdk/patient-portal/) documentation.
Effect| Description  
---|---  
PORTAL_WIDGET| Add widgets to the patient portal landing page.  
SHOW_PATIENT_PORTAL_MENU_ITEMS| Configure menu items in the patient portal. Check out [Patient Portal](/sdk/patient-portal/#configure-portal-menu-items).  
PATIENT_PORTAL__APPLICATION_CONFIGURATION| Configure the patient portal application.  
PATIENT_PORTAL__FORM_RESULT| Return form results in the patient portal.  
PATIENT_PORTAL__APPOINTMENT_SHOW_MEETING_LINK| Show the 'join' button on the telehealth appointment card.  
PATIENT_PORTAL__APPOINTMENT_IS_CANCELABLE| Show the 'cancel' button on the appointment card.  
PATIENT_PORTAL__APPOINTMENT_IS_RESCHEDULABLE| Show the 'reschedule' button on the appointment card.  
PATIENT_PORTAL__SEND_INVITE| Trigger a portal invitation for a user.  
PATIENT_PORTAL__SEND_CONTACT_VERIFICATION| Send an email or SMS verification to a patient contact point. Works for any patient contact point, not just the portal. Check out [Send Contact Verification](/sdk/effect-send-contact-verification/).  
PATIENT_PORTAL__APPOINTMENTS__SLOTS__POST_SEARCH_RESULTS| Modify slot availability in the patient portal appointment scheduler.  
PATIENT_PORTAL__APPOINTMENTS__FORM_APPOINTMENT_TYPES__PRE_SEARCH_RESULTS| Modify appointment types in the patient portal before a search.  
PATIENT_PORTAL__APPOINTMENTS__FORM_APPOINTMENT_TYPES__POST_SEARCH_RESULTS| Modify appointment types in the patient portal after a search.  
PATIENT_PORTAL__APPOINTMENTS__FORM_LOCATIONS__PRE_SEARCH_RESULTS| Modify locations in the patient portal before a search.  
PATIENT_PORTAL__APPOINTMENTS__FORM_LOCATIONS__POST_SEARCH_RESULTS| Modify locations in the patient portal after a search.  
PATIENT_PORTAL__APPOINTMENTS__FORM_PROVIDERS__PRE_SEARCH_RESULTS| Modify providers in the patient portal before a search.  
PATIENT_PORTAL__APPOINTMENTS__FORM_PROVIDERS__POST_SEARCH_RESULTS| Modify providers in the patient portal after a search.  
###  Simple API 
Check out the [HTTP](/sdk/handlers-simple-api-http/) and [WebSocket](/sdk/handlers-simple-api-websocket/) SimpleAPI documentation.
Effect| Description  
---|---  
SIMPLE_API_RESPONSE| Return a response from a SimpleAPI HTTP endpoint.  
SIMPLE_API_WEBSOCKET_BROADCAST| Broadcast a message to WebSocket connections.  
###  HTTP Requests 
Check out the [HTTP Request](/sdk/effect-http-request/) documentation.
Effect| Description  
---|---  
HTTP_REQUEST| Have the platform issue an HTTP request on behalf of a plugin. Most useful when chained with [`.set_async(...)`](/sdk/effect-http-request/#async-execution) so the platform's async runner handles delay, retries, and retry-on-status-code behavior.  
###  Revenue / Payment Processor 
Effect| Description  
---|---  
REVENUE__STORED_CARD__CHARGE| Charge a patient's stored payment card on file. Check out [Charge Stored Card](/sdk/effect-charge-stored-card/).  
REVENUE__PAYMENT_PROCESSOR__METADATA| Advertises a custom payment processor to Canvas. Use the [PaymentProcessorMetadata](/sdk/payment-processor-effect/#paymentprocessormetadata) class in the effects module.  
REVENUE__PAYMENT_PROCESSOR__FORM| Returns the HTML form used to collect and tokenize card details. Use the [PaymentProcessorForm](/sdk/payment-processor-effect/#paymentprocessorform) class in the effects module.  
REVENUE__PAYMENT_PROCESSOR__CREDIT_CARD_TRANSACTION| Returns the result of charging a card. Use the [CardTransaction](/sdk/payment-processor-effect/#cardtransaction) class in the effects module.  
REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHOD| Returns a patient's saved payment method. Use the [PaymentMethod](/sdk/payment-processor-effect/#paymentmethod) class in the effects module.  
REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHOD__ADD_RESPONSE| Returns the result of adding a payment method. Use the [AddPaymentMethodResponse](/sdk/payment-processor-effect/#addpaymentmethodresponse) class in the effects module.  
REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHOD__REMOVE_RESPONSE| Returns the result of removing a payment method. Use the [RemovePaymentMethodResponse](/sdk/payment-processor-effect/#removepaymentmethodresponse) class in the effects module.  
###  Surescripts 
Check out the [Surescripts Effects](/sdk/effect-surescripts/) documentation.
Effect| Description  
---|---  
SEND_SURESCRIPTS_ELIGIBILITY_REQUEST| Can be used to send a Surescripts eligibility request. See [Eligibility](/sdk/effect-surescripts/#eligibility).  
SEND_SURESCRIPTS_BENEFITS_REQUEST| Can be used to send a Surescripts benefits request. See [Benefits](/sdk/effect-surescripts/#benefits).  
SEND_SURESCRIPTS_MEDICATION_HISTORY_REQUEST| Can be used to send a Surescripts medication history request. See [Medication History](/sdk/effect-surescripts/#medication-history).  
###  Data Integration 
Check out the [Data Integration Effects](/sdk/effect-data-integration/) documentation.
Effect| Description  
---|---  
ASSIGN_DOCUMENT_REVIEWER| Assign a staff member or team as reviewer to a document in the Data Integration queue.  
CATEGORIZE_DOCUMENT| Categorize a document in the Data Integration queue into a specific document type.  
JUNK_DOCUMENT| Mark a document in the Data Integration queue as junk (spam).  
LINK_DOCUMENT_TO_PATIENT| Link a document in the Data Integration queue to a patient by patient id.  
REMOVE_DOCUMENT_FROM_PATIENT| Remove or unlink a document from a patient in the Data Integration queue.  
UPDATE_DOCUMENT_FIELDS| Prefill template field values on a document in the Data Integration queue (`PrefillDocumentFields` class).  
###  Commands 
Check out the [Commands documentation](/sdk/commands/) for full details.
Command effects follow a consistent naming pattern: `{ACTION}_{COMMAND_TYPE}_COMMAND`. The available actions are:
Action| Description  
---|---  
ORIGINATE| Create and open a new command in a note. Supports an optional `commit` flag to also commit the command in the same operation if the command is commit-able via SDK.  
EDIT| Modify field values on an existing command.  
DELETE| Remove an uncommitted command from a note.  
COMMIT| Finalize and save a command.  
ENTER_IN_ERROR| Mark a committed command as entered in error.  
SEND| Transmit a committed command to an external system (prescribe, refill, adjust prescription, lab orders only).  
REVIEW| Place a command into review status (prescribe, refill, adjust prescription only).  
DELEGATE| Delegate the order to someone else to complete (imaging order, refer only).  
SIGN| Sign the order (imaging order, order DME, refer only).  
The following command types support `ORIGINATE`, `EDIT`, `DELETE`, `COMMIT`, and `ENTER_IN_ERROR` actions unless noted otherwise:
Command Type| Effect Prefix| Notes  
---|---|---  
Add Condition| `*_ADD_CONDITION_COMMAND`|   
Adjust Prescription| `*_ADJUST_PRESCRIPTION_COMMAND`| No COMMIT. Supports SEND and REVIEW  
Allergy| `*_ALLERGY_COMMAND`|   
Assess| `*_ASSESS_COMMAND`|   
Change Medication| `*_CHANGE_MEDICATION_COMMAND`|   
Chart Section Review| `*_CHART_SECTION_REVIEW_COMMAND`| ORIGINATE only  
Close Goal| `*_CLOSE_GOAL_COMMAND`|   
Custom Command| `*_CUSTOM_COMMAND_COMMAND`| ORIGINATE, ENTER_IN_ERROR  
Diagnose| `*_DIAGNOSE_COMMAND`|   
Exam| `*_EXAM_COMMAND`|   
Family History| `*_FAMILY_HISTORY_COMMAND`|   
Follow Up| `*_FOLLOW_UP_COMMAND`|   
Goal| `*_GOAL_COMMAND`|   
HPI| `*_HPI_COMMAND`|   
Imaging Order| `*_IMAGING_ORDER_COMMAND`| No COMMIT or SEND. Supports DELEGATE and SIGN  
Imaging Review| `*_IMAGING_REVIEW_COMMAND`|   
Immunization Statement| `*_IMMUNIZATION_STATEMENT_COMMAND`|   
Immunize| `*_IMMUNIZE_COMMAND`|   
Instruct| `*_INSTRUCT_COMMAND`|   
Lab Order| `*_LAB_ORDER_COMMAND`| Also supports SEND  
Lab Review| `*_LAB_REVIEW_COMMAND`|   
Medical History| `*_MEDICAL_HISTORY_COMMAND`|   
Medication Statement| `*_MEDICATION_STATEMENT_COMMAND`|   
Order DME| `*_ORDER_DME_COMMAND`| Also supports SIGN  
Perform| `*_PERFORM_COMMAND`|   
Plan| `*_PLAN_COMMAND`|   
POC Lab Test| `*_POC_LAB_TEST_COMMAND`|   
Prescribe| `*_PRESCRIBE_COMMAND`| No COMMIT. Supports SEND and REVIEW  
Questionnaire| `*_QUESTIONNAIRE_COMMAND`|   
Reason For Visit| `*_REASON_FOR_VISIT_COMMAND`| ORIGINATE, EDIT, DELETE only  
Refer| `*_REFER_COMMAND`| No COMMIT. Supports DELEGATE and SIGN  
Reference| `*_REFERENCE_COMMAND`| EDIT does not refresh the rendered table  
Referral Review| `*_REFERRAL_REVIEW_COMMAND`|   
Refill| `*_REFILL_COMMAND`| No COMMIT. Supports SEND and REVIEW  
Remove Allergy| `*_REMOVE_ALLERGY_COMMAND`|   
Remove Past Medical History| `*_REMOVE_PAST_MEDICAL_HISTORY_COMMAND`|   
Resolve Condition| `*_RESOLVE_CONDITION_COMMAND`|   
Review of Systems| `*_ROS_COMMAND`|   
Stop Medication| `*_STOP_MEDICATION_COMMAND`|   
Structured Assessment| `*_STRUCTURED_ASSESSMENT_COMMAND`|   
Surgical History| `*_SURGICAL_HISTORY_COMMAND`|   
Task| `*_TASK_COMMAND`|   
Uncategorized Document Review| `*_UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND`|   
Update Diagnosis| `*_UPDATE_DIAGNOSIS_COMMAND`|   
Update Goal| `*_UPDATE_GOAL_COMMAND`|   
Visual Exam Finding| `*_VISUAL_EXAM_FINDING_COMMAND`|   
Vitals| `*_VITALS_COMMAND`|   

---

# Events

Source: https://docs.canvasmedical.com/sdk/events/

**What is an Event?**
An event is an occurrence of an action that happens within Canvas. For example, a patient being prescribed a medication, a user searching for a condition or an appointment being created are all examples of events.
**Why should I use them?**
By writing plugins that respond to events, plugin code is notified and can react to events that occur in Canvas. This enables plugin authors to create custom workflows whenever a relevant event takes place, such as making a POST request to a webhook.
**How do I use them?**
To make plugin code react to an event, you can add the event types listed below into the `RESPONDS_TO` list of a plugin that inherits from `BaseHandler`. For example:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.ALLERGY_INTOLERANCE_CREATED)]
        def compute(self):
            ...
    ```
The plugin author can enter custom workflow code into the `compute` method that will execute every time an Allergy Intolerance is created in Canvas.
For more information on writing plugins, see the guide [here](/guides/your-first-plugin/).
> **Info:** A handler's `compute` method runs only for the events listed in its `RESPONDS_TO`, which can be a single event name or a list. A handler with no `RESPONDS_TO`, or one that leaves out the event you expect, installs and enables without error but never runs. If `compute` never fires, check that `RESPONDS_TO` names the right event.
###  Sending outbound webhooks 
A common pattern is to send an outbound webhook to a third-party system when something changes in Canvas. To do this, write a handler that responds to the relevant events, builds a custom payload, and sends it to your external URL (see [making HTTP requests](/sdk/utils/#post)). You have full control over the payload shape. The event itself typically gives you the entity id and patient id; use the [data modules](/sdk/data/) to enrich the payload with additional details — for example, retrieve a patient's email address from a [`PatientContactPoint`](/sdk/data-patient/#patientcontactpoint). Store the destination URL as a plugin [secret](/sdk/secrets/) rather than hard-coding it.
For firewall allowlisting, outbound events (such as note state change webhooks) are sent from one of three static source IP addresses:
  - `52.70.89.15`
  - `54.86.133.235`
  - `34.197.78.70`
##  Event Actor 
The actor is the user that initiated the event. It can be accessed within the compute method of the plugin by `self.event.actor`. For side-effect events or automated events where the action cannot be attributed to a specific user, the actor may be absent.
The actor is available in the following contexts:
  - [**SimpleAPI**](/sdk/handlers-simple-api/) handlers — HTTP and WebSocket requests
  - [**Action button**](/sdk/handlers-action-buttons/) handlers — button display and click events
  - [**Application**](/sdk/handlers-applications/) handlers
  - **Note state change events** — `NOTE_STATE_CHANGE_EVENT_PRE_CREATE`, `NOTE_STATE_CHANGE_EVENT_CREATED`, `NOTE_STATE_CHANGE_EVENT_UPDATED`
  - **Note UI events** — `NOTE_OPENED`, `NOTE_CLOSED`
  - **Note restrictions events** — `GET_NOTE_RESTRICTIONS`
  - **Note footer events** — `NOTE_FOOTER__GET_CONFIGURATION`
  - **Phone dial events** — `PHONE_DIAL__GET_CONFIGURATION`, `PHONE_NUMBER_CLICKED`
  - **Appointment scheduling events** — all `APPOINTMENT__*` events
  - **Patient chart and profile events** — all `PATIENT_CHART__*` events (conditions, medications, detected issues, etc.), chart summary configuration, panel sections, and patient metadata
  - **Patient timeline events** — `PATIENT_TIMELINE__GET_CONFIGURATION`
  - **Homepage events** — `GET_HOMEPAGE_CONFIGURATION`
  - **Command additional-fields events** — `COMMAND__FORM__GET_ADDITIONAL_FIELDS`
  - **Lab order command events** — `LAB_ORDER_COMMAND__PRE_SEND`, `HEALTH_GORILLA_LAB_ORDER_PREPARED`
  - **Claim events** — `CLAIM__CONDITIONS`
  - **SSO events** — `SSO__PROCESS_ADDITIONAL_REQUEST_DATA`, `SSO__GET_POST_LOGIN_REDIRECT`
  - **Payment processor events** — all `REVENUE__PAYMENT_PROCESSOR__*` events
  - **Stored card charge events** — `REVENUE__STORED_CARD__CHARGE_RESPONSE`, carrying the actor of the effect that requested the charge
  - **Patient portal events** — all `PATIENT_PORTAL__*` events
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    class CustomHandler(BaseHandler):
        RESPONDS_TO = []
        def compute(self) -> list[Effect]:
            actor = self.event.actor
            log.info(actor.dbid)        # The database ID of the actor, if available
            log.info(actor.instance)  # The corresponding CanvasUser instance
            log.info(actor.instance.person_subclass) # The corresponding Staff or Patient instance
            return []
    ```
##  Event Types and Context 
The event `target` object can be accessed within the compute method of the plugin by `self.event.target`. If `self.event.target.type` exists, it provides the same type that would be imported from the Data module. For example, a type of `Condition` would be the same as what you can import from `canvas_sdk.v1.data.condition`.
The event `context` object can be accessed via `self.event.context`. The content present in each event's context depends on the event type. The table below shows what you can expect for each event type, or you could take a look yourself by logging it out.
###  Common Context Patterns 
Many events include common contextual information to help you understand the scope and origin of the event:
  - **Patient context** : Most patient-related events include `"patient": {"id": pt_id}` in the context, allowing you to identify which patient the event relates to.
  - **Note context** : Command lifecycle events (PRE_COMMIT, POST_COMMIT, etc.) include `"note": {"uuid": note_id}` in the context, indicating the note where the command was executed.
  - **User context** : All command-related PRE_SEARCH and POST_SEARCH events include `"user": {"staff": staff_key}` in the context, containing the staff key of the user performing the search. This allows you to customize search results based on user-specific preferences, roles, or permissions.
  - **Search results context** : Command POST_SEARCH events include `"results"`, the list the search returned. Command PRE_SEARCH events fire before the search runs, so their context holds only `search_term` and `user`. To modify the results a search returns, respond to the POST_SEARCH event. When several handlers respond to the same PRE_SEARCH event, a handler that runs after one that returned an `AUTOCOMPLETE_SEARCH_RESULTS` effect finds those results in `"results"`.
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    class MyHandler(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.ALLERGY_INTOLERANCE_CREATED)]
        def compute(self):
            log.info(self.event.context)
            return []
    ```
###  Record lifecycle events 
These events fire as a result of records being created, updated, or deleted.
####  Patients 
PATIENT_CREATED  
---  
Occurs when a patient is created.  
Target object| Context object  
    "id": pt_id
    "type": [Patient](/sdk/data-patient/)
| 
    empty  
> **Info:** When a patient is created through the FHIR API, Canvas saves the patient and fires `PATIENT_CREATED` before it saves the patient's external identifiers. It then fires `PATIENT_EXTERNAL_IDENTIFIER_CREATED` for each identifier, and only then does the FHIR create finish. So a `PATIENT_CREATED` handler can't see the identifiers yet. To act on them, for example to recognize a patient your own FHIR POST created, listen for `PATIENT_EXTERNAL_IDENTIFIER_CREATED` instead.
PATIENT_UPDATED  
---  
Occurs when a patient's data is updated.  
Target object| Context object  
    "id": pt_id
    "type": [Patient](/sdk/data-patient/)
| 
    empty  
PATIENT_PREFERRED_PHARMACY_UPDATED  
---  
Occurs when a patient's preferred pharmacy is created or updated.  
Target object| Context object  
    "id": pt_id
    "type": [Patient](/sdk/data-patient/)
| 
    "patient":
        "id": pt_id  
CARE_TEAM_MEMBERSHIP_CREATED  
---  
Occurs when a new care team member is added for a patient.  
Target object| Context object  
    "id": care_team_membership_id
    "type": [CareTeamMembership](/sdk/data-care-team/#careteammembership)
| 
    "patient":
        "id": pt_id  
CARE_TEAM_MEMBERSHIP_UPDATED  
---  
Occurs when a care team member is adjusted for a patient.  
Target object| Context object  
    "id": care_team_membership_id
    "type": [CareTeamMembership](/sdk/data-care-team/#careteammembership)
| 
    "patient":
        "id": pt_id  
CARE_TEAM_MEMBERSHIP_DELETED  
---  
Occurs when a care team member is removed for a patient.  
Target object| Context object  
    "id": care_team_membership_id
    "type": [CareTeamMembership](/sdk/data-care-team/#careteammembership)
| 
    "patient":
        "id": pt_id  
PATIENT_ADDRESS_CREATED  
---  
Occurs when an address is added for a patient.  
Target object| Context object  
    "id": address_id
    "type": [PatientAddress](/sdk/data-patient/#patientaddress)
| 
    "patient":
        "id": pt_id  
PATIENT_ADDRESS_UPDATED  
---  
Occurs when one of a patient's addresses is updated.  
Target object| Context object  
    "id": address_id
    "type": [PatientAddress](/sdk/data-patient/#patientaddress)
| 
    "patient":
        "id": pt_id  
PATIENT_ADDRESS_DELETED  
---  
Occurs when one of a patient's addresses is removed.  
Target object| Context object  
    "id": address_id
    "type": [PatientAddress](/sdk/data-patient/#patientaddress)
| 
    "patient":
        "id": pt_id  
PATIENT_CONTACT_PERSON_CREATED  
---  
Occurs when a contact is added for a patient.  
Target object| Context object  
    "id": contact_person_id
    "type": None
| 
    "patient":
        "id": pt_id  
PATIENT_CONTACT_PERSON_UPDATED  
---  
Occurs when one of a patient's contacts is updated.  
Target object| Context object  
    "id": contact_person_id
    "type": None
| 
    "patient":
        "id": pt_id  
PATIENT_CONTACT_PERSON_DELETED  
---  
Occurs when one of a patient's contacts is removed.  
Target object| Context object  
    "id": contact_person_id
    "type": None
| 
    "patient":
        "id": pt_id  
PATIENT_CONTACT_POINT_CREATED  
---  
Occurs when a contact method for a patient is added.  
Target object| Context object  
    "id": contact_point_id
    "type": [PatientContactPoint](/sdk/data-patient/#patientcontactpoint)
| 
    "patient":
        "id": pt_id  
PATIENT_CONTACT_POINT_UPDATED  
---  
Occurs when a contact method for a patient is updated.  
Target object| Context object  
    "id": contact_point_id
    "type": [PatientContactPoint](/sdk/data-patient/#patientcontactpoint)
| 
    "patient":
        "id": pt_id  
PATIENT_CONTACT_POINT_DELETED  
---  
Occurs when a contact method for a patient is removed.  
Target object| Context object  
    "id": contact_point_id
    "type": [PatientContactPoint](/sdk/data-patient/#patientcontactpoint)
| 
    "patient":
        "id": pt_id  
PATIENT_EXTERNAL_IDENTIFIER_CREATED  
---  
Occurs when an external identifier is created for a patient.  
Target object| Context object  
    "id": patientexternalidentifier_id
    "type": [PatientExternalIdentifier](/sdk/data-patient/#patientexternalidentifier)
| 
    "patient":
        "id": pt_id  
PATIENT_EXTERNAL_IDENTIFIER_UPDATED  
---  
Occurs when an external identifier for a patient is updated.  
Target object| Context object  
    "id": patientexternalidentifier_id
    "type": [PatientExternalIdentifier](/sdk/data-patient/#patientexternalidentifier)
| 
    "patient":
        "id": pt_id  
PATIENT_EXTERNAL_IDENTIFIER_DELETED  
---  
Occurs when an external identifier for a patient is deleted.  
Target object| Context object  
    "id": patientexternalidentifier_id
    "type": [PatientExternalIdentifier](/sdk/data-patient/#patientexternalidentifier)
| 
    "patient":
        "id": pt_id  
####  Patient Facility Address 
PATIENT_FACILITY_ADDRESS_CREATED  
---  
Occurs when a patient facility address is created.  
Target object| Context object  
    "id": patientfacilityaddress_id
    "type": [PatientFacilityAddress](/sdk/data-patient/#patientfacilityaddress)
| 
    "patient":
        "id": pt_id  
PATIENT_FACILITY_ADDRESS_UPDATED  
---  
Occurs when a patient facility address is updated.  
Target object| Context object  
    "id": patientfacilityaddress_id
    "type": [PatientFacilityAddress](/sdk/data-patient/#patientfacilityaddress)
| 
    "patient":
        "id": pt_id  
PATIENT_FACILITY_ADDRESS_DELETED  
---  
Occurs when a patient facility address is deleted. Deleting a facility address also fires `PATIENT_ADDRESS_DELETED` (see note below).  
Target object| Context object  
    "id": patientfacilityaddress_id
    "type": [PatientFacilityAddress](/sdk/data-patient/#patientfacilityaddress)
| 
    "patient":
        "id": pt_id  
> **Info:** Facility addresses have their own `PATIENT_FACILITY_ADDRESS_*` events. Assigning a facility to a patient fires `PATIENT_FACILITY_ADDRESS_CREATED` only, not `PATIENT_ADDRESS_CREATED`. Deleting one fires both `PATIENT_FACILITY_ADDRESS_DELETED` and `PATIENT_ADDRESS_DELETED`. Listen for the `PATIENT_FACILITY_ADDRESS_*` events for every facility address change.
####  Patient Metadata 
PATIENT_METADATA_CREATED  
---  
Occurs when a patient's metadata is created.  
Target object| Context object  
    "id": patientmetadata_id
    "type": [PatientMetadata](/sdk/data-patient/#patientmetadata)
| 
    "patient":
        "id": pt_id  
PATIENT_METADATA_UPDATED  
---  
Occurs when a patient's metadata is updated.  
Target object| Context object  
    "id": patientmetadata_id
    "type": [PatientMetadata](/sdk/data-patient/#patientmetadata)
| 
    "patient":
        "id": pt_id  
####  Allergy Intolerances 
ALLERGY_INTOLERANCE_CREATED  
---  
Occurs when an allergy is created for a patient. Additional details for the allergy may become available with subsequent ALLERGY_INTOLERANCE_UPDATED events.  
Target object| Context object  
    "id": allergy_id
    "type": [AllergyIntolerance](/sdk/data-allergy-intolerance/#allergyintolerance)
| 
    "patient":
        "id": pt_id  
ALLERGY_INTOLERANCE_UPDATED  
---  
Occurs when an allergy is updated for a patient.  
Target object| Context object  
    "id": allergy_id
    "type": [AllergyIntolerance](/sdk/data-allergy-intolerance/#allergyintolerance)
| 
    "patient":
        "id": pt_id  
####  Appointments 
To keep an external system in sync with appointment changes made in the Canvas UI (for example, an onboarding flow that tracks whether a patient has scheduled their intake), listen for the appointment lifecycle events and post a webhook to your system. The [appointment-sync-webhook](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/appointment-sync-webhook) reference plugin demonstrates this: it responds to `APPOINTMENT_CREATED`, `APPOINTMENT_CANCELED`, and `APPOINTMENT_NO_SHOWED`, fetches the full appointment details, builds a payload with appointment and patient information, and sends an HTTP POST to a webhook URL configured as a plugin [secret](/sdk/secrets/).
APPOINTMENT_CREATED  
---  
Occurs when an appointment is first created/booked.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "patient":
        "id": pt_id  
APPOINTMENT_UPDATED  
---  
Occurs when details of an appointment are updated.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "patient":
        "id": pt_id  
APPOINTMENT_CHECKED_IN  
---  
Occurs when a patient has arrived and been checked in for their appointment.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "patient":
        "id": pt_id  
APPOINTMENT_RESTORED  
---  
Occurs when a cancelled appointment is restored to a non-cancelled status.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "patient":
        "id": pt_id  
APPOINTMENT_CANCELED  
---  
Occurs when an appointment is cancelled.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "patient":
        "id": pt_id  
APPOINTMENT_NO_SHOWED  
---  
Occurs when an appointment is marked as a no-show.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "patient":
        "id": pt_id  
APPOINTMENT_RESCHEDULED  
---  
Occurs when an appointment is rescheduled by cancelling it and creating a replacement, which is what the provider UI, the patient portal, and the Appointment effect's `reschedule()` all do. The target is the new appointment, and `APPOINTMENT_CREATED` fires for it as well. Moving an appointment by updating it in place instead, through the Appointment effect's `update()` or the FHIR API, fires only `APPOINTMENT_UPDATED`. See [Detecting rescheduled appointments](/sdk/data-appointment/#detecting-rescheduled-appointments).  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "patient":
        "id": pt_id  
APPOINTMENT_LABEL_ADDED  
---  
Occurs when one or more labels are added to an appointment.  
Target object| Context object  
    "id": appointment_id
    "type": None
| 
    "patient":
        "id": pt_id
    "label": label_name  
APPOINTMENT_LABEL_REMOVED  
---  
Occurs when one or more labels are removed from an appointment.  
Target object| Context object  
    "id": appointment_id
    "type": None
| 
    "patient":
        "id": pt_id
    "label": label_name  
APPOINTMENT__SLOTS__POST_SEARCH  
---  
Occurs when requesting slot availability when scheduling an appointment.  
Target object| Context object  
| 
    "slots_by_provider": list[dict]
    "selected_values": dict  
APPOINTMENT__FORM__PROVIDERS__PRE_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__PROVIDERS__POST_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "providers": list[dict]
    "selected_values": dict
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__LOCATIONS__PRE_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__LOCATIONS__POST_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "locations": list[dict]
    "selected_values": dict
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__VISIT_TYPES__PRE_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__VISIT_TYPES__POST_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "visit_types": list[dict]
    "selected_values": dict
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__DURATIONS__PRE_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__DURATIONS__POST_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "durations": list[dict]
    "selected_values": dict
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__REASON_FOR_VISIT__PRE_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__REASON_FOR_VISIT__POST_SEARCH  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "reason_for_visit": list[dict]
    "selected_values": dict
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__GET_ADDITIONAL_FIELDS  
---  
Occurs when a schedule appointment form is loaded.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
APPOINTMENT__FORM__UPDATED  
---  
Occurs when a schedule appointment form is updated.  
Target object| Context object  
    "id": appointment_id
    "type": [Appointment](/sdk/data-appointment/#appointment)
| 
    "patient_id": int
    "selected_values": dict
    "category": [NoteTypeCategories](/sdk/data-note/#notetypecategories)  
####  Command Metadata 
COMMAND_METADATA_CREATED  
---  
Occurs when metadata is created on a command.  
Target object| Context object  
    "id": commandmetadata_id
    "type": [CommandMetadata](/sdk/data-command/#commandmetadata)
| 
    empty  
COMMAND_METADATA_UPDATED  
---  
Occurs when metadata on a command is updated.  
Target object| Context object  
    "id": commandmetadata_id
    "type": [CommandMetadata](/sdk/data-command/#commandmetadata)
| 
    empty  
####  Appointment Metadata 
APPOINTMENT_METADATA_CREATED  
---  
Occurs when an appointment's metadata is created.  
Target object| Context object  
    "id": appointmentmetadata_id
    "type": [AppointmentMetadata](/sdk/data-appointment/#appointmentmetadata)
| 
    "appointment":
        "id": appointment_id
    "patient":  # present only when the appointment has a patient
        "id": pt_id  
APPOINTMENT_METADATA_UPDATED  
---  
Occurs when an appointment's metadata is updated.  
Target object| Context object  
    "id": appointmentmetadata_id
    "type": [AppointmentMetadata](/sdk/data-appointment/#appointmentmetadata)
| 
    "appointment":
        "id": appointment_id
    "patient":  # present only when the appointment has a patient
        "id": pt_id  
####  Claims 
CLAIM_CREATED  
---  
Occurs when a claim is created.  
Target object| Context object  
    "id": claim_id
    "type": [Claim](/sdk/data-claim/#claim)
| 
    "patient":
      "id": pt_id
    "note":
      "id": note_id  
CLAIM_UPDATED  
---  
Occurs when a claim is updated.  
Target object| Context object  
    "id": claim_id
    "type": [Claim](/sdk/data-claim/#claim)
| 
    "patient":
      "id": pt_id
    "note":
      "id": note_id  
CLAIM_QUEUE_MOVED  
---  
Occurs when a claim moves from one queue to another.  
Target object| Context object  
    "id": claim_id
    "type": [Claim](/sdk/data-claim/#claim)
| 
    "patient":
      "id": pt_id
    "note":
      "id": note_id
    "queue_entered":
      "id": queue_id
    "queue_exited":
      "id": queue_id  
CLAIM__CONDITIONS  
---  
Fires when the conditions list is loaded inside the claim summary view. Plugins can use this event to surface plugin-specific diagnosis information alongside the existing diagnosis codes on the claim.  
Target object| Context object  
    "id": claim_id
    "type": [Claim](/sdk/data-claim/#claim)
| 
    [
      "id": str,
      "codings": [
        "code": str,
        "system": str,
        "display": str
      ]
    ]  
CLAIM_SUPERVISING_PROVIDER_CHANGED  
---  
Occurs when a claim's supervising provider snapshot is created or updated. The context includes the previous value(s) of any changed fields.  
Target object| Context object  
    "id": claim_id
    "type": [Claim](/sdk/data-claim/#claim)
| 
    "previous": null | {
      "first_name": str,
      "last_name": str,
      ...
    }  
CLAIM_INCIDENT_TO_CHANGED  
---  
Occurs when a claim's `incident_to` billing flag is changed. The context includes the previous boolean value.  
Target object| Context object  
    "id": claim_id
    "type": [Claim](/sdk/data-claim/#claim)
| 
    "previous": bool  
CLAIM_BALANCE_CHANGED  
---  
Occurs when a claim's patient balance or aggregate coverage balance changes. Use it to follow payments as they post and to see when the amount the patient or their insurance owes changes. A balance can change from:
  - Payments collected in Canvas, from the claim, from the patient's billing, or by the patient in the patient portal
  - Insurance payments and adjustments from remittances (ERAs) and manual remits
  - Payments recorded through the FHIR [PaymentNotice](/api/paymentnotice/) API, including copays
  - Payments posted by plugins, with [`ClaimEffect.post_payment`](/sdk/effect-claims/#post-payment) or a [stored card charge](/sdk/effect-charge-stored-card/)
  - Adjustments, write-offs, and transfers of a balance between payers or to the patient
  - Changes to the claim's charges or coverages
The event fires once per claim after the transaction commits, so the context holds the final balances. If a claim's balances end the transaction where they started, the event doesn't fire. `previous` holds the balances from before the transaction's first change, so `previous` and `current` show the net change. Balances are strings with two decimal places, such as `"150.00"` or `"-12.50"`. To react to balance changes, use this event instead of `CLAIM_UPDATED`, which fires on every claim save and doesn't include balances.  
Target object| Context object  
    "id": [claim_id](/sdk/data-claim/#claim)
    "type": [Claim](/sdk/data-claim/#claim)
| 
    "patient":  # present only when the claim's note has a patient
      "id": [pt_id](/sdk/data-patient/#patient)
    "note":  # present only when the claim has a note
      "id": [note_id](/sdk/data-note/#note)
    "previous":
      "patient_balance": str
      "aggregate_coverage_balance": str
    "current":
      "patient_balance": str
      "aggregate_coverage_balance": str  
####  Billing Line Items 
BILLING_LINE_ITEM_CREATED  
---  
Occurs when a billing line item is created from adding a CPT code to a note.  
Target object| Context object  
    "id": billing_line_item_id
    "type": [BillingLineItem](/sdk/data-billing-line-item/#billinglineitem)
| 
    "patient":
        "id": pt_id  
BILLING_LINE_ITEM_UPDATED  
---  
Occurs when a billing line item is modified.  
Target object| Context object  
    "id": billing_line_item_id
    "type": [BillingLineItem](/sdk/data-billing-line-item/#billinglineitem)
| 
    "patient":
        "id": pt_id  
####  Calendars 
CALENDAR_CREATED  
---  
Occurs when a calendar is created.  
Target object| Context object  
    "id": calendar_id
    "type": [Calendar](/sdk/data-calendar/#calendar)
| 
    empty  
CALENDAR_UPDATED  
---  
Occurs when a calendar is updated.  
Target object| Context object  
    "id": calendar_id
    "type": [Calendar](/sdk/data-calendar/#calendar)
| 
    empty  
CALENDAR_DELETED  
---  
Occurs when a calendar is deleted.  
Target object| Context object  
    "id": calendar_id
    "type": [Calendar](/sdk/data-calendar/#calendar)
| 
    empty  
####  Calendar Events 
CALENDAR_EVENT_CREATED  
---  
Occurs when a calendar event is created.  
Target object| Context object  
    "id": event_id
    "type": [Event](/sdk/data-calendar/#event)
| 
    empty  
CALENDAR_EVENT_UPDATED  
---  
Occurs when a calendar event is updated.  
Target object| Context object  
    "id": event_id
    "type": [Event](/sdk/data-calendar/#event)
| 
    empty  
CALENDAR_EVENT_DELETED  
---  
Occurs when a calendar event is deleted.  
Target object| Context object  
    "id": event_id
    "type": [Event](/sdk/data-calendar/#event)
| 
    empty  
####  Patient Payments 
PATIENT_PAYMENT_PROCESSED  
---  
Occurs when a patient payment is processed in Canvas.  
Target object| Context object  
    "id": pt_id
    "type": [Patient](/sdk/data-patient/)
| 
    "patient_id": str
    "total_amount_cents": str
    "timestamp": str
    "payment_method_and_description": str
    "claim_payments": [
        {
            "claim_id": str,
            "allocated_cents": str
        }
    ]  
####  Clinical Documents 
These events fire during the lifecycle of documents in the [Data Integration](https://canvas-medical.help.usepylon.com/articles/4617508394-data-integration) module — including inbound faxes, uploaded documents, and electronic transmissions. Each event's context includes document metadata from the underlying [IntegrationTask](/sdk/data-integration-task/).
Use `DOCUMENT_RECEIVED` to automate inbound-document intake, such as inbound faxes. It fires when a new `IntegrationTask` is created, from any channel (fax, document upload, lab, and so on).
  - **Getting the file:** the event context carries the file URL as `document["content_url"]`. The `IntegrationTask` data class doesn't include the file, so this event is where you get it. Fetch it with `requests.get(document["content_url"])`, and check `document["channel"]` first if you only want one channel.
  - **Following one document:** every event in this family uses the `IntegrationTask` UUID as its `target` and `document["id"]`, so you can match one document across `DOCUMENT_RECEIVED`, `DOCUMENT_LINKED_TO_PATIENT`, `DOCUMENT_CATEGORIZED`, `DOCUMENT_REVIEWER_ASSIGNED`, `DOCUMENT_REVIEWED`, and `DOCUMENT_DELETED`.
  - **After it's filed to a chart:** use the [DocumentReference](/sdk/data-document-reference/) data class, which has a presigned `document_url`.
DOCUMENT_RECEIVED  
---  
Occurs when a new clinical document is received via fax, upload, or electronic transmission.  
Target object| Context object  
    "id": document_id
    "type": [IntegrationTask](/sdk/data-integration-task/)
| 
    "document":
      "id": document_id
      "channel": str
      "status": str
      "title": str
      "type": str
      "content_url": str
      "content_type": str
      "created_at": datetime str
    "patient":
      "id": pt_id
    "available_document_types":
        "key": str
        "name": str
        "report_type": str
        "template_type": str
        "template_fields":
            "name": str
            "label": str
            "type": str
            "required": bool  
DOCUMENT_LINKED_TO_PATIENT  
---  
Occurs when a clinical document is linked to a patient.  
Target object| Context object  
    "id": document_id
    "type": [IntegrationTask](/sdk/data-integration-task/)
| 
    "document":
      "id": document_id
      "channel": str
      "status": str
      "title": str
      "type": str
      "content_url": str
      "content_type": str
      "created_at": datetime str
    "patient":
      "id": pt_id
    "previous_patient":
      "id": pt_id
    "linked_at": datetime str
    "available_document_types":
        "key": str
        "name": str
        "report_type": str
        "template_type": str
        "template_fields":
            "name": str
            "label": str
            "type": str
            "required": bool  
DOCUMENT_CATEGORIZED  
---  
Occurs when a clinical document is categorized.  
Target object| Context object  
    "id": document_id
    "type": [IntegrationTask](/sdk/data-integration-task/)
| 
    "document":
      "id": document_id
      "channel": str
      "status": str
      "title": str
      "type": str
      "content_url": str
      "content_type": str
      "created_at": datetime str
    "document_type":
      "key": str
      "name": str
      "report_type": str
      "template_type": str
    "previous_document_type":
      "key": str
      "name": str
      "report_type": str
      "template_type": str
    "categorized_at": datetime str
    "patient":
      "id": pt_id  
DOCUMENT_REVIEWER_ASSIGNED  
---  
Occurs when a reviewer (Staff or Team) is assigned or reassigned on the Data Integration document review panel. This does not fire when a reviewer is assigned on a LabReport or ImagingReport — only when the [IntegrationTaskReview](/sdk/data-integration-task/) reviewer changes.  
Target object| Context object  
    "id": document_id
    "type": [IntegrationTask](/sdk/data-integration-task/)
| 
    "document":
      "id": document_id
      "channel": str
      "status": str
      "title": str
      "type": str
      "content_url": str
      "content_type": str
      "created_at": datetime str
    "assigned_at": datetime str
    "reviewer":
      "type": str
      "id": reviewer_id
      "name": str
    "previous_reviewer":
      "type": str
      "id": reviewer_id
      "name": str
    "patient":
      "id": pt_id  
DOCUMENT_REVIEWED  
---  
Occurs when a clinical document is marked as reviewed. This fires when the Data Integration task status changes to reviewed, or when a Lab Results Review, Imaging Report Review, Consult Report Review, or Uncategorized Document Review command is committed.  
Target object| Context object  
    "id": document_id
    "type": [IntegrationTask](/sdk/data-integration-task/)
| 
    "document":
      "id": document_id
      "channel": str
      "status": str
      "title": str
      "type": str
      "content_url": str
      "content_type": str
      "created_at": datetime str
    "review":
      "reviewer":
        "type": str
        "id": reviewer_id
        "name": str
      "status": str
      "patient_communication_method": str
      "internal_comment": str
      "message_to_patient": str
    "reviewed_at": datetime str
    "document_type":
      "key": str
      "name": str
      "report_type": str
      "template_type": str
    "patient":
      "id": pt_id  
DOCUMENT_DELETED  
---  
Occurs when a document is junked/deleted from the Data Integration panel. This does not fire when a report is junked from the patient chart.  
Target object| Context object  
    "id": document_id
    "type": [IntegrationTask](/sdk/data-integration-task/)
| 
    "document":
      "id": document_id
      "channel": str
      "status": str
      "title": str
      "type": str
      "content_url": str
      "content_type": str
      "created_at": datetime str
    "deleted_at": datetime str
    "patient":
      "id": pt_id
    "document_type":
      "key": str
      "name": str
      "report_type": str
      "template_type": str
    "deleted_by":
      "id": user_id
      "name": str  
DOCUMENT_FIELDS_UPDATED  
---  
Occurs when a clinical document's fields are updated. This fires when a Lab Report, Imaging Report, or Specialist Consult Report is parsed and its values are saved. The `updated_fields` list contains each changed field with its new and previous values.  
Target object| Context object  
    "id": document_id
    "type": [IntegrationTask](/sdk/data-integration-task/)
| 
    "document":
      "id": document_id
      "channel": str
      "status": str
      "title": str
      "type": str
      "content_url": str
      "content_type": str
      "created_at": datetime str
    "patient":
      "id": pt_id
    "updated_fields":
        "name": str
        "value": str | int | float | bool
        "previous_value": str | int | float | bool | None
    "document_type":
      "key": str
      "name": str
      "report_type": str
      "template_type": str
    "updated_at": datetime str  
####  Document Review Delegation 
The `DOCUMENT_DELEGATED` event fires when an uncategorized clinical document's review is delegated to another staff member or team, or routed back to its owner. It is a review-workflow event, separate from the Data Integration document-lifecycle events above.
DOCUMENT_DELEGATED  
---  
Occurs when an uncategorized clinical document review is delegated to another staff member or team from the document review surface, or routed back to its owner. This is distinct from DOCUMENT_REVIEWER_ASSIGNED, which fires only for Data Integration reviewer changes. `signature_consent` indicates whether the recipient may apply the owner's signature; `routed_back` is true when the document was returned to its owner; `comment` carries the delegator's instructions.  
Target object| Context object  
    "id": document_id
    "type": [IntegrationTask](/sdk/data-integration-task/)
| 
    "document": [UncategorizedClinicalDocument](/sdk/data-uncategorized-clinical-document/)
      "id": document_id
      "channel": str
      "status": str
      "title": str
      "type": str
      "content_url": str
      "content_type": str
      "created_at": datetime str
    "delegated_at": datetime str
    "delegated_by": [Staff](/sdk/data-staff/#staff)
      "type": str ("STAFF")
      "id": staff_id
      "name": str
    "delegated_to": [Staff](/sdk/data-staff/#staff) or [Team](/sdk/data-team/#team)
      "type": str ("STAFF" or "TEAM")
      "id": staff_or_team_id
      "name": str
    "on_behalf_of": [Staff](/sdk/data-staff/#staff)
      "type": str ("STAFF")
      "id": staff_id
      "name": str
    "signature_consent": bool
    "routed_back": bool
    "comment": str
    "patient": [Patient](/sdk/data-patient/#patient)
      "id": pt_id  
####  Conditions 
CONDITION_ASSESSED  
---  
Occurs when a condition is assessed through the Assess Condition command.  
Target object| Context object  
    "id": condition_id
    "type": [Condition](/sdk/data-condition/#condition)
| 
    "patient":
        "id": pt_id  
CONDITION_CREATED  
---  
Occurs when a condition is diagnosed for a patient. Additional details for the condition may become available with subsequent CONDITION_UPDATED events.  
Target object| Context object  
    "id": condition_id
    "type": [Condition](/sdk/data-condition/#condition)
| 
    "patient":
        "id": pt_id  
CONDITION_RESOLVED  
---  
Occurs when a condition is resolved through the Resolve Condition command.  
Target object| Context object  
    "id": condition_id
    "type": [Condition](/sdk/data-condition/#condition)
| 
    "patient":
        "id": pt_id  
CONDITION_UPDATED  
---  
Occurs when a condition is updated for a patient, including when committing an [Assess](/sdk/commands/#assess) command moves it onto or off the problem list.  
Target object| Context object  
    "id": condition_id
    "type": [Condition](/sdk/data-condition/#condition)
| 
    "patient":
        "id": pt_id  
####  Consents 
CONSENT_CREATED  
---  
Occurs when a patient consent is created.  
Target object| Context object  
    "id": consent_id
    "type": None
| 
    "patient":
       "id": pt_id  
CONSENT_DELETED  
---  
Occurs when a patient consent is removed/deleted.  
Target object| Context object  
    "id": consent_id
    "type": None
| 
    "patient":
       "id": pt_id  
CONSENT_UPDATED  
---  
Occurs when a patient consent is updated.  
Target object| Context object  
    "id": consent_id
    "type": None
| 
    "patient":
       "id": pt_id  
####  Coverages 
COVERAGE_CREATED  
---  
Occurs when a coverage for a patient is created.  
Target object| Context object  
    "id": coverage_id
    "type": [Coverage](/sdk/data-coverage/#coverage)
| 
    "patient":
       "id": pt_id  
COVERAGE_UPDATED  
---  
Occurs when a coverage for a patient is updated.  
Target object| Context object  
    "id": coverage_id
    "type": [Coverage](/sdk/data-coverage/#coverage)
| 
    "patient":
       "id": pt_id  
####  Eligibility responses 
A `COVERAGE_ELIGIBILITY_RESPONSE_CREATED` or `COVERAGE_ELIGIBILITY_RESPONSE_UPDATED` event fires on every eligibility response save. When the response resolves to a definite status, a matching `COVERAGE_ELIGIBILITY_RESPONSE_ACTIVE`, `COVERAGE_ELIGIBILITY_RESPONSE_INACTIVE`, or `COVERAGE_ELIGIBILITY_RESPONSE_FAILED` event fires alongside it. For example, when a failed eligibility check is first recorded, both `COVERAGE_ELIGIBILITY_RESPONSE_CREATED` and `COVERAGE_ELIGIBILITY_RESPONSE_FAILED` fire. Each event's context carries the derived `status` string and the associated `coverage`; `_FAILED` events also include the payer `errors`.
COVERAGE_ELIGIBILITY_RESPONSE_CREATED  
---  
Occurs when an eligibility response is created for a coverage.  
Target object| Context object  
    "id": eligibility_response_id
    "type": [EligibilityResponse](/sdk/data-eligibility-response/#eligibilityresponse)
| 
    "coverage":
      "id": coverage_id
    "patient":
      "id": pt_id
    "status": str  
COVERAGE_ELIGIBILITY_RESPONSE_UPDATED  
---  
Occurs when an eligibility response is updated.  
Target object| Context object  
    "id": eligibility_response_id
    "type": [EligibilityResponse](/sdk/data-eligibility-response/#eligibilityresponse)
| 
    "coverage":
      "id": coverage_id
    "patient":
      "id": pt_id
    "status": str  
COVERAGE_ELIGIBILITY_RESPONSE_ACTIVE  
---  
Occurs when an eligibility response resolves to an active status.  
Target object| Context object  
    "id": eligibility_response_id
    "type": [EligibilityResponse](/sdk/data-eligibility-response/#eligibilityresponse)
| 
    "coverage":
      "id": coverage_id
    "patient":
      "id": pt_id
    "status": str  
COVERAGE_ELIGIBILITY_RESPONSE_INACTIVE  
---  
Occurs when an eligibility response resolves to an inactive status.  
Target object| Context object  
    "id": eligibility_response_id
    "type": [EligibilityResponse](/sdk/data-eligibility-response/#eligibilityresponse)
| 
    "coverage":
      "id": coverage_id
    "patient":
      "id": pt_id
    "status": str  
COVERAGE_ELIGIBILITY_RESPONSE_FAILED  
---  
Occurs when an eligibility response check fails to complete (the payer response errored).  
Target object| Context object  
    "id": eligibility_response_id
    "type": [EligibilityResponse](/sdk/data-eligibility-response/#eligibilityresponse)
| 
    "coverage":
      "id": coverage_id
    "patient":
      "id": pt_id
    "status": str
    "errors": list[str]  
####  Detected Issues 
DETECTED_ISSUE_CREATED  
---  
Occurs when a detected issue is created.  
Target object| Context object  
    "id": detected_issue_id
    "type": [DetectedIssue](/sdk/data-detected-issue/#detectedissue)
| 
    "patient":
       "id": pt_id  
DETECTED_ISSUE_UPDATED  
---  
Occurs when a detected issue is updated.  
Target object| Context object  
    "id": detected_issue_id
    "type": [DetectedIssue](/sdk/data-detected-issue/#detectedissue)
| 
    "patient":
       "id": pt_id  
DETECTED_ISSUE_EVIDENCE_CREATED  
---  
Occurs when detected issue evidence is created.  
Target object| Context object  
    "id": detected_issue_evidence_id
    "type": [DetectedIssueEvidence](/sdk/data-detected-issue/#detectedissueevidence)
| 
    empty  
DETECTED_ISSUE_EVIDENCE_UPDATED  
---  
Occurs when a detected issue evidence is updated.  
Target object| Context object  
    "id": detected_issue_evidence_id
    "type": [DetectedIssueEvidence](/sdk/data-detected-issue/#detectedissueevidence)
| 
    empty  
####  Devices 
DEVICE_CREATED  
---  
Occurs when a device is created.  
Target object| Context object  
    "id": device_id
    "type": [Device](/sdk/data-device/#device)
| 
    "patient":
       "id": pt_id  
DEVICE_UPDATED  
---  
Occurs when a device is updated.  
Target object| Context object  
    "id": device_id
    "type": [Device](/sdk/data-device/#device)
| 
    "patient":
       "id": pt_id  
####  Document References 
DOCUMENT_REFERENCE_CREATED  
---  
Occurs when a document reference is created.  
Target object| Context object  
    "id": document_reference_id
    "type": None
| 
    "patient":
       "id": pt_id  
DOCUMENT_REFERENCE_UPDATED  
---  
Occurs when a document reference is updated.  
Target object| Context object  
    "id": document_reference_id
    "type": None
| 
    "patient":
       "id": pt_id  
DOCUMENT_REFERENCE_DELETED  
---  
Occurs when a document reference is deleted.  
Target object| Context object  
    "id": document_reference_id
    "type": None
| 
    "patient":
       "id": pt_id  
####  Encounters 
ENCOUNTER_CREATED  
---  
Occurs when an encounter is created.  
Target object| Context object  
    "id": encounter_id
    "type": [Encounter](/sdk/data-encounter/#encounter)
| 
    empty  
ENCOUNTER_UPDATED  
---  
Occurs when an encounter is updated.  
Target object| Context object  
    "id": encounter_id
    "type": [Encounter](/sdk/data-encounter/#encounter)
| 
    empty  
####  Imaging Reports 
IMAGING_REPORT_CREATED  
---  
Occurs when an imaging report is entered into the data integration section of canvas.  
Target object| Context object  
    "id": report_id
    "type": [ImagingReport](/sdk/data-imaging/#imagingreport)
| 
    "patient":
       "id": pt_id  
IMAGING_REPORT_UPDATED  
---  
Occurs when an imaging report is updated.  
Target object| Context object  
    "id": report_id
    "type": [ImagingReport](/sdk/data-imaging/#imagingreport)
| 
    "patient":
       "id": pt_id  
####  Immunizations 
IMMUNIZATION_CREATED  
---  
Occurs when an immunization is created. Additional details for the immunization may become available with subsequent IMMUNIZATION_STATEMENT_UPDATED events.  
Target object| Context object  
    "id": immunization_id
    "type": [Immunization](/sdk/data-immunization/#immunization)
| 
    "patient":
       "id": pt_id  
IMMUNIZATION_UPDATED  
---  
Occurs when an immunization is updated.  
Target object| Context object  
    "id": immunization_id
    "type": [Immunization](/sdk/data-immunization/#immunization)
| 
    "patient":
       "id": pt_id  
IMMUNIZATION_STATEMENT_CREATED  
---  
Occurs when an immunization statement is created. Additional details for the immunization statement may become available with subsequent IMMUNIZATION_STATEMENT_UPDATED events.  
Target object| Context object  
    "id": immunization_id
    "type": [Immunization](/sdk/data-immunization/#immunization)
| 
    "patient":
       "id": pt_id  
IMMUNIZATION_STATEMENT_UPDATED  
---  
Occurs when an immunization statement is updated.  
Target object| Context object  
    "id": immunization_id
    "type": [Immunization](/sdk/data-immunization/#immunization)
| 
    "patient":
       "id": pt_id  
####  Instructions 
INSTRUCTION_CREATED  
---  
Occurs when an instruction is created using the Instruct command. Additional details for the instruction may become available with subsequent INSTRUCTION_UPDATED events.  
Target object| Context object  
    "id": instruction_id
    "type": None
| 
    "patient":
       "id": pt_id  
INSTRUCTION_UPDATED  
---  
Occurs when an instruction is updated.  
Target object| Context object  
    "id": instruction_id
    "type": None
| 
    "patient":
       "id": pt_id  
####  Interviews 
INTERVIEW_CREATED  
---  
Occurs when an interview is created using the Questionnaire command or through the Questionnaire endpoint in the FHIR API. Additional details for the interview may become available with subsequent INTERVIEW_UPDATED events.  
Target object| Context object  
    "id": interview_id
    "type": [Interview](/sdk/data-questionnaire/#interview)
| 
    "patient":
       "id": pt_id  
INTERVIEW_UPDATED  
---  
Occurs when an interview is updated.  
Target object| Context object  
    "id": interview_id
    "type": [Interview](/sdk/data-questionnaire/#interview)
| 
    "patient":
       "id": pt_id  
####  Labs 
To be notified when lab results (documents and individual records) are added to Canvas, use the lab order and report events in this section. Pair them with the [LabReport](/sdk/data-labs/) data module to read the result details.
LAB_ORDER_CREATED  
---  
Occurs when a lab order is created via the Lab Order command. Additional details for the lab order may become available with subsequent LAB_ORDER_UPDATED events.  
Target object| Context object  
    "id": laborder_id
    "type": [LabOrder](/sdk/data-labs/#laborder)
| 
    "patient":
       "id": pt_id  
LAB_ORDER_UPDATED  
---  
Occurs when a lab order is updated.  
Target object| Context object  
    "id": laborder_id
    "type": [LabOrder](/sdk/data-labs/#laborder)
| 
    "patient":
       "id": pt_id  
LAB_REPORT_CREATED  
---  
Occurs when a lab report is created either through Data Integration, electronic ingestion or the FHIR API.  
Target object| Context object  
    "id": labreport_id
    "type": [LabReport](/sdk/data-labs/#labreport)
| 
    "patient":
       "id": pt_id  
LAB_REPORT_UPDATED  
---  
Occurs when a lab report is updated.  
Target object| Context object  
    "id": labreport_id
    "type": [LabReport](/sdk/data-labs/#labreport)
| 
    "patient":
       "id": pt_id  
####  Medications 
MEDICATION_LIST_ITEM_CREATED  
---  
Occurs when a medication is added for a patient.  
Target object| Context object  
    "id": medication_id
    "type": [Medication](/sdk/data-medication/#medication)
| 
    "patient":
       "id": pt_id  
MEDICATION_LIST_ITEM_UPDATED  
---  
Occurs when a medication is updated for a patient.  
Target object| Context object  
    "id": medication_id
    "type": [Medication](/sdk/data-medication/#medication)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_UPDATED  
---  
Occurs when a prescription is updated.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_CREATED  
---  
Occurs when a prescription is created for a patient using the Prescribe command. Additional details for the prescription become available with subsequent PRESCRIPTION_UPDATED events.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
#####  Prescription status events 
The following events fire when a prescription's status changes during the e-prescribing lifecycle. These events always fire alongside a `PRESCRIPTION_CREATED` or `PRESCRIPTION_UPDATED` event. For example, when a prescription is first created, both `PRESCRIPTION_CREATED` and `PRESCRIPTION_OPENED` will fire. When a prescription's status is updated to "transmitted", both `PRESCRIPTION_UPDATED` and `PRESCRIPTION_TRANSMITTED` will fire.
PRESCRIPTION_OPENED  
---  
Occurs when a prescription's status is set to open. This is the default status when a prescription is first created.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_PENDING  
---  
Occurs when a prescription's status changes to pending.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_ACCEPTED  
---  
Occurs when a prescription has been ultimately accepted.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_ERRORED  
---  
Occurs when an error occurs during prescription processing.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_CANCEL_REQUESTED  
---  
Occurs when a cancellation has been requested for a prescription.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_CANCELED  
---  
Occurs when a prescription has been successfully canceled.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_CANCEL_DENIED  
---  
Occurs when a cancellation request for a prescription has been denied.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_RECEIVED  
---  
Occurs when a prescription has been received by the e-prescribing network.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_SIGNED  
---  
Occurs when a prescription has been signed.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_INQUEUE  
---  
Occurs when a prescription is in queue for transmission.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_TRANSMITTED  
---  
Occurs when a prescription has been transmitted to the pharmacy.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
PRESCRIPTION_DELIVERED  
---  
Occurs when a prescription has been delivered to the pharmacy.  
Target object| Context object  
    "id": prescription_id
    "type": [Prescription](/sdk/data-prescription)
| 
    "patient":
       "id": pt_id  
####  Surescripts 
Surescripts response events fire when the platform receives a response from Surescripts after a corresponding request effect is executed. These events let plugins react to insurance eligibility checks and other Surescripts services.
SURESCRIPTS_ELIGIBILITY_RESPONSE  
---  
Occurs when Surescripts returns an eligibility response after a `SendSurescriptsEligibilityRequestEffect` is executed. The response contains the patient's insurance plan information and coverage details. See [Handling Eligibility Responses](/sdk/effect-surescripts/#handling-eligibility-responses) for the typed response data classes and an example handler.  
Target object| Context object  
    empty
| 
    "correlation_id": str
    "patient_id": str
    "plans": list[dict]
    "error": str or None  
SURESCRIPTS_BENEFITS_RESPONSE  
---  
Occurs when Surescripts returns a benefits response after a `SendSurescriptsBenefitsRequestEffect` is executed. The response contains formulary and coverage details for the requested medication, including copays, quantity limits, and therapeutic alternatives. See [Handling Benefits Responses](/sdk/effect-surescripts/#handling-benefits-responses) for the typed response data classes and an example handler.  
Target object| Context object  
    empty
| 
    "correlation_id": str
    "patient_id": str
    "medication_ndc": str
    "coverages": list[dict]
    "error": str or None  
####  Messaging 
MESSAGE_CREATED  
---  
Occurs when a message (patient/practitioner communication) is created.  
Target object| Context object  
    "id": message_id
    "type": [Message](/sdk/data-message/#message)
| 
    "patient":
       "id": pt_id  
MESSAGE_TEAM_ASSIGNED  
---  
Occurs when a message is created with a team, and each time a message's team is assigned, changed, or cleared, including by the [`AssignMessageTeam`](/sdk/effect-messages/#assignmessageteam) effect. Deleting a team emits this event for each of its messages, with `team` set to null. A save that leaves the team unchanged does not emit it. `team` is null when the message was unassigned, and `previous_team` is null when it had no team before.  
Target object| Context object  
    "id": message_id
    "type": [Message](/sdk/data-message/#message)
| 
    "message": [Message](/sdk/data-message/#message)
      "id": message_id
      "sender": str, the id of the [Patient](/sdk/data-patient/) or [Staff](/sdk/data-staff/) who sent it
      "recipient": str, the id of the [Patient](/sdk/data-patient/) or [Staff](/sdk/data-staff/) it was sent to
      "read": datetime str | null
    "team": [Team](/sdk/data-team/) | null
      "id": team_id
      "name": str
    "previous_team": [Team](/sdk/data-team/) | null
      "id": team_id
      "name": str
    "patient": [Patient](/sdk/data-patient/)
      "id": pt_id
    "assigned_at": datetime str  
MESSAGE_TRANSMISSION_CREATED  
---  
Occurs when a message transmission record is created. Message transmissions track delivery attempts and status for messages sent through various channels (SMS, email, etc.).  
Target object| Context object  
    "id": message_transmission_id
    "type": [MessageTransmission](/sdk/data-message/#messagetransmission)
| 
    empty  
MESSAGE_TRANSMISSION_UPDATED  
---  
Occurs when a message transmission record is updated (e.g., when delivery status changes).  
Target object| Context object  
    "id": message_transmission_id
    "type": [MessageTransmission](/sdk/data-message/#messagetransmission)
| 
    empty  
####  Notes 
NOTE_STATE_CHANGE_EVENT_CREATED  
---  
Occurs as a note traverses through its state machine. This event can be used when looking at any changes to the [note state](/sdk/data-note/#notestates), including locking and unlocking.  
Target object| Context object  
    "id": nsce_id
    "type": NoteStateChangeEvent
| 
    "note_id": note_id,
    "patient_id": pt_id,
    "state": [str](/sdk/data-note/#notestates)  
NOTE_STATE_CHANGE_EVENT_PRE_CREATE  
---  
Occurs **before** a note state change event is created. This event allows protocols to perform validation and block the note state change if needed. If an [`EventValidationError`](/sdk/effect-event-validation-error) effect is returned, the note state change event is aborted and the error message is surfaced to the user.  
Target object| Context object  
    "id": nsce_id
    "type": NoteStateChangeEvent
| 
    "note_id": note_id,
    "patient_id": pt_id,
    "state": [str](/sdk/data-note/#notestates)  
NOTE_STATE_CHANGE_EVENT_UPDATED  
---  
Occurs when a note state change event is updated. After a note is locked, or signed for note types that require a signature, Canvas generates an archived PDF of the note in the background and saves it on that lock or sign event. That fires this event **twice** : once when the note's snapshot is saved and once when the PDF is saved.  
Target object| Context object  
    "id": nsce_id
    "type": NoteStateChangeEvent
| 
    "note_id": note_id,
    "patient_id": pt_id,
    "state": [str](/sdk/data-note/#notestates)  
NOTE_CREATED  
---  
Occurs when a note is created.  
Target object| Context object  
    "id": note_id
    "type": [Note](/sdk/data-note/)
| 
    "patient":
        "id": pt_id  
NOTE_UPDATED  
---  
Occurs when a note is updated, including changes to fields, commands, or body content.  
Target object| Context object  
    "id": note_id
    "type": [Note](/sdk/data-note/)
| 
    "patient":
        "id": pt_id
    "user":
        "id": staff_key  
NOTE_OPENED  
---  
Fires when a provider expands a note in the patient chart. The context includes the note's ID.  
Target object| Context object  
    "id": patient_key
    "type": Patient
| 
    "note": {"id": note_uuid},
    "user": {
      "type": str,
      "id": user_id
    }  
NOTE_CLOSED  
---  
Fires when a provider collapses a note that was previously open. The context includes the note's ID.  
Target object| Context object  
    "id": patient_key
    "type": Patient
| 
    "note": {"id": note_uuid},
    "user": {
      "type": str,
      "id": user_id
    }  
NOTE_SUPERVISING_PROVIDER_CHANGED  
---  
Occurs when a note's supervising provider is changed. The context includes the previous supervising provider's Staff ID, or `null` if the note previously had no supervising provider.  
Target object| Context object  
    "id": note_id
    "type": [Note](/sdk/data-note/)
| 
    "previous": null | {
      "id": staff_key
    }  
GET_NOTE_RESTRICTIONS  
---  
Fires every time a note is opened or its restrictions are refetched. Plugins respond with a [`NoteRestrictionsEffect`](/sdk/effect-note-restrictions/) to control whether the user can edit the note, whether the content is blurred, and what banner message is displayed. If no plugin responds, the note is unrestricted by default.  
Target object| Context object  
    "id": note.id
    "type": [Note](/sdk/data-note/)
| 
    empty  
####  Note Metadata 
NOTE_METADATA_CREATED  
---  
Occurs when a note's metadata is created.  
Target object| Context object  
    "id": notemetadata_id
    "type": [NoteMetadata](/sdk/data-note/#notemetadata)
| 
    empty  
NOTE_METADATA_UPDATED  
---  
Occurs when a note's metadata is updated.  
Target object| Context object  
    "id": notemetadata_id
    "type": [NoteMetadata](/sdk/data-note/#notemetadata)
| 
    empty  
####  Letters 
LETTER_CREATED  
---  
Occurs when a letter is created.  
Target object| Context object  
    "id": letter_id
    "type": [Letter](/sdk/data-letter/)
| 
    "patient":
       "id": pt_id  
LETTER_UPDATED  
---  
Occurs when a letter is updated.  
Target object| Context object  
    "id": letter_id
    "type": [Letter](/sdk/data-letter/)
| 
    "patient":
       "id": pt_id  
LETTER_ACTION_EVENT_CREATED  
---  
Occurs when a letter is printed or faxed. For a fax, `delivered_by_fax` on the target is still `None`.  
Target object| Context object  
    "id": letter_action_event_id
    "type": [LetterActionEvent](/sdk/data-letter-action-event/)
| 
    empty  
LETTER_ACTION_EVENT_UPDATED  
---  
Occurs when the faxing service reports whether a letter fax was delivered, and again if a later report changes the outcome or its message. See [delivery status](/sdk/data-fax/#delivery-status).  
Target object| Context object  
    "id": letter_action_event_id
    "type": [LetterActionEvent](/sdk/data-letter-action-event/)
| 
    empty  
####  Faxed Documents 
Canvas records an action event each time a note, referral, imaging order, lab order, or integration task is faxed, including faxes a plugin sends with the [Fax Note effect](/sdk/effect-notes/#fax-note). Letters have their own letter action events.
  - The `_CREATED` event fires when the fax is submitted. `delivered_by_fax` on the target is still `None`.
  - The `_UPDATED` event fires when the faxing service reports the outcome. Read `delivered_by_fax` and `fax_result_msg` on the target; see [delivery status](/sdk/data-fax/#delivery-status).
A later report that changes the outcome or its message fires `_UPDATED` again, so a plugin that retries failed faxes should retry each action event only once.
NOTE_ACTION_EVENT_CREATED  
---  
Occurs when a note is faxed.  
Target object| Context object  
    "id": note_action_event_id
    "type": [NoteActionEvent](/sdk/data-fax/#noteactionevent)
| 
    empty  
NOTE_ACTION_EVENT_UPDATED  
---  
Occurs when the faxing service reports whether a note fax was delivered.  
Target object| Context object  
    "id": note_action_event_id
    "type": [NoteActionEvent](/sdk/data-fax/#noteactionevent)
| 
    empty  
REFERRAL_ACTION_EVENT_CREATED  
---  
Occurs when a referral is faxed.  
Target object| Context object  
    "id": referral_action_event_id
    "type": [ReferralActionEvent](/sdk/data-fax/#referralactionevent)
| 
    empty  
REFERRAL_ACTION_EVENT_UPDATED  
---  
Occurs when the faxing service reports whether a referral fax was delivered.  
Target object| Context object  
    "id": referral_action_event_id
    "type": [ReferralActionEvent](/sdk/data-fax/#referralactionevent)
| 
    empty  
IMAGING_ORDER_ACTION_EVENT_CREATED  
---  
Occurs when an imaging order is faxed.  
Target object| Context object  
    "id": imaging_order_action_event_id
    "type": [ImagingOrderActionEvent](/sdk/data-fax/#imagingorderactionevent)
| 
    empty  
IMAGING_ORDER_ACTION_EVENT_UPDATED  
---  
Occurs when the faxing service reports whether an imaging order fax was delivered.  
Target object| Context object  
    "id": imaging_order_action_event_id
    "type": [ImagingOrderActionEvent](/sdk/data-fax/#imagingorderactionevent)
| 
    empty  
LAB_ORDER_ACTION_EVENT_CREATED  
---  
Occurs when a lab order is faxed.  
Target object| Context object  
    "id": lab_order_action_event_id
    "type": [LabOrderActionEvent](/sdk/data-fax/#laborderactionevent)
| 
    empty  
LAB_ORDER_ACTION_EVENT_UPDATED  
---  
Occurs when the faxing service reports whether a lab order fax was delivered.  
Target object| Context object  
    "id": lab_order_action_event_id
    "type": [LabOrderActionEvent](/sdk/data-fax/#laborderactionevent)
| 
    empty  
INTEGRATION_TASK_ACTION_EVENT_CREATED  
---  
Occurs when an integration task is faxed.  
Target object| Context object  
    "id": integration_task_action_event_id
    "type": [IntegrationTaskActionEvent](/sdk/data-fax/#integrationtaskactionevent)
| 
    empty  
INTEGRATION_TASK_ACTION_EVENT_UPDATED  
---  
Occurs when the faxing service reports whether an integration task fax was delivered.  
Target object| Context object  
    "id": integration_task_action_event_id
    "type": [IntegrationTaskActionEvent](/sdk/data-fax/#integrationtaskactionevent)
| 
    empty  
####  Observations 
OBSERVATION_CREATED  
---  
Occurs when an observation is created.  
Target object| Context object  
    "id": observation_id
    "type": [Observation](/sdk/data-observation/#observation)
| 
    "patient":
       "id": pt_id  
OBSERVATION_UPDATED  
---  
Occurs when an observation is updated.  
Target object| Context object  
    "id": observation_id
    "type": [Observation](/sdk/data-observation/#observation)
| 
    "patient":
       "id": pt_id  
####  Protocol Overrides 
PROTOCOL_OVERRIDE_CREATED  
---  
Target object| Context object  
    "id": protocoloverride_id
    "type": [ProtocolOverride](/sdk/data-protocol-override/#protocoloverride)
| 
    "patient":
       "id": pt_id  
PROTOCOL_OVERRIDE_UPDATED  
---  
Target object| Context object  
    "id": protocoloverride_id
    "type": [ProtocolOverride](/sdk/data-protocol-override/#protocoloverride)
| 
    "patient":
       "id": pt_id  
PROTOCOL_OVERRIDE_DELETED  
---  
Target object| Context object  
    "id": protocoloverride_id
    "type": [ProtocolOverride](/sdk/data-protocol-override/#protocoloverride)
| 
    "patient":
       "id": pt_id  
####  Referral Reports 
REFERRAL_REPORT_CREATED  
---  
Occurs when a specialist consult report is created in Data Integration.  
Target object| Context object  
    "id": referralreport_id
    "type": [ReferralReport](/sdk/data-referral/#referralreport)
| 
    "patient":
       "id": pt_id  
REFERRAL_REPORT_UPDATED  
---  
Occurs when a specialist consult report is updated.  
Target object| Context object  
    "id": referralreport_id
    "type": [ReferralReport](/sdk/data-referral/#referralreport)
| 
    "patient":
       "id": pt_id  
####  Tasks 
TASK_CREATED  
---  
Occurs when a task is created.  
Target object| Context object  
    "id": task_id
    "type": [Task](/sdk/data-task/#task)
| 
    "patient":
       "id": pt_id  
TASK_UPDATED  
---  
Occurs when a task is updated.  
Target object| Context object  
    "id": task_id
    "type": [Task](/sdk/data-task/#task)
| 
    "patient":
       "id": pt_id  
TASK_COMMENT_CREATED  
---  
Occurs when a comment is added to a task.  
Target object| Context object  
    "id": taskcomment_id
    "type": [TaskComment](/sdk/data-task/#taskcomment)
| 
    empty  
TASK_COMMENT_UPDATED  
---  
Occurs when a comment for a task is updated.  
Target object| Context object  
    "id": taskcomment_id
    "type": [TaskComment](/sdk/data-task/#taskcomment)
| 
    empty  
TASK_COMMENT_DELETED  
---  
Occurs when a comment for a task is removed.  
Target object| Context object  
    "id": taskcomment_id
    "type": [TaskComment](/sdk/data-task/#taskcomment)
| 
    empty  
TASK_LABELS_ADJUSTED  
---  
Occurs when a label is added to or removed from a task, including from the task panel. **Note:** unlike the other `TASK_*` events, the target of this event is the `TaskLabel` that changed — _not_ the task. The affected task's ID is available in the context object as `task.id` (use that to load the task, e.g. `Task.objects.get(id=self.event.context["task"]["id"])`), and `action` tells you whether the label was `add`ed or `remove`d.  
Target object| Context object  
    "id": task_label_id
    "type": [TaskLabel](/sdk/data-task/#tasklabel)
| 
    "patient":
       "id": pt_id
    "task":
        "id": task_id
    "action": literal["add", "remove"]  
TASK_COMPLETED  
---  
Occurs when a task is set to completed.  
Target object| Context object  
    "id": task_id
    "type": [Task](/sdk/data-task/#task)
| 
    "patient":
       "id": pt_id  
TASK_CLOSED  
---  
Occurs when a task is set to closed.  
Target object| Context object  
    "id": task_id
    "type": [Task](/sdk/data-task/#task)
| 
    "patient":
       "id": pt_id  
####  Task Metadata 
TASK_METADATA_CREATED  
---  
Occurs when a task's metadata is created.  
Target object| Context object  
    "id": taskmetadata_id
    "type": [TaskMetadata](/sdk/data-task/#taskmetadata)
| 
    empty  
TASK_METADATA_UPDATED  
---  
Occurs when a task's metadata is updated.  
Target object| Context object  
    "id": taskmetadata_id
    "type": [TaskMetadata](/sdk/data-task/#taskmetadata)
| 
    empty  
####  Staff 
STAFF_CREATED  
---  
Occurs when a staff is created.  
Target object| Context object  
    "id": staff_id
    "type": [Staff](/sdk/data-staff/#staff)
| 
    empty  
STAFF_UPDATED  
---  
Occurs when a staff is updated.  
Target object| Context object  
    "id": staff_id
    "type": [Staff](/sdk/data-staff/#staff)
| 
    empty  
STAFF_ACTIVATED  
---  
Occurs when a staff record is created with active=True, or a staff record's active field is updated from False to True.  
Target object| Context object  
    "id": staff_id
    "type": [Staff](/sdk/data-staff/#staff)
| 
    empty  
STAFF_DEACTIVATED  
---  
Occurs when a staff record's active field is updated from True to False.  
Target object| Context object  
    "id": staff_id
    "type": [Staff](/sdk/data-staff/#staff)
| 
    empty  
####  Staff External Identifier 
STAFF_EXTERNAL_IDENTIFIER_CREATED  
---  
Occurs when an external identifier is created for a staff member.  
Target object| Context object  
    "id": staffexternalidentifier_id
    "type": [StaffExternalIdentifier](/sdk/data-staff/#staffexternalidentifier)
| 
    "staff":
        "id": staff_id  
STAFF_EXTERNAL_IDENTIFIER_UPDATED  
---  
Occurs when an external identifier for a staff member is updated.  
Target object| Context object  
    "id": staffexternalidentifier_id
    "type": [StaffExternalIdentifier](/sdk/data-staff/#staffexternalidentifier)
| 
    "staff":
        "id": staff_id  
STAFF_EXTERNAL_IDENTIFIER_DELETED  
---  
Occurs when an external identifier for a staff member is deleted.  
Target object| Context object  
    "id": staffexternalidentifier_id
    "type": [StaffExternalIdentifier](/sdk/data-staff/#staffexternalidentifier)
| 
    "staff":
        "id": staff_id  
####  Staff Metadata 
STAFF_METADATA_CREATED  
---  
Occurs when a staff member's metadata is created.  
Target object| Context object  
    "id": staffmetadata_id
    "type": [StaffMetadata](/sdk/data-staff/#staffmetadata)
| 
    empty  
STAFF_METADATA_UPDATED  
---  
Occurs when a staff member's metadata is updated.  
Target object| Context object  
    "id": staffmetadata_id
    "type": [StaffMetadata](/sdk/data-staff/#staffmetadata)
| 
    empty  
STAFF_METADATA_DELETED  
---  
Occurs when a staff member's metadata is deleted.  
Target object| Context object  
    "id": staffmetadata_id
    "type": [StaffMetadata](/sdk/data-staff/#staffmetadata)
| 
    empty  
####  Vital Signs 
VITAL_SIGN_CREATED  
---  
Occurs when a vitals entry is created for a patient using the vitals command. Additional details for the vitals become available with subsequent VITAL_SIGN_UPDATED events.  
Target object| Context object  
    "id": vitalsign_id
    "type": None
| 
    empty  
VITAL_SIGN_UPDATED  
---  
Occurs when a vitals entry is updated for a patient.  
Target object| Context object  
    "id": vitalsign_id
    "type": None
| 
    empty  
###  Command lifecycle events 
These events fire during the command lifecycle.
####  Generic events 
Event| Occurs when| PRE_COMMAND_ORIGINATE| Before any command is entered into a note.  
---|---  
POST_COMMAND_ORIGINATE| After any command is entered into a note.  
PRE_COMMAND_UPDATE| Before the data in any command is updated.  
POST_COMMAND_UPDATE| After the data in any command is updated.  
PRE_COMMAND_COMMIT| Before any command is committed.  
POST_COMMAND_COMMIT| After any command is committed.  
PRE_COMMAND_DELETE| Before any command is deleted.  
POST_COMMAND_DELETE| After any command is deleted.  
PRE_COMMAND_ENTER_IN_ERROR| Before any command is marked as entered in error.  
POST_COMMAND_ENTER_IN_ERROR| After any command is marked as entered in error.  
PRE_COMMAND_EXECUTE_ACTION| Before an action is executed on any command.  
POST_COMMAND_EXECUTE_ACTION| After an action is executed on any command.  
POST_COMMAND_INSERTED_INTO_NOTE| After a user adds a command to a note in the Canvas UI. Commands added by a plugin effect or through the FHIR API do not fire this event.  
AVAILABLE_ACTIONS| When a command is rendered in the UI, after any update to data, state, or other changes  
#####  Transaction Behavior 
Pre-event handlers (`PRE_COMMAND_ORIGINATE`, `PRE_COMMAND_COMMIT`, `PRE_COMMAND_UPDATE`) run synchronously inside the same database transaction as the command operation. Your handler can perform validation or modify data, and if it raises an exception, both your changes and the command operation roll back together.
Post-event handlers (`POST_COMMAND_ORIGINATE`, `POST_COMMAND_COMMIT`, `POST_COMMAND_UPDATE`) use Django's `on_commit` mechanism and execute only after the outermost transaction commits successfully. If you wrap a command operation inside a `transaction.atomic()` block, the post-event handlers won't fire until that outer transaction commits.
This model lets you combine command operations with other database writes in a single atomic unit. You can originate a command and update related records together, knowing that either all operations succeed or none do.
See [Transactions](/sdk/custom-data-transactions/) for more on using `transaction.atomic()` in your plugins.
#####  Context Overview 
Each command lifecycle event provides specific context to the handler, depending on the stage of the command lifecycle.
**Base Context (All Events Except`PRE_COMMAND_ORIGINATE`)**:
    ```json
    {
      "note": { "uuid": "note-123" },
      "patient": { "id": "patient-123" },
      "fields": { "key": "value" }
    }
    ```
  - `note.uuid`: The unique identifier of the note associated with the command.
  - `patient.id`: The unique identifier of the patient associated with the note.
  - `fields`: A dictionary containing command-specific details. See examples for each command.
**`PRE_COMMAND_ORIGINATE` Context**: Since the command is not yet connected to a note, the `PRE_COMMAND_ORIGINATE` event context only includes:
    ```json
    {
      "fields": { "key": "value" }
    }
    ```
  - `fields`: Contains details specific to the command being originated.
#####  Accessing structured plan / treatment plan data 
If you want the structured contents of a finished note, such as a treatment plan or care plan, read its commands rather than parsing the rendered [DocumentReference](/sdk/data-document-reference/) PDF. Use the command lifecycle events above with the [Command](/sdk/data-command/) data model: read a note's commands with `note.commands.all()` and branch on each command's type. [Plan](/sdk/commands/#plan), [Prescribe](/sdk/commands/#prescribe), [Follow-up](/sdk/commands/#followup), [Task](/sdk/commands/#task), and Instruct commands carry most plan data.
#####  Post-originate versus inserted-into-note events 
The two event families catch different writes:
  - **`POST_ORIGINATE`** fires whenever a command is created, however it was written: in the Canvas UI, through the FHIR API, or by a plugin effect. Use it to react to every new command, or to **edit** the command that triggered it.
  - **`POST_INSERTED_INTO_NOTE`** (the per-command `*__POST_INSERTED_INTO_NOTE` events and `POST_COMMAND_INSERTED_INTO_NOTE`) fires only when a user inserts a command into the note body in the Canvas UI. Use it to respond to a clinician's action in the note, such as adding related commands next to the one they inserted.
#####  Avoiding recursion in post-update handlers 
> **Warning:** A handler that responds to a command's `*__POST_UPDATE` event and edits that same command can loop forever. The edit updates the command, which fires `POST_UPDATE` again, which edits it again.
Every `POST_UPDATE` handler that edits its own command needs a guard that returns no effects once the command already holds what you would set:
  1. **Compare before you edit.** Read the field from the event's `fields` context. If it already has the value you would write, return `[]`.
  2. **For values you compute from other inputs, cache what you used.** Store the inputs under a key such as `f"plan-update:{command_id}"` with the [cache](/sdk/caching/). On each event, return `[]` if the cached inputs match the current event. Only when they differ, update the cache and return the edit.
    ```python
    from canvas_sdk.commands import PlanCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    STANDARD_NARRATIVE = "Follow up in two weeks."
    class StandardizePlanNarrative(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PLAN_COMMAND__POST_UPDATE)
        def compute(self) -> list[Effect]:
            narrative = self.context["fields"].get("narrative")
            # The guard: the edit below fires POST_UPDATE again, so stop once it is applied.
            if not narrative or narrative == STANDARD_NARRATIVE:
                return []
            return [PlanCommand(command_uuid=self.target, narrative=STANDARD_NARRATIVE).edit()]
    ```
When the value comes from other data, cache the inputs instead. This handler writes a follow-up date into the plan, computed from the note's date of service. Its own edit fires `POST_UPDATE` again, finds the same inputs in the cache, and stops. A clinician's later edit to the narrative also leaves it alone, until the date of service changes:
    ```python
    from datetime import timedelta
    from canvas_sdk.caching.plugins import get_cache
    from canvas_sdk.commands import PlanCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Command
    class FollowUpDateInPlan(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PLAN_COMMAND__POST_UPDATE)
        def compute(self) -> list[Effect]:
            note = Command.objects.get(id=self.target).note
            inputs = note.datetime_of_service.isoformat()
            cache = get_cache()
            key = f"plan-update:{self.target}"
            # The guard: stop when this command was already updated from these inputs.
            if cache.get(key) == inputs:
                return []
            cache.set(key, inputs)
            follow_up = (note.datetime_of_service + timedelta(days=14)).date()
            narrative = f"Follow up on {follow_up.isoformat()}."
            return [PlanCommand(command_uuid=self.target, narrative=narrative).edit()]
    ```
* * *
####  Add Condition Command 
ADD_CONDITION_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
ADD_CONDITION_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADD_CONDITION__CONDITION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ADD_CONDITION__CONDITION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[ConditionSearchResult]  
####  Adjust Prescription Command 
ADJUST_PRESCRIPTION_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
ADJUST_PRESCRIPTION_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "change_medication_to": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ADJUST_PRESCRIPTION__INDICATIONS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
ADJUST_PRESCRIPTION__INDICATIONS__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ADJUST_PRESCRIPTION__PHARMACY__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
ADJUST_PRESCRIPTION__PHARMACY__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ADJUST_PRESCRIPTION__PRESCRIBE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[MedicationSearchResult]  
ADJUST_PRESCRIPTION__PRESCRIBE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ADJUST_PRESCRIPTION__CHANGE_MEDICATION_TO__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[MedicationSearchResult]  
ADJUST_PRESCRIPTION__CHANGE_MEDICATION_TO__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ADJUST_PRESCRIPTION__SUPERVISING_PROVIDER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
ADJUST_PRESCRIPTION__SUPERVISING_PROVIDER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ADJUST_PRESCRIPTION__PRESCRIBER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
ADJUST_PRESCRIPTION__PRESCRIBER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Allergy Command 
ALLERGY_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
ALLERGY_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "severity": str
      "narrative": str
      "approximate_date":
        "input": str
        "date": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ALLERGY__ALLERGY__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[AllergySearchResult]  
ALLERGY__ALLERGY__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Assess Command 
ASSESS_COMMAND__CONDITION_SELECTED  
---  
Occurs when an Assess command's condition is set to a condition already on the patient's chart, either by a clinician picking it or by a plugin editing the command with `condition_id`. `data.condition` holds the condition's `id` and its `codings`. Setting the condition to an ICD-10 code sends `ASSESS_COMMAND__ICD10_CODE_SELECTED` instead. Clearing the field sends neither event, and neither event fires when a plugin originates an Assess command with the condition already set.  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "data":
      "condition":
        "id": condition_id
        "codings":
          "code": str
          "system": str
          "display": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__ICD10_CODE_SELECTED  
---  
Occurs when an Assess command's condition is set to an ICD-10 code rather than a charted condition, either by a clinician picking a code the patient doesn't have charted or by a plugin editing the command with `icd10_code`. No condition is attached until commit, so `data.codings` holds the code. A plugin edit sends this event even when the patient already has a condition with that code; the clinician's search shows the charted condition in that case, so a clinician's pick sends `ASSESS_COMMAND__CONDITION_SELECTED`. Committing the command reuses the patient's charted condition with that code, or records a new one. The event doesn't fire when a plugin originates an Assess command with `icd10_code` already set.  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "data":
      "codings":
        "code": str
        "system": str
        "display": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
ASSESS_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "approximate_date_of_onset":
        "input": str
        "date": str
      "show_in_problem_list": bool
      "background": str
      "status": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS__CONDITION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ASSESS__CONDITION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[ConditionSearchResult]  
####  Cancel Prescription Command 
CANCEL_PRESCRIPTION_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescription": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CANCEL_PRESCRIPTION__SELECTED_PRESCRIPTION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
CANCEL_PRESCRIPTION__SELECTED_PRESCRIPTION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
####  Change Medication Command 
CHANGE_MEDICATION_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHANGE_MEDICATION__MEDICATION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[MedicationSearchResult]  
CHANGE_MEDICATION__MEDICATION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Chart Section Review Command 
CHART_SECTION_REVIEW_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "section": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHART_SECTION_REVIEW_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "section": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHART_SECTION_REVIEW_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "section": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHART_SECTION_REVIEW_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "section": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHART_SECTION_REVIEW_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
CHART_SECTION_REVIEW_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "section": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHART_SECTION_REVIEW_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "section": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CHART_SECTION_REVIEW_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "section": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  Clipboard Command 
CLIPBOARD_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
CLIPBOARD_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLIPBOARD_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "text": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
#####  Clipboard Fields Context 
The Clipboard Command provides the following fields in its context:
Field| Type| Description  
---|---|---  
`text`|  _string_|  The raw text content copied to the clipboard.  
Refer to the base context documentation for additional details about the full context structure.
    ```json
    {
      "note": { "uuid": "note-123" },
      "patient": { "id": "patient-123" },
      "fields": {
        "text": "Patient complains of persistent headaches for the past two weeks."
      }
    }
    ```
* * *
####  Close Goal Command 
CLOSE_GOAL_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
CLOSE_GOAL_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_id": dict
      "achievement_status": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CLOSE_GOAL__GOAL_ID__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
CLOSE_GOAL__GOAL_ID__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Assess Coding Gap Command 
ASSESS_CODING_GAP_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "details": str
      "diagnose": list
      "background": str
      "approximate_date_of_onset": str
      "todays_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ASSESS_CODING_GAP__DIAGNOSE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_id
    }
    "results": list[ConditionSearchResult]  
ASSESS_CODING_GAP__DIAGNOSE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_id
    }  
####  Create Coding Gap Command 
CREATE_CODING_GAP_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": list
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CREATE_CODING_GAP__DIAGNOSE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_id
    }
    "results": list[ConditionSearchResult]  
CREATE_CODING_GAP__DIAGNOSE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_id
    }  
####  Defer Coding Gap Command 
DEFER_CODING_GAP_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DEFER_CODING_GAP_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  Validate Coding Gap Command 
VALIDATE_CODING_GAP_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VALIDATE_CODING_GAP_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "detected_issue": str
      "status": str
      "date": str
      "details": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  Custom Command 
CUSTOM_COMMAND_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "content": str
      "schema_key": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
CUSTOM_COMMAND_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": str
    "user":
      "staff": staff_id  
####  Diagnose Command 
DIAGNOSE_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
DIAGNOSE_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnose": dict
      "background": str
      "approximate_date_of_onset":
        "input": str
        "date": str
      "today_assessment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DIAGNOSE__DIAGNOSE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[ConditionSearchResult]  
DIAGNOSE__DIAGNOSE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Educational Material Command 
EDUCATIONAL_MATERIAL_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
EDUCATIONAL_MATERIAL_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
EDUCATIONAL_MATERIAL__LANGUAGE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
EDUCATIONAL_MATERIAL__LANGUAGE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
EDUCATIONAL_MATERIAL__TITLE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
EDUCATIONAL_MATERIAL__TITLE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Family History Command 
FAMILY_HISTORY_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
FAMILY_HISTORY_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "family_history": dict
      "relative": dict
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FAMILY_HISTORY__FAMILY_HISTORY__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
FAMILY_HISTORY__FAMILY_HISTORY__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
FAMILY_HISTORY__RELATIVE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
FAMILY_HISTORY__RELATIVE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Follow Up Command 
FOLLOW_UP_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
FOLLOW_UP_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "requested_date": dict
      "note_type": dict
      "coding": dict
      "reason_for_visit": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
FOLLOW_UP__CODING__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
FOLLOW_UP__CODING__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
FOLLOW_UP__NOTE_TYPE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
FOLLOW_UP__NOTE_TYPE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Goal Command 
GOAL_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
GOAL_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
GOAL_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": str
      "start_date": str
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  History of Present Illness Command 
HISTORY_OF_PRESENT_ILLNESS_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
HISTORY_OF_PRESENT_ILLNESS_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  Imaging Order Command 
IMAGING_ORDER_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
IMAGING_ORDER_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "image": dict
      "indications": list[dict]
      "priority": str
      "additional_details": str
      "imaging_center": dict
      "comment": str
      "ordering_provider": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_ORDER__IMAGE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
IMAGING_ORDER__IMAGE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
IMAGING_ORDER__IMAGING_CENTER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
IMAGING_ORDER__IMAGING_CENTER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
IMAGING_ORDER__INDICATIONS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
IMAGING_ORDER__INDICATIONS__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
IMAGING_ORDER__ORDERING_PROVIDER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
IMAGING_ORDER__ORDERING_PROVIDER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Imaging Review Command 
IMAGING_REVIEW_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMAGING_REVIEW__REPORT__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
IMAGING_REVIEW__REPORT__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
IMAGING_REVIEW__COMMUNICATION_METHOD__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
IMAGING_REVIEW__COMMUNICATION_METHOD__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
####  Immunization Statement Command 
IMMUNIZATION_STATEMENT_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "statement": dict
      "date":
        "date": str
        "input": str
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZATION_STATEMENT__STATEMENT__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
IMMUNIZATION_STATEMENT__STATEMENT__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
IMMUNIZATION_STATEMENT_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
####  Immunize Command 
IMMUNIZE_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
IMMUNIZE_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "lot_number": dict
      "manufacturer": str
      "exp_date_original": str
      "sig_original": str
      "consent_given": bool
      "given_by": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
IMMUNIZE__CODING__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
IMMUNIZE__CODING__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
IMMUNIZE__GIVEN_BY__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
IMMUNIZE__GIVEN_BY__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
IMMUNIZE__LOT_NUMBER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
IMMUNIZE__LOT_NUMBER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Instruct Command 
INSTRUCT_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
INSTRUCT_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "instruct": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
INSTRUCT__INSTRUCT__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
INSTRUCT__INSTRUCT__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Lab Order Command 
`LAB_ORDER_COMMAND__POST_COMMIT` is useful for automating tasks when a lab is ordered, for example creating a task for a medical assistant whenever any lab command is committed. The event context includes the command `fields`, so you can branch on the order's details (for example, only create the task when `fields["lab_partner"]["text"]` is `"Generic Lab"`). The [lab-order-automated-task](https://www.canvasmedical.com/extensions/lab-order-automated-task) extension is a reference implementation.
LAB_ORDER_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
LAB_ORDER_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER_COMMAND__PRE_SEND  
---  
Fires from Canvas right before a lab order's FHIR `RequestGroup` is built and POSTed to Health Gorilla. Plugins may respond with one or more [HealthGorillaLabOrderOverride](/sdk/effect-health-gorilla-lab-order-override/) effects to inject account numbers, bill-to, performer organization, sub-tenant, or location into the outbound payload.  
Target object| Context object  
    "id": laborder_id
    "type": [LabOrder](/sdk/data-labs/#laborder)
| 
    "lab_order":
      "id": laborder_id
      "uuid": laborder_id
    "lab_partner": str
    "note":
      "id": note_id
      "uuid": note_id
    "patient":
      "id": pt_id  
HEALTH_GORILLA_LAB_ORDER_PREPARED  
---  
Fires from Canvas right after the outbound Health Gorilla FHIR `RequestGroup` dict is constructed and right before it is POSTed to Health Gorilla. Read-only — any effects returned by handlers are discarded. Complements `LAB_ORDER_COMMAND__PRE_SEND`, which fires before the build and accepts override effects.  
Target object| Context object  
    "id": laborder_id
    "type": [LabOrder](/sdk/data-labs/#laborder)
| 
    "lab_order":
      "id": laborder_id
      "uuid": laborder_id
    "lab_partner": str
    "note":
      "id": note_id
      "uuid": note_id
    "patient":
      "id": pt_id
    "request_group": dict  
LAB_ORDER_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "lab_partner": dict
      "tests": list[dict]
      "ordering_provider": dict
      "diagnosis": list[dict]
      "fasting_status": bool
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_ORDER__DIAGNOSIS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
LAB_ORDER__DIAGNOSIS__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
LAB_ORDER__LAB_PARTNER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
LAB_ORDER__LAB_PARTNER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
LAB_ORDER__ORDERING_PROVIDER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
LAB_ORDER__ORDERING_PROVIDER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
LAB_ORDER__TESTS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
LAB_ORDER__TESTS__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Lab Review Command 
LAB_REVIEW_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
LAB_REVIEW__REPORT__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
LAB_REVIEW__REPORT__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
LAB_REVIEW__COMMUNICATION_METHOD__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
LAB_REVIEW__COMMUNICATION_METHOD__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
####  Medical History Command 
MEDICAL_HISTORY_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
MEDICAL_HISTORY_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_medical_history": dict
      "approximate_start_date":
        "date": str
        "input": str
      "approximate_end_date":
        "date": str
        "input": str
      "show_on_condition_list": bool
      "comments": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICAL_HISTORY__APPROXIMATE_END_DATE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
MEDICAL_HISTORY__APPROXIMATE_END_DATE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
MEDICAL_HISTORY__APPROXIMATE_START_DATE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
MEDICAL_HISTORY__APPROXIMATE_START_DATE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
MEDICAL_HISTORY__PAST_MEDICAL_HISTORY__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[ConditionSearchResult]  
MEDICAL_HISTORY__PAST_MEDICAL_HISTORY__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Medication Statement Command 
MEDICATION_STATEMENT_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
MEDICATION_STATEMENT_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "sig": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
MEDICATION_STATEMENT__MEDICATION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[MedicationSearchResult]  
MEDICATION_STATEMENT__MEDICATION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Order DME Command 
ORDER_DME_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
ORDER_DME_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "item": dict
      "indications": list[dict]
      "quantity": int
      "length_of_need": str
      "send_to": dict
      "ordering_provider": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ORDER_DME__INDICATIONS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
ORDER_DME__INDICATIONS__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ORDER_DME__ITEM__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
ORDER_DME__ITEM__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ORDER_DME__ORDERING_PROVIDER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
ORDER_DME__ORDERING_PROVIDER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
ORDER_DME__SEND_TO__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
ORDER_DME__SEND_TO__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
Each pair of search events fires when a user searches in one of the command's fields:
  - `ORDER_DME__ITEM__*`: the item field, which searches the DME formulary.
  - `ORDER_DME__INDICATIONS__*`: the **Indications** field, which searches ICD-10 conditions.
  - `ORDER_DME__SEND_TO__*`: the **Send to** field, which searches for a supplier.
  - `ORDER_DME__ORDERING_PROVIDER__*`: the ordering provider field, which searches active staff who can prescribe.
Reply to a `PRE_SEARCH` event with an [`AUTOCOMPLETE_SEARCH_RESULTS`](/sdk/effects/) effect to supply the results; returning nothing runs the normal search. Reply to a `POST_SEARCH` event with the same effect to replace or annotate the results.
In `POST_SEARCH` events, each entry in `results` has `text`, `value`, `disabled`, `description`, `annotations`, and `extra` keys:
  - **Item results:** `text` is the product name, `annotations` holds the product's code system and code (for example, `HCPCS E0114`), and `extra` holds `dme_product_id`, `code`, and `code_system`. `code_system` is `HCPCS` or `INTERNAL`. The `value` and `extra.dme_product_id` IDs are Canvas's internal product IDs, not the external ID that the `OrderDmeCommand` `dme_product_id` parameter takes.
        ```json
        {
          "text": "Standard wheelchair",
          "disabled": false,
          "description": null,
          "annotations": ["HCPCS K0001"],
          "extra": {
            "dme_product_id": 12,
            "code": "K0001",
            "code_system": "HCPCS"
          },
          "value": "12"
        }
        ```
A product with no code has `null` in `annotations`.
  - **Ordering provider results:** `text` is the staff member's name with credentials. `value` is Canvas's internal staff ID, not the [Staff](/sdk/data-staff/#staff) `id` that the `OrderDmeCommand` `ordering_provider_key` parameter takes.
        ```json
        {
          "text": "Jane Smith MD",
          "disabled": false,
          "description": null,
          "annotations": null,
          "extra": null,
          "value": 42
        }
        ```
  - **Supplier results:** `text` is the supplier's name, `description` summarizes the supplier's phone, fax, and address, and `extra.contact` holds the contact record. Canvas searches suppliers in any specialty, using the service-area ZIP codes of the user's primary practice location.
        ```json
        {
          "text": "Pacific Mobility (Pacific Mobility Supply), Durable Medical Equipment",
          "disabled": false,
          "description": "Phone: (415) 555-0142 Fax: (415) 555-0143 Address: 2037 Irving St, San Francisco, CA 94122",
          "annotations": null,
          "extra": {
            "contact": {
              "id": 8703,
              "firstName": "Pacific",
              "lastName": "Mobility",
              "practiceName": "Pacific Mobility Supply",
              "specialty": "Durable Medical Equipment",
              "businessPhone": "4155550142",
              "businessFax": "4155550143",
              "businessAddress": "2037 Irving St, San Francisco, CA 94122",
              "composeAddress": "2037 Irving St, San Francisco, CA 94122",
              "notes": null,
              "score": 0
            }
          },
          "value": "8703"
        }
        ```
When the order is signed, Canvas saves the supplier from the selected result's `extra.contact`.
####  Perform Command 
PERFORM_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
PERFORM_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "perform": dict
      "notes": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PERFORM__PERFORM__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
PERFORM__PERFORM__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Physical Exam Command 
PHYSICAL_EXAM_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
PHYSICAL_EXAM_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PHYSICAL_EXAM__QUESTIONNAIRE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
PHYSICAL_EXAM__QUESTIONNAIRE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Plan Command 
PLAN_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
PLAN_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PLAN_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  POC Lab Test Command 
POC Lab Test commands carry a `test_values|<label>` field per template field — those labels are determined dynamically by the selected template, so the `fields` block below shows the static shape only; dynamic per-field entries appear alongside.
POC_LAB_TEST_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str   # one per template field
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
POC_LAB_TEST_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
POC_LAB_TEST_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "template": dict
      "indications": list[dict]
      "remarks": str
      "test_values|<label>": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  Prescribe Command 
PRESCRIBE_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
PRESCRIBE_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
PRESCRIBE__INDICATIONS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
PRESCRIBE__INDICATIONS__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
PRESCRIBE__PHARMACY__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
PRESCRIBE__PHARMACY__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
PRESCRIBE__PRESCRIBE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
PRESCRIBE__PRESCRIBE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
PRESCRIBE__SUPERVISING_PROVIDER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
PRESCRIBE__SUPERVISING_PROVIDER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
PRESCRIBE__PRESCRIBER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
PRESCRIBE__PRESCRIBER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Questionnaire Command 
QUESTIONNAIRE_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
QUESTIONNAIRE_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
      "result": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
QUESTIONNAIRE__QUESTIONNAIRE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
QUESTIONNAIRE__QUESTIONNAIRE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Reason for Visit Command 
REASON_FOR_VISIT_COMMAND__POST_COMMIT  
---  
This event does not fire. Reason for Visit commands can't be committed.  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
REASON_FOR_VISIT_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__PRE_COMMIT  
---  
This event does not fire. Reason for Visit commands can't be committed.  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "coding": dict
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REASON_FOR_VISIT__CODING__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REASON_FOR_VISIT__CODING__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Refer Command 
REFER_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
REFER_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "refer_to": dict
      "indications": list[dict]
      "clinical_question": str
      "priority": str
      "notes_to_specialist": str
      "include_visit_note": bool
      "internal_comment": str
      "documents_to_include": dict
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFER__REFER_TO__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REFER__REFER_TO__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REFER__INDICATIONS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REFER__INDICATIONS__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REFER__DOCUMENTS_TO_INCLUDE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REFER__DOCUMENTS_TO_INCLUDE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REFER__LINKED_ITEMS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REFER__LINKED_ITEMS_INCLUDE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Reference Command 
REFERENCE_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
REFERENCE_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERENCE_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "diagnostic_view_id": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  Referral Review Command 
REFERRAL_REVIEW_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFERRAL_REVIEW__REPORT__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REFERRAL_REVIEW__REPORT__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REFERRAL_REVIEW__COMMUNICATION_METHOD__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REFERRAL_REVIEW__COMMUNICATION_METHOD__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
####  Approve Refill Command 
APPROVE_REFILL_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
APPROVE_REFILL_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
APPROVE_REFILL_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "refills": int
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  Deny Refill Command 
DENY_REFILL_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
DENY_REFILL_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
DENY_REFILL_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "response_type": str
      "reason_code": str
      "note_to_pharmacist": str
      "refill_request": int
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  Refill Prescription Command 
REFILL_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
REFILL_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "prescribe": dict
      "indications": list[dict]
      "sig": str
      "days_supply": int
      "quantity_to_dispense": int
      "type_to_dispense": dict
      "refills": int
      "substitutions": str
      "pharmacy": dict
      "prescriber": dict
      "note_to_pharmacist": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REFILL__INDICATIONS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REFILL__INDICATIONS__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REFILL__PHARMACY__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REFILL__PHARMACY__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REFILL__PRESCRIBE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[MedicationSearchResult]  
REFILL__PRESCRIBE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REFILL__SUPERVISING_PROVIDER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REFILL__SUPERVISING_PROVIDER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REFILL__PRESCRIBER__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REFILL__PRESCRIBER__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Remove Allergy Command 
REMOVE_ALLERGY_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
REMOVE_ALLERGY_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "allergy": dict
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_ALLERGY__ALLERGY__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
REMOVE_ALLERGY__ALLERGY__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Remove Past Medical History Command 
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
REMOVE_PAST_MEDICAL_HISTORY__CONDITION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
REMOVE_PAST_MEDICAL_HISTORY__CONDITION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
####  Resolve Condition Command 
RESOLVE_CONDITION_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
RESOLVE_CONDITION_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "condition": dict
      "show_in_condition_list": bool
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
RESOLVE_CONDITION__CONDITION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
RESOLVE_CONDITION__CONDITION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[ConditionSearchResult]  
####  Review of Systems Command 
ROS_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
ROS_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
ROS__QUESTIONNAIRE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
ROS__QUESTIONNAIRE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Snooze Protocol Command 
SNOOZE_PROTOCOL_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
SNOOZE_PROTOCOL_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "protocol_key": str
      "snooze_until_date": str
      "snooze_reason": str
      "snooze_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SNOOZE_PROTOCOL__PROTOCOL__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
SNOOZE_PROTOCOL__PROTOCOL__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
####  Stop Medication Command 
STOP_MEDICATION_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
STOP_MEDICATION_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "medication": dict
      "rationale": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STOP_MEDICATION__MEDICATION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[MedicationSearchResult]  
STOP_MEDICATION__MEDICATION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Structured Assessment Command 
STRUCTURED_ASSESSMENT_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
STRUCTURED_ASSESSMENT_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "questionnaire": dict
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
STRUCTURED_ASSESSMENT__QUESTIONNAIRE__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
STRUCTURED_ASSESSMENT__QUESTIONNAIRE__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Surgical History Command 
SURGICAL_HISTORY_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
SURGICAL_HISTORY_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "past_surgical_history": dict
      "approximate_date":
        "input": str
        "date": str
      "comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
SURGICAL_HISTORY__PAST_SURGICAL_HISTORY__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
SURGICAL_HISTORY__PAST_SURGICAL_HISTORY__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Task Command 
TASK_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
TASK_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "assign_to": dict
      "due_date": str
      "priority": str
      "comment": str
      "labels": list[dict]
      "linked_items": list[dict]
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
TASK__ASSIGN_TO__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
TASK__ASSIGN_TO__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
TASK__LABELS__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
TASK__LABELS__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Update Diagnosis Command 
UPDATE_DIAGNOSIS_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
UPDATE_DIAGNOSIS_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "conditionId": str
      "newConditionCode": str
      "background": str
      "narrative": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_DIAGNOSIS__CONDITION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
UPDATE_DIAGNOSIS__CONDITION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
UPDATE_DIAGNOSIS__NEW_CONDITION__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
UPDATE_DIAGNOSIS__NEW_CONDITION__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
####  Update Goal Command 
UPDATE_GOAL_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
UPDATE_GOAL_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "goal_statement": dict
      "due_date": str
      "achievement_status": str
      "priority": str
      "progress": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UPDATE_GOAL__GOAL_STATEMENT__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
UPDATE_GOAL__GOAL_STATEMENT__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
####  Uncategorized Document Review Command 
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "report": str
      "message_to_patient": str
      "communication_method": str
      "internal_comment": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
UNCATEGORIZED_DOCUMENT_REVIEW__REPORT__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
UNCATEGORIZED_DOCUMENT_REVIEW__REPORT__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
UNCATEGORIZED_DOCUMENT_REVIEW__COMMUNICATION_METHOD__PRE_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }  
UNCATEGORIZED_DOCUMENT_REVIEW__COMMUNICATION_METHOD__POST_SEARCH  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "search_term": str
    "user": {
      "staff": staff_key
    }
    "results": list[dict]  
####  Visual Exam Finding 
VISUAL_EXAM_FINDING_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
VISUAL_EXAM_FINDING_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VISUAL_EXAM_FINDING_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "title": str
      "narrative": str
      "image": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
####  Vitals Command 
VITALS_COMMAND__POST_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__POST_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__POST_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__AVAILABLE_ACTIONS  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "actions":
      "name": string
    "user":
      "staff": staff_id  
VITALS_COMMAND__POST_VALIDATION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__POST_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__POST_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__POST_INSERTED_INTO_NOTE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__POST_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__PRE_COMMIT  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__PRE_DELETE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__PRE_ENTER_IN_ERROR  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__PRE_EXECUTE_ACTION  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__PRE_ORIGINATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
VITALS_COMMAND__PRE_UPDATE  
---  
Target object| Context object  
    "id": command_uuid
    "type": [Command](/sdk/data-command/)
| 
    "fields":
      "height": str
      "weight_lbs": str
      "weight_oz": str
      "waist_circumference": str
      "body_temperature": str
      "body_temperature_site": str
      "blood_pressure_systole": int
      "blood_pressure_diastole": str
      "blood_pressure_position_and_site": str
      "pulse": str
      "pulse_rhythm": str
      "respiration_rate": int
      "oxygen saturation": str
      "note": str
    "note":
      "uuid": note_id
    "patient":
      "id": pt_id  
###  Patient Portal Events 
PATIENT_PORTAL__APPOINTMENT_CANCELED  
---  
Occurs after an appointment is canceled  
Target| Target type| Context object  
    appt_id
| 
    [Appointment](/sdk/data-appointment/)
| 
    None  
PATIENT_PORTAL__APPOINTMENT_RESCHEDULED  
---  
Occurs after an appointment is rescheduled  
Target| Target type| Context object  
    appt_id
| 
    [Appointment](/sdk/data-appointment/)
| 
    None  
PATIENT_PORTAL__APPOINTMENT_CAN_BE_CANCELED  
---  
Occurs when checking if an appointment can be canceled  
Target| Target type| Context object  
    appt_id
| 
    [Appointment](/sdk/data-appointment/)
| 
    None  
PATIENT_PORTAL__APPOINTMENT_CAN_BE_RESCHEDULED  
---  
Occurs when checking if an appointment can be rescheduled  
Target| Target type| Context object  
    appt_id
| 
    [Appointment](/sdk/data-appointment/)
| 
    None  
PATIENT_PORTAL__APPOINTMENTS__SLOTS__POST_SEARCH  
---  
Occurs after the appointment slots search has been done, allowing the values to be modified  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    "slots_by_provider": {provider: {date: [{"start", "end"}]}} (JSON string)  
PATIENT_PORTAL__APPOINTMENTS__FORM_APPOINTMENT_TYPES__PRE_SEARCH  
---  
Occurs before appointment types are resolved, allowing the internal values to be bypassed  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    None  
PATIENT_PORTAL__APPOINTMENTS__FORM_APPOINTMENT_TYPES__POST_SEARCH  
---  
Occurs after appointment types are resolved, allowing the internal values to be modified  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    "appointment_types": [{"id", "title"}]  
PATIENT_PORTAL__APPOINTMENTS__FORM_LOCATIONS__PRE_SEARCH  
---  
Occurs before appointment locations are resolved, allowing the internal values to be bypassed  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    None  
PATIENT_PORTAL__APPOINTMENTS__FORM_LOCATIONS__POST_SEARCH  
---  
Occurs after appointment locations are resolved, allowing the internal values to be modified  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    "locations": [{"id", "title"}]  
PATIENT_PORTAL__APPOINTMENTS__FORM_PROVIDERS__PRE_SEARCH  
---  
Occurs before appointment providers are resolved, allowing the internal values to be bypassed  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    None  
PATIENT_PORTAL__APPOINTMENTS__FORM_PROVIDERS__POST_SEARCH  
---  
Occurs after appointment providers are resolved, allowing the internal values to be modified  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    "providers": [{"id", "title"}]  
PATIENT_PORTAL__GET_FORMS  
---  
Occurs on every page load of the Patient Portal; It only accepts the [`PATIENT_PORTAL__FORM_RESULT`](/sdk/patient-portal/#forms) effect as a return value  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    "requested_from": str["appointment" |
                          "labs" |
                          "login" |
                          "messaging" |
                          "my-health" |
                          "payment" |
                          "search-appointment"]  
`PATIENT_PORTAL__GET_FORMS` is the built-in mechanism for presenting patient forms: respond to it with one or more [`PATIENT_PORTAL__FORM_RESULT`](/sdk/patient-portal/#forms) effects (`FormResult`) and the questionnaires are shown to the patient in a modal after they log in. If you need a different presentation, such as a standalone page where a patient picks from a list of forms to complete before an upcoming appointment, build a custom [Application](/sdk/handlers-applications/) in the patient portal (a `portal_menu_item`-scoped Application that launches your own UI via `LaunchModalEffect`) rather than relying on the built-in forms modal.
PATIENT_PORTAL__DOCUMENT_DOWNLOADED  
---  
Occurs when a patient downloads a clinical document from the Patient Portal. Use it to keep your own record of what a patient has received, such as an after-visit summary or a lab requisition. The event is queued asynchronously once the document is generated, so a handler can't delay or block the download. See [Track Document Downloads](/sdk/patient-portal/#track-document-downloads) for the documents that fire it and the context each one carries.  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    "document": str["after_visit_summary", "lab_requisition", "imaging_requisition"]
    "note_id": str, the id of the [Note](/sdk/data-note/#note) (after_visit_summary only)
    "order_id": str, the id of the [LabOrder](/sdk/data-labs/#laborder) or [ImagingOrder](/sdk/data-imaging/#imagingorder) (lab_requisition and imaging_requisition only)  
PATIENT_PORTAL__POST_LOGIN  
---  
Occurs once, right after a patient logs in to the Patient Portal. Return a `LaunchModalEffect` with the `DEFAULT_MODAL` target to open a modal over the page the patient lands on. See [Show a Modal After Login](/sdk/patient-portal/#show-a-modal-after-login).  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
    "login_method": str["credentials" |
                        "access_token" |
                        "registration"]  
###  Action Buttons Events 
For more information on handling these events, see [Action Buttons](/sdk/handlers-action-buttons).
Action button and application events include context about the user who triggered them, so you can tailor behavior to the current user (for example, only showing a button to a specific staff member):
    ```python
    {
      "user": {
        "id": "<either staff or patient id>",
        "type": "Staff" | "Patient"
      }
    }
    ```
This `user` context is available in an `ActionButton`'s `visible()` and `handle()` methods and in an `Application`'s `on_open()` method.
SHOW_NOTE_HEADER_BUTTON  
---  
Occurs when patient notes are being loaded  
Target| Context object  
    patient_id
| 
      "note_id": str
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/)  
SHOW_NOTE_FOOTER_BUTTON  
---  
Occurs when patient notes are being loaded  
Target| Context object  
    patient_id
| 
      "note_id": str
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/)  
SHOW_NOTE_BODY_BUTTON  
---  
Occurs when patient notes are being loaded  
Target| Context object  
    patient_id
| 
      "note_id": str
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/)  
SHOW_NOTE_BODY_AUTOMATION_BUTTON  
---  
Occurs when patient notes are being loaded  
Target| Context object  
    patient_id
| 
      "note_id": str
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/)  
SHOW_NOTE_HEADER_DROPDOWN_BUTTON  
---  
Occurs when patient notes are being loaded  
Target| Context object  
    patient_id
| 
      "note_id": str
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/)  
SHOW_CHART_PATIENT_HEADER_BUTTON  
---  
Occurs when the patient header is being loaded, on both the chart and the profile page. This location sits outside any note, so `note_id` is null.  
Target| Context object  
    patient_id
| 
      "note_id": null
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/)  
SHOW_CHART_SUMMARY_SOCIAL_DETERMINANTS_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for social determinants section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_GOALS_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for goals section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_CONDITIONS_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for conditions section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_MEDICATIONS_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for medications section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_ALLERGIES_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for allergies section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_CARE_TEAMS_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for care teams section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_VITALS_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for vitals section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_IMMUNIZATIONS_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for immunizations section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_SURGICAL_HISTORY_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for surgical history section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_FAMILY_HISTORY_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for family history section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
SHOW_CHART_SUMMARY_CODING_GAPS_SECTION_BUTTON  
---  
Occurs when patient chart summary is being loaded, specifically for coding gaps section  
Target| Target type| Context object  
    patient_id
| 
    [Patient](/sdk/data-patient/)
| 
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
ACTION_BUTTON_CLICKED  
---  
Occurs when an action button is clicked  
Target| Context object  
    patient_id
| 
      "key": action_button_key
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
###  Note Custom Content 
NOTE__GET_CUSTOM_CONTENT  
---  
Occurs when a note renders on an instance in the [revamped note beta program](/product-updates/note-revamp/). Plugins respond with custom content blocks to show above the note body or inside a note section. See the [Note Custom Content effect](/sdk/effect-note-custom-content/) for usage details.  
Target  
    note_id  
###  Note Footer Configuration 
NOTE_FOOTER__GET_CONFIGURATION  
---  
Occurs when a note's footer is loaded. Allows plugins to configure the footer — for example, to hide Canvas's default state-transition buttons so plugin-provided buttons replace them. See the [Note Footer Configuration effect](/sdk/effect-note-footer-configuration/) for usage details.  
Target| Context object  
    note_id
| 
    empty  
###  Phone Dial Configuration 
PHONE_DIAL__GET_CONFIGURATION  
---  
Occurs when a patient chart loads its phone numbers. Allows plugins to make those numbers clickable and choose whether the device or the plugin handles a click. See the [Phone Dial Configuration effect](/sdk/effect-phone-dial-configuration/) for usage details.  
Target| Context object  
    patient_id
| 
    empty  
PHONE_NUMBER_CLICKED  
---  
Occurs when a user clicks a clickable phone number in a patient chart. Fires under both device and plugin handling. The context includes at least the following:  
Target| Context object  
    phone_number
| 
      "phone_number": str
      "source": str
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/)  
###  Application Events 
For more information on these events, see [Applications](/sdk/handlers-applications).
APPLICATION__ON_GET  
---  
Occurs when Canvas requests the available applications for a given scope. Handled automatically by [Note Applications](/sdk/handlers-embedded-applications/#note-applications) to return application metadata via the `SHOW_APPLICATION` effect.  
Target| Context object  
    scope
| 
      "scope": str
      "patient":
        "id": str
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
APPLICATION__ON_OPEN  
---  
Occurs when a user clicks on an application icon to open it  
Target| Context object  
    application_id
| 
      "patient":
        "id": str
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
###  Payment Processor Events 
These events drive the custom [Payment Processor](/sdk/handlers-payment-processors/) handlers. They are dispatched as a user moves through a payment workflow, and the actor that initiated the workflow is set on each event (see Event Actor). Every event other than `REVENUE__PAYMENT_PROCESSOR__LIST` includes the `identifier` of the processor it targets, so a handler only acts when the identifier matches its own.
The `identifier` is the unique id of the payment processor handler the event is intended for. Canvas derives it from the handler's class (its module path and class name) and exposes it on the handler as `self.identifier`; it is the same value the handler advertises via the [`PaymentProcessorMetadata`](/sdk/payment-processor-effect/#paymentprocessormetadata) effect when responding to `REVENUE__PAYMENT_PROCESSOR__LIST`.
REVENUE__PAYMENT_PROCESSOR__LIST  
---  
Occurs when Canvas gathers the list of available payment processors. A handler responds with a [PaymentProcessorMetadata](/sdk/payment-processor-effect/#paymentprocessormetadata) effect.  
Target| Context object  
    None
| 
    "payment_type": str  # optional, e.g. "card"  
REVENUE__PAYMENT_PROCESSOR__SELECTED  
---  
Occurs when a payment processor is selected. A handler responds with one or more [PaymentProcessorForm](/sdk/payment-processor-effect/#paymentprocessorform) effects.  
Target| Context object  
    None
| 
    "identifier": str
    "intent": str  # optional, "pay" | "add_card"
    "patient":
        "id": str  # optional  
REVENUE__PAYMENT_PROCESSOR__CHARGE  
---  
Occurs when a card is charged. A handler responds with a [CardTransaction](/sdk/payment-processor-effect/#cardtransaction) effect.  
Target| Context object  
    None
| 
    "identifier": str
    "amount": str
    "token": str
    "additional_context": str  # optional
    "patient":
        "id": str  # optional  
REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__LIST  
---  
Occurs when Canvas lists a patient's saved payment methods. A handler responds with one or more [PaymentMethod](/sdk/payment-processor-effect/#paymentmethod) effects.  
Target| Context object  
    None
| 
    "identifier": str
    "patient":
        "id": str  # optional  
REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__ADD  
---  
Occurs when a payment method is added for a patient. A handler responds with an [AddPaymentMethodResponse](/sdk/payment-processor-effect/#addpaymentmethodresponse) effect.  
Target| Context object  
    None
| 
    "identifier": str
    "token": str
    "additional_context": str  # optional
    "patient":
        "id": str  
REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__REMOVE  
---  
Occurs when a payment method is removed for a patient. A handler responds with a [RemovePaymentMethodResponse](/sdk/payment-processor-effect/#removepaymentmethodresponse) effect.  
Target| Context object  
    None
| 
    "identifier": str
    "token": str
    "patient":
        "id": str  
###  Stored Card Charge Events 
This event reports the outcome of a [Charge Stored Card](/sdk/effect-charge-stored-card/) effect. Unlike the payment processor events above, it is not a request for a handler to respond to: the charge has already been attempted, and nothing a handler returns changes it. Handle it to reconcile the result, and correlate it with the charge that produced it using `idempotency_key`, which is echoed from the request.
Apart from `success` and `error`, every value arrives as a string or `null`, including the amount and the ids that were UUIDs on the request. The context is already parsed into a dictionary on `self.event.context`, and the actor is the one that emitted the originating effect.
REVENUE__STORED_CARD__CHARGE_RESPONSE  
---  
Occurs when a [ChargeStoredCard](/sdk/effect-charge-stored-card/) effect has finished processing, whether or not the card was charged. Carries no card data or PHI.  
Target object| Context object  
    "id": pt_id
    "type": [Patient](/sdk/data-patient/#patient)
| 
    "success": bool          # whether the card was charged
    "payment_intent_id": str # processor's payment id, null on failure
    "error":                 # null on success
        "code": str          # see [Error codes](/sdk/effect-charge-stored-card/#error-codes)
        "message": str
    "idempotency_key": str   # echoed, use this to correlate
    "patient_id": str        # echoed, a [Patient](/sdk/data-patient/#patient) id
    "payment_card_id": str   # echoed, a [PaymentCard](/sdk/data-payment-card/) id under Stripe
    "claim_id": str          # echoed, a [Claim](/sdk/data-claim/) id, null when none
    "amount": str            # echoed, the dollar amount submitted  
###  Patient Portal Events 
APPLICATION__ON_CONTEXT_CHANGE  
---  
Occurs when a user navigates to a different URL while an application is open. Currently supported for revenue workflows.  
Target| Context object  
    application_id
| 
      "url": str
      "patient":
        "id": str
      "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)
      "claim": (optional)
        "id": str
      "claim_queue": (optional)
        "dbid": str  
APPLICATION__GET_NOTIFICATION_BADGE  
---  
Occurs when Canvas loads applications and requests the current notification badge count. Respond by overriding `compute_notification_badge()` on your [Application](/sdk/handlers-applications/#notification-badges) handler.  
Target| Context object  
    application_id
| 
      "staff":
        "id": str
        "type": [Staff](/sdk/data-staff/)
      "patient":
        "id": str
        "type": [Patient](/sdk/data-patient/)  
###  Patient Chart Configuration 
PATIENT_CHART__CONDITIONS  
---  
Occurs when the conditions are loaded on the patient chart.  
Target object| Context object  
    "id": patient_id
    "type": [Patient](/sdk/data-patient/)
| 
    "conditions":
        "id": condition id
        "codings":
          "code": str
          "system": str
          "display": str  
PATIENT_CHART__MEDICATIONS  
---  
Occurs when the medications are loaded on the patient chart.  
Target object| Context object  
    "id": patient_id
    "type": [Patient](/sdk/data-patient/)
| 
    "medications":
        "id": medication id
        "codings":
          "code": str
          "system": str
          "display": str  
PATIENT_CHART__DETECTED_ISSUES  
---  
Occurs when the detected issues are loaded on the patient chart. The context is a bare list rather than an object keyed by name, so iterate `self.context` directly. Each entry carries only an `id`; read anything else about the issue through [DetectedIssue](/sdk/data-detectedissue/).  
Target object| Context object  
    "id": patient_id
    "type": [Patient](/sdk/data-patient/)
| 
    list of:
        "id": detected issue id  
###  Patient Timeline Configuration 
PATIENT_TIMELINE__GET_CONFIGURATION  
---  
Occurs when a patient's chart is loaded. Allows plugins to configure which note types are visible on the timeline, and which the New Note button may offer. See the [Patient Timeline effect](/sdk/effect-patient-timeline/) for usage details.  
Target object| Context object  
    "id": patient_key
    "type": [Patient](/sdk/data-patient/)
| 
    empty  
###  Patient Group 
PATIENT_GROUP_CREATED  
---  
Occurs when a patient group is created  
Target object| Context object  
    "id": patient_group_id
    "type": [Patient Group](/sdk/data-patient-group/)
| 
    empty  
PATIENT_GROUP_UPDATED  
---  
Occurs when a patient group is updated  
Target object| Context object  
    "id": patient_group_id
    "type": [Patient Group](/sdk/data-patient-group/)
| 
    empty  
PATIENT_GROUP_MEMBERSHIP_CREATED  
---  
Occurs when a patient is added as a member of a group  
Target object| Context object  
    "id": patient_group_id
    "type": [Patient Group](/sdk/data-patient-group/)
| 
    "patient":
            "id": str
          "group":
            "id": str
PATIENT_GROUP_MEMBERSHIP_UPDATED  
---  
Occurs when a patient's group membership is updated  
Target object| Context object  
    "id": patient_group_id
    "type": [Patient Group](/sdk/data-patient-group/)
| 
    "patient":
            "id": str
          "group":
            "id": str
PATIENT_GROUP_MEMBERSHIP_DELETED  
---  
Occurs when a patient member is removed from a patient group  
Target object| Context object  
    "id": patient_group_id
    "type": [Patient Group](/sdk/data-patient-group/)
| 
    "patient":
            "id": str
          "group":
            "id": str  
###  SSO Events 
For more information on these events, see [SSO Capabilities](/sdk/sso/).
Event| Occurs when| SSO__PROCESS_ADDITIONAL_REQUEST_DATA| A user has just authenticated via SAML SSO. Read-only access to the SAML response. See [SSO Capabilities](/sdk/sso/#sso__process_additional_request_data).  
---|---  
SSO__GET_POST_LOGIN_REDIRECT| A user has just authenticated via SAML SSO and Canvas is deciding where to send them. Return a [REDIRECT_CONTEXT](/sdk/effect-redirect/) effect to override the destination. See [SSO Capabilities](/sdk/sso/#sso__get_post_login_redirect).  
###  Other Events 
Event| Occurs when| UNKNOWN| Default event type unlikely to ever be emitted.  
---|---  
CRON| This event fires regularly and can be used for scheduled tasks. See [CronTask](/sdk/handlers-crontask/).  
PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION| A patient chart's summary section is loading. This event fires very frequently — potentially tens of times per page load — so it should **not** be used to trigger database writes such as creating banner alerts or making API requests; doing so will slow page loads considerably. Create banner alerts at the time the underlying data is written (for example, on a patient external identifier event) rather than at display time.  
PATIENT_CHART_SUMMARY__GET_CUSTOM_SECTION| Canvas is requesting the content for a custom patient chart summary section. See [Patient Chart Summary Custom Section Handler](/sdk/patient-chart-summary-custom-section-handler/).  
PANEL_SECTIONS_CONFIGURATION| The panel section is loading.  
GET_PROVIDER_MENU_CONFIGURATION| The provider (hamburger) menu is loading. See [Provider Menu Configuration](/sdk/layout-effect/#provider-menu-configuration).  
PLUGIN_CREATED| A plugin is uploaded for the first time. See [ProtocolCards](/sdk/effect-protocol-cards/) and [BannerAlerts](/sdk/effect-banner-alerts/) for examples of how to use this event.  
PLUGIN_UPDATED| A plugin is enabled or when the plugin code has changed. See [ProtocolCards](/sdk/effect-protocol-cards/) and [BannerAlerts](/sdk/effect-banner-alerts/) for examples of how to use this event.  
PATIENT_PROFILE__ADD_PHARMACY__POST_SEARCH| Adding a pharmacy for a patient in their profile. Reply with `PATIENT_PROFILE__ADD_PHARMACY__POST_SEARCH_RESULTS` to supply the results.  
FAX__RECIPIENT__PRE_SEARCH| Searching for a fax recipient, before the search runs. Reply with `AUTOCOMPLETE_SEARCH_RESULTS` to supply the results; returning nothing runs the normal search. See [Service Provider search results](/sdk/data-serviceprovider/#search-results).   
Context object: 
    "search_term": str
    "source": "fax"
    "results": list[dict]
    "user":
        "staff": str  
FAX__RECIPIENT__POST_SEARCH| Searching for a fax recipient, after the search runs. Reply with `AUTOCOMPLETE_SEARCH_RESULTS` to replace or annotate the results.   
Context object: 
    "search_term": str
    "source": "fax"
    "results": list[dict]
    "user":
        "staff": str  
PATIENT_PROFILE__EXTERNAL_CARE_TEAM__PRE_SEARCH| Searching for a provider to add to a patient's external care team, before the search runs. Reply with `AUTOCOMPLETE_SEARCH_RESULTS` to supply the results; returning nothing runs the normal search.   
Context object: 
    "search_term": str
    "source": "care_team"
    "results": list[dict]
    "user":
        "staff": str  
PATIENT_PROFILE__EXTERNAL_CARE_TEAM__POST_SEARCH| Searching for a provider to add to a patient's external care team, after the search runs. Reply with `AUTOCOMPLETE_SEARCH_RESULTS` to replace or annotate the results.   
Context object: 
    "search_term": str
    "source": "care_team"
    "results": list[dict]
    "user":
        "staff": str  
PATIENT_PORTAL__WIDGET_CONFIGURATION| Patient Portal landing page is loading. See [Tailoring Portal Landing Page](/guides/custom-landing-page/) for examples of how to use this event.  
PATIENT_METADATA__GET_ADDITIONAL_FIELDS| Patient Profile is loading. See [How to add patient profile additional fields](/guides/profile-additional-fields/) for examples of how to use this event.   
Context object: 
    "patient":
        "id": str
    "user":
        "id": str
        "type": [Staff](/sdk/data-staff/) | [Patient](/sdk/data-patient/)  
GET_HOMEPAGE_CONFIGURATION| Homepage is loading. See [Set default homepage](/guides/set-default-homepage/) for examples of how to use this event.  
COMMAND__FORM__GET_ADDITIONAL_FIELDS| Command is originated. See [Command metadata Create Form](/sdk/command-metadata-create-form-effect/) for how to use this event.   
Target: 
    "command_uuid": str
Context object: 
    "schema_key": str
    "purpose": "form" | "print"  
####  One-time backfill with `PLUGIN_UPDATED`
Event-driven plugins only react to changes that happen after they are installed, so existing records (for example, patients who already have a qualifying external identifier) will not trigger them. To apply an effect to existing records when a plugin is published, write a separate handler that responds to `PLUGIN_UPDATED`, queries for the records that need the effect, and returns the effects for any that do not already have it. For example, a backfill handler can find every patient with a matching external identifier and no existing [Banner Alert](/sdk/effect-banner-alerts/), and return an `AddBannerAlert` effect for each. Because the handler checks for the alert before creating it (keyed by the banner's `key`), it is idempotent — you can upload it once, remove it, or re-upload it later without creating duplicates.
###  Search Result Data Structures 
Many event payloads include search results. This section documents the common structures within them.
####  MedicationSearchResult 
Medication search events (such as `MEDICATION_STATEMENT__MEDICATION__POST_SEARCH`, `PRESCRIBE__PRESCRIBE__POST_SEARCH`, etc.) return results that follow this structure:
    ```json
    {
      "text": "acetaminophen 500 mg tablet",
      "disabled": false,
      "description": null,
      "annotations": null,
      "extra": {
        "coding": [
          {
            "code": 206813,
            "display": "acetaminophen 500 mg tablet",
            "system": "http://www.fdbhealth.com/"
          },
          {
            "code": "198440",
            "display": "acetaminophen 500 mg tablet",
            "system": "http://www.nlm.nih.gov/research/umls/rxnorm"
          }
        ],
        "clinical_quantities": [
          {
            "erx_quantity": "1.0000000",
            "representative_ndc": "57896021910",
            "clinical_quantity_description": "tablet",
            "erx_ncpdp_script_quantity_qualifier_code": "C48542",
            "erx_ncpdp_script_quantity_qualifier_description": "Tablet"
          }
        ]
      },
      "value": 206813
    }
    ```
For detailed information about medication data structures, see [Medication](/sdk/data-medication/).
For examples of working with medication search results, see the [Customize Search Results](/guides/customize-search-results/) guide.
####  ConditionSearchResult 
Condition/diagnosis search events (such as `DIAGNOSE__DIAGNOSE__POST_SEARCH`, `MEDICAL_HISTORY__PAST_MEDICAL_HISTORY__POST_SEARCH`, etc.) return results that follow this structure:
    ```json
    {
      "text": "Broken internal left hip prosthesis, subsequent encounter",
      "disabled": false,
      "description": null,
      "annotations": ["T84.011D"],
      "extra": {
        "coding": [
          {
            "code": "T84011D",
            "display": "Broken internal left hip prosthesis, subsequent encounter",
            "system": "ICD-10"
          },
          {
            "code": 404684003,
            "display": "Broken internal left hip prosthesis, subsequent encounter",
            "system": "http://snomed.info/sct"
          }
        ]
      },
      "value": "T84011D"
    }
    ```
The Assess command's condition search lists the patient's charted conditions before new ICD-10 codes. A plugin handling `ASSESS__CONDITION__PRE_SEARCH` or `ASSESS__CONDITION__POST_SEARCH` can receive both kinds of result:
  - **Charted conditions** come first, active ones before the rest. A resolved condition is left out when an active condition has the same ICD-10 code. Picking it would make it a second active condition. An empty search term returns only charted conditions. A search term matches a charted condition when its ICD-10 code contains the term. It also matches when every word of the term appears in the condition's name, in any order. A charted condition's `value` is the condition's id rather than an ICD-10 code, and its `extra` has no `coding`. Its `annotations` hold the ICD-10 code followed by the condition's clinical status, such as `Active` or `Resolved`.
  - **ICD-10 codes** from the terminology search follow, in the structure shown above. A code the patient already has charted is listed as the charted condition instead, so picking it doesn't record a duplicate.
    ```json
    {
      "text": "Unilateral primary osteoarthritis, right knee",
      "annotations": ["M17.11", "Active"],
      "value": 4217
    }
    ```
For detailed information about condition data structures, see [Condition](/sdk/data-condition/).
####  AllergySearchResult 
Allergy search events (such as `ALLERGY__ALLERGY__POST_SEARCH`, `REMOVE_ALLERGY__ALLERGY__POST_SEARCH`, etc.) return results that follow this structure:
    ```json
    {
      "text": "Penicillins (allergy group)",
      "disabled": false,
      "description": null,
      "annotations": null,
      "extra": {
        "coding": [
          {
            "code": 476,
            "display": "Penicillins",
            "system": "http://www.fdbhealth.com/"
          }
        ],
        "category_id": 1,
        "category": "allergy group"
      },
      "value": 476
    }
    ```
For detailed information about allergy data structures, see [Allergy Intolerance](/sdk/data-allergy-intolerance/).

---

# Abnormal Lab Task Notification

Source: https://docs.canvasmedical.com/sdk/example-abnormal_lab_task_notification/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/abnormal_lab_task_notification) for this plugin on GitHub.
This Canvas EMR plugin automatically creates task notifications whenever lab results with abnormal values are received, ensuring critical lab findings are flagged for prompt clinical review.
##  SDK Features 
  - Responds to `LAB_REPORT_CREATED` [event](/sdk/events/#labs)
  - Loads and parses the [Lab Report data model](/sdk/data-labs/#labreport) to identify [lab values](/sdk/data-labs/#labvalue) flagged as abnormal
  - Returns a [task effect](/sdk/effect-tasks/#adding-a-task)
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.1.0",
        "name": "abnormal_lab_task_notification",
        "description": "A plugin that creates task notifications for abnormal lab values",
        "components": {
            "handlers": [
                {
                    "class": "abnormal_lab_task_notification.handlers.abnormal_lab_handler:AbnormalLabHandler",
                    "description": "Monitors lab reports and creates tasks for abnormal values",
                    "data_access": {
                        "event": "LAB_REPORT_CREATED",
                        "read": [
                            "lab_reports",
                            "lab_values"
                        ],
                        "write": [
                            "tasks"
                        ]
                    }
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "tags": ["lab", "notifications", "tasks"],
        "variables": [],
        "license": "NONE",
        "readme": "This plugin monitors incoming lab reports and creates task notifications for any abnormal lab values, ensuring they are flagged for prompt review."
    }
    ```
##  handlers/ 
###  abnormal_lab_handler.py 
**Purpose and Functionality**
This file defines a handler called AbnormalLabHandler for use with the Canvas Medical SDK. Its primary function is to monitor for the creation of new laboratory reports (`LAB_REPORT_CREATED` events). When such an event occurs, the handler inspects the report to determine if it contains any abnormal lab values. If abnormal results are found, it automatically creates a task for prompt clinical review.
**Event Handling**
  - The handler listens for the LAB_REPORT_CREATED event.
  - When triggered, it examines the relevant [lab report(/sdk/data-labs/#labreport)] for any values marked as abnormal.
**Core Logic**
  - It fetches the full LabReport instance specified by the event.
  - It filters out any reports that are for test purposes, junked, or do not belong to a patient.
  - It iterates through all values within the lab report.
  - For each value, it checks if there is a non-empty abnormal_flag.
  - If one or more abnormal values are found, it creates a task for the associated patient.
**Effects Produced**
  - Adds a new open task titled "Review Abnormal Lab Values ({count} abnormal)", labeled as "abnormal-lab" and "urgent-review" to the patient's workflow.
  - Logs the creation of the task and any errors encountered in the process.
**Error Handling**
  - If anything goes wrong (e.g., the report is missing, or there's a processing error), it logs the error and does not produce any task.
**Summary**
This handler automates the process of flagging abnormal laboratory results for clinical review within Canvas Medical, enhancing the safety net for critical lab findings by ensuring they are not overlooked.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.task import AddTask, TaskStatus
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data.lab import LabReport
    from logger import log
    class AbnormalLabHandler(BaseHandler):
        """
        A handler that monitors lab reports and creates task notifications
        for abnormal lab values to ensure prompt review.
        Triggers on: LAB_REPORT_CREATED events
        Effects: Creates tasks for abnormal lab values
        """
        RESPONDS_TO = EventType.Name(EventType.LAB_REPORT_CREATED)
        def compute(self) -> list[Effect]:
            """
            This method gets called when a LAB_REPORT_CREATED event is fired.
            It checks for abnormal lab values and creates tasks for them.
            """
            # Get the lab report ID from the event target
            lab_report_id = self.event.target.id
            try:
                # Get the lab report instance with filters applied
                lab_report = LabReport.objects.filter(
                    id=lab_report_id,
                    for_test_only=False,
                    junked=False,
                    patient__isnull=False
                ).first()
                if not lab_report:
                    return []
                patient_id = lab_report.patient.id
                # Check all lab values for abnormal flags
                abnormal_values = []
                for lab_value in lab_report.values.all():
                    # Check if the lab value has an abnormal flag (handle None case)
                    abnormal_flag = getattr(lab_value, 'abnormal_flag', None) or ""
                    if abnormal_flag.strip():
                        abnormal_values.append(lab_value)
                if not abnormal_values:
                    return []
                # Create a task for the abnormal lab values
                abnormal_count = len(abnormal_values)
                task_title = f"Review Abnormal Lab Values ({abnormal_count} abnormal)"
                # Create the task
                task = AddTask(
                    patient_id=patient_id,
                    title=task_title,
                    status=TaskStatus.OPEN,
                    labels=["abnormal-lab", "urgent-review"]
                )
                applied_task = task.apply()
                log.info(f"Created task for {abnormal_count} abnormal lab value(s) in report {lab_report_id}")
                return [applied_task]
            except Exception as e:
                log.error(f"Error processing lab report {lab_report_id}: {str(e)}")
                return []
    ```

---

# AI Note Titles

Source: https://docs.canvasmedical.com/sdk/example-ai_note_titles/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/ai_note_titles) for this plugin on GitHub.
##  Description 
Plugin that renames Notes when locked using OpenAI and the contents of the Note.
##  Configuration 
This example plugin defines the following "secrets" in the manifest file:
    ```plaintext
        "variables": [
            {"name": "OPENAI_API_KEY", "sensitive": true}
        ],
    ```
Once defined in the `MANIFEST.json`, set the secrets for your plugin in the Admin UI of your Canvas EMR. [Read more](https://docs.canvasmedical.com/sdk/secrets/)
###  OPENAI_API_KEY 
[OpenAI API Key](https://platform.openai.com/docs/api-reference/authentication)
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "ai_note_titles",
        "description": "Edit the description in CANVAS_MANIFEST.json",
        "components": {
            "handlers": [
                {
                    "class": "ai_note_titles.handlers.rename_note:Handler",
                    "description": "Renames Notes when locked using OpenAI and the contents of the Note"
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [
            {"name": "OPENAI_API_KEY", "sensitive": true}
        ],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  handlers/ 
###  rename_note.py 
**Purpose**
This code defines a handler in a Canvas SDK plugin that automatically renames clinical notes when they are locked, using the OpenAI API to generate new titles based on the note content.
**Class Overview**
  - The main class, `Handler`, extends `BaseHandler`.
  - The handler listens for `NOTE_STATE_CHANGE_EVENT_CREATED` events—specifically, when a note's state changes (e.g., gets locked).
**Main Workflow**
  - When a relevant event fires, the `compute` method is triggered.
  - It extracts the note ID from the context.
  - If the note event corresponds to a locking action, it proceeds.
  - It collects the note content and sends it (along with instructions) to OpenAI's API, requesting a concise, descriptive title.
  - If a valid title is returned, it generates an `update` effect to rename the note in Canvas.
**OpenAI Integration**
  - The `get_note_title` function prepares headers and a request payload from the note's structured content and specific instructions.
  - It POSTS this data to OpenAI's API (note: the endpoint used, `/v1/responses`, is likely a placeholder).
  - It parses the response to extract the generated title.
**Supporting Functions**
  - `get_model`: Returns the OpenAI model name (`gpt-4.1`).
  - `get_input`: Serializes note commands (actions or entries inside the note) to JSON for use as the prompt to the language model.
  - `get_instructions`: Supplies explicit instructions and examples to OpenAI, guiding it to create short, clinically meaningful titles.
  - `is_locked_note_event`: Checks if the event is specifically a note being locked (not other state transitions).
**Error Handling**
  - Logs issues if the note ID is missing, the OpenAI call fails, or expected fields are missing in the response.
**Effect on Canvas**
  - If a new title is obtained, issues a `NoteEffect.update()` call to rename the note instance.
**Summary**
This file defines a Canvas plugin handler that listens for notes being locked, then uses OpenAI to generate and set a concise, relevant note title based on its clinical contents.
    ```python
    import json
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note import Note as NoteEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.utils.http import Http
    from canvas_sdk.v1.data.command import Command
    from canvas_sdk.v1.data.note import CurrentNoteStateEvent, NoteStates
    from logger import log
    class Handler(BaseHandler):
        """Renames Notes when locked using OpenAI and the contents of the Note."""
        RESPONDS_TO: list[str] = [
            EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED),
        ]
        def compute(self) -> list[Effect]:
            """This method gets called when an event of the type RESPONDS_TO is fired."""
            note_id: str | None = self.context.get("note_id")
            if not note_id:
                log.error("No note ID found in context")
                return []
            if not self.is_locked_note_event():
                return []
            new_title = self.get_note_title(note_id)
            if not new_title:
                return []
            return [NoteEffect(instance_id=note_id, title=new_title).update()]
        def get_note_title(self, note_id: str) -> str | None:
            """Get the new note title from the note."""
            headers = {
                "Authorization": f"Bearer {self.secrets.get('OPENAI_API_KEY')}",
                "Content-Type": "application/json",
            }
            payload = {
                "input": self.get_input(note_id),
                "instructions": self.get_instructions(),
                "model": self.get_model(),
                "temperature": 0,
            }
            response = Http().post(
                "https://api.openai.com/v1/responses", headers=headers, data=json.dumps(payload)
            )
            if not response.ok:
                log.error(
                    f"Generate note title request failed: {response.status_code} - {response.text}"
                )
                return None
            response_json = response.json()
            new_title: str | None = None
            try:
                new_title = response_json.get("output")[0].get("content")[0].get("text")
            except Exception as e:
                log.error(f"Failed to get note title from response: {response.text} {e}")
            return new_title
        def get_model(self) -> str:
            """Get the OpenAI model to use."""
            return "gpt-4.1"
        def get_input(self, note_id: str) -> str:
            """Stringified commands within note to be used as input for OpenAI."""
            commands = Command.objects.filter(
                note__id=note_id, entered_in_error__isnull=True, committer__isnull=False
            )
            return json.dumps(list(commands.values("schema_key", "data")))
        def get_instructions(self) -> str:
            """Instructions for OpenAI to use to rename the note."""
            return """
            You are a clinical documentation specialist that generates a clinical note title using 10 words or less.
            This will read by a clinician looking to get a quick overview of the note.
            Return the exact title ONLY and nothing else.
            Examples:
            Ankle edema and amlodipine intolerance, medication change discussion
            Refilled metoprolol succinate ER and rosuvastatin 10 mg tablets
            Follow up call regarding elevated heart rate to 120
            Fall with back pain, unsteady gait, declined ER and HHA
            """
        def is_locked_note_event(self) -> bool:
            """Check if the note is locked."""
            return (
                CurrentNoteStateEvent.objects.values_list("state", flat=True).get(
                    id=self.event.target.id
                )
                == NoteStates.LOCKED
            )
    ```

---

# API Samples

Source: https://docs.canvasmedical.com/sdk/example-api_samples/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/api_samples) for this plugin on GitHub.
Showcases the usage of the SimpleAPI handler
##  Configuration 
Once installed, see the plugin configuration page to set credentials to make authenticated requests.
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "api_samples",
        "description": "Example usages of the SimpleAPI handler",
        "components": {
            "handlers": [
                {
                    "class": "api_samples.routes.hello_world:HelloWorldAPI",
                    "description": "Returns a json message"
                },
                {
                    "class": "api_samples.routes.email_bounce:EmailBounceAPI",
                    "description": "Creates a task to confirm patient contact info"
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [
            {"name": "my-api-key", "sensitive": true}
        ],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  routes/ 
###  email_bounce.py 
The code defines an endpoint for handling bounced email events.
**Endpoint**
  - **Path:** `/crm-webhooks/email-bounce`
  - **Method:** POST
  - **Expected Body:** JSON containing `{"mrn": "valid patient MRN"}`
  - **Authorization:** Requires an API key in the `Authorization` header that matches the plugin secret `'my-api-key'`.
**Core Functionality**
  - When a POST request is received:
    - It authenticates the request by verifying the provided API key against a stored secret.
    - It retrieves the `Patient` object from the database with the given MRN (Medical Record Number) from the request body.
    - It schedules a new open task for that patient:
      - **Title:** `"Please confirm contact information."`
      - **Due Date:** 5 days from the current UTC date
      - **Label:** `"CRM"`
  - Returns a response indicating both the creation of the task and a confirmation JSON message.
**Intended Use**
This endpoint provides an automated workflow to prompt staff to confirm and update patient contact information in response to an email bounce event, improving contact data quality in clinical operations.
    ```python
    import arrow
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.effects.task import AddTask, TaskStatus
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    from canvas_sdk.v1.data import Patient
    #
    # POST /plugin-io/api/api_samples/crm-webhooks/email-bounce
    # Body: { "mrn": "valid patient MRN" }
    # Headers: "Authorization <your value for 'my-api-key'>"
    #
    class EmailBounceAPI(SimpleAPIRoute):
        PATH = "/crm-webhooks/email-bounce"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            return credentials.key == self.secrets["my-api-key"]
        def post(self) -> list[Response]:
            patient = Patient.objects.get(mrn=self.request.json()["mrn"])
            five_days_from_now = arrow.utcnow().shift(days=5).datetime
            task_effect = AddTask(
                patient_id=patient.id,
                title="Please confirm contact information.",
                due=five_days_from_now,
                status=TaskStatus.OPEN,
                labels=["CRM"],
            )
            return [task_effect.apply(), JSONResponse({"message": "Task Created"})]
    ```
###  hello_world.py 
This code defines a simple API endpoint which handles requests to the path `/hello-world`. When a GET request is made to this endpoint, the API responds with a JSON message that says "Hello world!".
**Authentication**
The endpoint requires an API key for authentication. The client must provide an API key (as a header called `Authorization`). The provided key is compared to a value stored in `self.secrets["my-api-key"]`. If the keys match, authentication is successful and the request is allowed; otherwise, it will be denied.
**Response**
A GET request to `/plugin-io/api/api_samples/hello-world` (when authenticated) returns a JSON response in the following format:
    ```json
    {
      "message": "Hello world!"
    }
    ```
    ```python
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    #
    # GET /plugin-io/api/api_samples/hello-world
    # Headers: "Authorization <your value for 'my-api-key'>"
    #
    class HelloWorldAPI(SimpleAPIRoute):
        PATH = "/hello-world"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            return credentials.key == self.secrets["my-api-key"]
        def get(self) -> list[Response]:
            return [JSONResponse({"message": "Hello world!"})]
    ```

---

# AWS S3

Source: https://docs.canvasmedical.com/sdk/example-aws_s3/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/aws_s3) for this plugin on GitHub.
##  Description 
Plugin that provides a SimpleAPI for managing AWS S3 objects, including listing, uploading, downloading, deleting files, and generating presigned URLs. It also includes a chart application that renders a form interface for interacting with S3 directly from the chart.
##  Configuration 
This example plugin defines the following "secrets" in the manifest file:
    ```plaintext
        "variables": [
            {"name": "S3Key", "sensitive": true},
            {"name": "S3Secret", "sensitive": true},
            {"name": "S3Region", "sensitive": false},
            {"name": "S3Bucket", "sensitive": false}
        ],
    ```
Once defined in the `MANIFEST.json`, set the secrets for your plugin in the Admin UI of your Canvas EMR. [Read more](https://docs.canvasmedical.com/sdk/secrets/)
###  S3Key 
Your AWS Access Key ID.
###  S3Secret 
Your AWS Secret Access Key.
###  S3Region 
The AWS region where your S3 bucket is located (e.g., `us-east-1`).
###  S3Bucket 
The name of your S3 bucket.
##  CANVAS_MANIFEST.json 
    ```json
    {
      "sdk_version": "0.81.0",
      "plugin_version": "0.0.1",
      "name": "aws_manip",
      "description": "use AWS S3 to store, retrieve and delete documents",
      "components": {
        "handlers": [
          {
            "class": "aws_manip.handlers.aws_manip:AwsManip",
            "description": "AWS extractor based on AWS S3"
          }
        ],
        "applications": [
          {
            "class": "aws_manip.handlers.aws_form_app:AwsFormApp",
            "name": "AWS S3 Document Management",
            "description": "AWS S3 manip",
            "icon": "static/aws_manip.png",
            "scope": "patient_specific",
            "show_in_panel": false
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [
        {"name": "S3Key", "sensitive": true},
        {"name": "S3Secret", "sensitive": true},
        {"name": "S3Region", "sensitive": false},
        {"name": "S3Bucket", "sensitive": false}
      ],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
##  handlers/ 
###  aws_manip.py 
**Purpose**
This code defines a SimpleAPI handler that exposes REST endpoints for managing objects in an Amazon S3 bucket using the Canvas SDK's AWS S3 client.
**Class Overview**
  - The main class, `AwsManip`, extends `SimpleAPI`.
  - It creates an S3 client using credentials stored in plugin secrets.
**Main Workflow**
  - `GET /list_items` — Lists all objects in the configured S3 bucket.
  - `GET /get_item/<item_key>` — Retrieves an object's content by its key.
  - `GET /presigned_url/<item_key>` — Generates a presigned URL for temporary (1-hour) access to an object.
  - `POST /upload_item/<item_key>` — Uploads content to S3, handling both text and binary content types.
  - `DELETE /delete_item/<item_key>` — Deletes an object from S3 by key.
**S3 Client Integration**
  - The `_s3_client` method creates an `S3` client instance from `canvas_sdk.clients.aws.libraries`, configured with `S3Credentials` from plugin secrets.
  - Each endpoint checks `client.is_ready()` before performing operations.
    ```python
    from http import HTTPStatus
    from aws_manip.constants.secrets import Secrets
    from canvas_sdk.clients.aws.libraries import S3
    from canvas_sdk.clients.aws.structures import Credentials as S3Credentials
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, PlainTextResponse, Response
    from canvas_sdk.handlers.simple_api import Credentials, SimpleAPI, api
    class AwsManip(SimpleAPI):
        """Simple API handler for AWS S3 object management operations."""
        PREFIX = None
        USER_TYPE_STAFF = "Staff"
        def authenticate(self, credentials: Credentials) -> bool:
            """Authenticate API requests.
            Args:
                credentials: The credentials provided with the request.
            Returns:
                True to allow all requests (authentication bypassed).
            """
            return True
        def _s3_client(self) -> S3:
            """Create and configure an S3 client with credentials from secrets.
            Returns:
                Configured S3 client instance.
            """
            return S3(
                S3Credentials(
                    key=self.secrets[Secrets.s3_key],
                    secret=self.secrets[Secrets.s3_secret],
                    region=self.secrets[Secrets.s3_region],
                    bucket=self.secrets[Secrets.s3_bucket],
                )
            )
        @api.get("/list_items")
        def list_items(self) -> list[Response | Effect]:
            """List all objects in the S3 bucket."""
            client = self._s3_client()
            if client.is_ready():
                content = [p.key for p in client.list_s3_objects("")]
                status_code = HTTPStatus(HTTPStatus.OK)
                return [JSONResponse(content, status_code=status_code)]
            return []
        @api.get("/get_item/<item_key>")
        def get_item(self) -> list[Response | Effect]:
            """Retrieve an object's content from S3 by key."""
            item_key = self.request.path_params["item_key"]
            client = self._s3_client()
            if client.is_ready() and item_key:
                content = client.access_s3_object(item_key).content
                status_code = HTTPStatus(HTTPStatus.OK)
                return [Response(content, status_code=status_code)]
            return []
        @api.get("/presigned_url/<item_key>")
        def presigned_url(self) -> list[Response | Effect]:
            """Generate a presigned URL for temporary access to an S3 object."""
            item_key = self.request.path_params["item_key"]
            client = self._s3_client()
            if client.is_ready() and item_key:
                content = client.generate_presigned_url(item_key, 3600)
                status_code = HTTPStatus(HTTPStatus.OK)
                return [PlainTextResponse(content, status_code=status_code)]
            return []
        @api.post("/upload_item/<item_key>")
        def upload_item(self) -> list[Response | Effect]:
            """Upload content to S3 with the specified key."""
            item_key = self.request.path_params["item_key"]
            client = self._s3_client()
            content = self.request.body
            content_type = self.request.content_type
            if client.is_ready() and item_key:
                if content_type == "text/plain":
                    response = client.upload_text_to_s3(item_key, content.decode("utf-8"))
                else:
                    response = client.upload_binary_to_s3(item_key, content, content_type)
                return [Response(response.content, status_code=response.status_code)]
            return []
        @api.delete("/delete_item/<item_key>")
        def delete_item(self) -> list[Response | Effect]:
            """Delete an object from S3 by key."""
            item_key = self.request.path_params["item_key"]
            client = self._s3_client()
            if client.is_ready() and item_key:
                content = client.delete_object(item_key).content
                status_code = HTTPStatus(HTTPStatus.OK)
                return [Response(content, status_code=status_code)]
            return []
    ```
###  aws_form_app.py 
**Purpose**
This code defines an Application handler that launches a modal form in the right chart pane for interacting with the S3 management API endpoints.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    from canvas_sdk.templates import render_to_string
    class AwsFormApp(Application):
        """Application handler for launching the AWS S3 management form interface."""
        PLUGIN_API_BASE_ROUTE = "/plugin-io/api/aws_manip"
        def on_open(self) -> Effect:
            """Render and launch the AWS S3 management modal form."""
            content = render_to_string(
                "templates/aws_form.html",
                {
                    "listItemsURL": f"{self.PLUGIN_API_BASE_ROUTE}/list_items",
                    "getItemURL": f"{self.PLUGIN_API_BASE_ROUTE}/get_item",
                    "presignedUrlURL": f"{self.PLUGIN_API_BASE_ROUTE}/presigned_url",
                    "uploadItemURL": f"{self.PLUGIN_API_BASE_ROUTE}/upload_item",
                    "deleteItemURL": f"{self.PLUGIN_API_BASE_ROUTE}/delete_item",
                },
            )
            return LaunchModalEffect(
                content=content,
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
            ).apply()
    ```

---

# Charting API Examples

Source: https://docs.canvasmedical.com/sdk/example-charting_api_examples/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/charting_api_examples) for this plugin on GitHub.
This example plugin provides several examples of APIs you might define when automating charting in Canvas.
  - Notes
    - Creating a note
    - Getting information about a note
    - Searching for notes by patient, type, and date of service
    - Adding billing line items to a note
  - Commands
    - Creating a command
    - Creating multiple commands from a single request
    - Creating a command and committing it in a single request
##  Configuration 
All of the example endpoints in this plugin are protected with [API key authentication](https://docs.canvasmedical.com/sdk/handlers-simple-api-http/#api-key-1). Once installed, you'll need to set the `simpleapi-api-key` value on the plugin's configuration page in your EHR.
##  Endpoint Documentation 
###  Search Notes 
`GET /plugin-io/api/charting_api_examples/notes/`
This endpoint allows the retrieval of an optionally filtered set of notes. The results are paginated, and the client can exert some control over the page size. The response body will include an attribute, `next_page`, which will either contain a URL to the next page of the same filtered set or be `null`, indicating there are no more records to fetch.
####  Optional query parameters: 
#####  limit 
_int_
Determines the number of results to return per page.
  - If unspecified, the default is 10.
  - If a number less than 1 is specified, 1 will be used.
  - If a number greate than 100 is specified, 100 will be used.
#####  offset 
_int_
Number of records to skip with returning results. When used with **limit** , this enables the pagination of results.
  - If unspecified, the default is 0.
  - If a number less than 0 is specified, 0 will be used.
#####  patient_id 
_str_
Filters the notes returned to just those associated with the given patient.
#####  note_type 
_coding_
You can search by just the code value or you can search by the system and code in the format "system|code" (e.g. `http://snomed.info/sct|308335008`).
#####  datetime_of_service 
_iso8601 formatted datetime string_
Exact match for notes with the given datetime.
#####  datetime_of_service__gt 
_iso8601 formatted datetime string_
Filter to notes occurring after the given datetime.
#####  datetime_of_service__gte 
_iso8601 formatted datetime string_
Filter to notes occurring at or after the given datetime.
#####  datetime_of_service__lt 
_iso8601 formatted datetime string_
Filter to notes occurring before the given datetime.
#####  datetime_of_service__lte 
_iso8601 formatted datetime string_
Filter to notes occurring at or before the given datetime.
####  Example Request 
    ```bash
    curl --request GET \
      --url 'https://training.canvasmedical.com/plugin-io/api/charting_api_examples/notes/?limit=2&offset=4' \
      --header 'Authorization: <your-api-key-goes-here>'
    ```
####  Example Response 
    ```json
    {
      "next_page": "https://training.canvasmedical.com/plugin-io/api/charting_api_examples/notes/?limit=2&offset=6",
      "count": 2,
      "notes": [
        {
          "id": "10ff2047-6301-4ab4-81cd-b500e7df8ef7",
          "patient_id": "5350cd20de8a470aa570a852859ac87e",
          "provider_id": "5843991a8c934118ab4f424c839b340f",
          "datetime_of_service": "2025-02-21 23:31:45.627894+00:00",
          "note_type": {
            "id": "c5df4f03-58e4-442b-ad6c-0d3dadc6b726",
            "name": "Office visit",
            "coding": {
              "display": "Office Visit",
              "code": "308335008",
              "system": "http://snomed.info/sct"
            }
          }
        },
        {
          "id": "4dba128f-96cc-4dd0-814b-a064bfdcde7e",
          "patient_id": "5350cd20de8a470aa570a852859ac87e",
          "provider_id": "336159560091471cb6b0e149d9054697",
          "datetime_of_service": "2025-02-21 23:31:45.928071+00:00",
          "note_type": {
            "id": "c5df4f03-58e4-442b-ad6c-0d3dadc6b726",
            "name": "Office visit",
            "coding": {
              "display": "Office Visit",
              "code": "308335008",
              "system": "http://snomed.info/sct"
            }
          }
        }
      ]
    }
    ```
###  Read a Note 
`GET /plugin-io/api/charting_api_examples/notes/<note-id>/`
####  Example Response 
    ```json
    {
      "note": {
        "id": "1490b8db-00a9-47d9-9170-ec142460b586",
        "patient_id": "5350cd20de8a470aa570a852859ac87e",
        "provider_id": "6b33e69474234f299a56d480b03476d3",
        "datetime_of_service": "2025-10-02 23:30:00+00:00",
        "state": "NEW",
        "note_type": {
          "id": "c5df4f03-58e4-442b-ad6c-0d3dadc6b726",
          "name": "Office visit",
          "coding": {
            "display": "Office Visit",
            "code": "308335008",
            "system": "http://snomed.info/sct"
          }
        }
      }
    }
    ```
###  Create a Note 
`POST /plugin-io/api/charting_api_examples/notes/`
####  Example Request Body 
    ```json
    {
      "practice_location_id": "306b19f0-231a-4cd4-ad2d-a55c885fd9f8",
      "note_type_id": "c5df4f03-58e4-442b-ad6c-0d3dadc6b726",
      "patient_id": "5350cd20de8a470aa570a852859ac87e",
      "provider_id": "6b33e69474234f299a56d480b03476d3",
      "datetime_of_service": "2025-10-04 23:30:00",
      "title": "My cool note"
    }
    ```
###  Add Billing Line Item to a Note 
`POST /plugin-io/api/charting_api_examples/notes/<note-id>/billing_line_items/`
####  Example Request Body 
    ```json
    {
      "cpt_code": "98008"
    }
    ```
###  Add a Diagnose Command to a Note 
`POST /plugin-io/api/charting_api_examples/notes/<note-id>/diagnose/`
`icd10_code` is required, but `committed` may be true, false, or omitted entirely.
####  Example Request Body 
    ```json
    {
      "icd10_code": "E119",
      "committed": true
    }
    ```
###  Add Multiple Commands to a Note 
`POST /plugin-io/api/charting_api_examples/notes/<note-id>/prechart/`
####  Example Request Body 
    ```json
    null
    ```
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "charting_api_examples",
        "description": "A series of custom API routes that showcase SDK charting functionality",
        "components": {
            "handlers": [
                {
                    "class": "charting_api_examples.routes.notes:NoteAPI",
                    "description": "Endpoints that showcase interactions with notes."
                },
                {
                    "class": "charting_api_examples.routes.billing_line_items:BillingLineItemAPI",
                    "description": "Endpoints for interacting with billing line items on a note."
                },
                {
                    "class": "charting_api_examples.routes.commands:CommandAPI",
                    "description": "Endpoints for interacting with commands on a note."
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [
            {"name": "simpleapi-api-key", "sensitive": true}
        ],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  routes/ 
###  commands.py 
This file provides an example of how to define REST API endpoints in a Canvas-based plugin for inserting medical charting commands to clinical notes, with validation, error handling, and support for both single and batch command operations.
**Endpoints**
  1. `/notes/<id>/diagnose/` (POST):
     - Adds a DiagnoseCommand to the specified note.
     - Expects a JSON body with at least an "icd10_code" parameter, and optionally "committed" (boolean).
     - If "committed" is true, the diagnose command is also committed immediately after being originated.
     - Handles missing attribute errors and note-not-found situations gracefully, responding with appropriate error messages and status codes.
  2. `/notes/<id>/prechart/` (POST):
     - Initiates (originates) several commands at once for a note: ReasonForVisitCommand, PhysicalExamCommand, DiagnoseCommand, and PlanCommand.
     - Designed to quickly set up the structure for clinical pre-charting with a single request.
**Implementation Highlights**
  - The API is protected with API key authentication via `APIKeyAuthMixin`.
  - Uses utility functions (`get_note_from_path_params`, `note_not_found_response`) to locate notes and standardize error responses.
  - Returns both command effects (operations that are intended to be executed in the Canvas system) and standard JSON responses.
  - Uses status codes according to best practices, addressing Python version differences by using explicit numeric codes where needed.
**Canvas SDK Features Used**
  - Commands: `DiagnoseCommand`, `PhysicalExamCommand`, `PlanCommand`, `ReasonForVisitCommand` — each representing an action to be performed on a note.
  - Effects: Chainable "originate" (create/begin the command) and "commit" (finalize/commit the command).
    ```python
    from http import HTTPStatus
    from uuid import uuid4
    from canvas_sdk.commands import (
        DiagnoseCommand,
        PhysicalExamCommand,
        PlanCommand,
        ReasonForVisitCommand,
    )
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPI, api
    from canvas_sdk.v1.data.note import Note
    from charting_api_examples.util import get_note_from_path_params, note_not_found_response
    class CommandAPI(APIKeyAuthMixin, SimpleAPI):
        PREFIX = "/notes"
        """
        This shows how you can create an endpoint to insert a particular type of
        command. In this example, it's a diagnose command. It can be committed or
        left uncommitted.
        POST /plugin-io/api/charting_api_examples/notes/<note-id>/diagnose/
        Headers: "Authorization <your value for 'simpleapi-api-key'>"
        Body: {
            "icd10_code": "E11.9",
            "committed": false
        }
        """
        @api.post("/<id>/diagnose/")
        def add_diagnose_command(self) -> list[Response | Effect]:
            required_attributes = {"icd10_code",}
            request_body = self.request.json()
            missing_attributes = required_attributes - request_body.keys()
            if len(missing_attributes) > 0:
                return [
                    JSONResponse(
                        {"error": f"Missing required attribute(s): {', '.join(missing_attributes)}"},
                        # Normally you should use a constant, but this status
                        # code's constant changes in 3.13 from
                        # UNPROCESSABLE_ENTITY to UNPROCESSABLE_CONTENT. Using the
                        # number directly here avoids that future breakage.
                        status_code=422,
                    )
                ]
            note = get_note_from_path_params(self.request.path_params)
            if not note:
                return note_not_found_response()
            diagnose_command = DiagnoseCommand(
                note_uuid=str(note.id),
                icd10_code=request_body["icd10_code"].upper(),
            )
            if request_body.get("committed"):
                # To chain command effects, you must know what the command's id
                # is. To accomplish that, we set the id ourselves rather than
                # allow the database to assign one.
                diagnose_command.command_uuid = str(uuid4())
                command_effects = [diagnose_command.originate(), diagnose_command.commit()]
            else:
                command_effects = [diagnose_command.originate()]
            return [
                *command_effects,
                JSONResponse({"message": "Command data accepted for creation"}, status_code=HTTPStatus.ACCEPTED)
            ]
        """
        This shows how you can originate many commands from the same request.
        POST /plugin-io/api/charting_api_examples/notes/<note-id>/prechart/
        Headers: "Authorization <your value for 'simpleapi-api-key'>"
        Body: {
        }
        """
        @api.post("/<id>/prechart/")
        def add_precharting_commands(self) -> list[Response | Effect]:
            request_body = self.request.json()
            note = get_note_from_path_params(self.request.path_params)
            if not note:
                return note_not_found_response()
            rfv = ReasonForVisitCommand(note_uuid=str(note.id))
            exam = PhysicalExamCommand(note_uuid=str(note.id))
            diagnose = DiagnoseCommand(note_uuid=str(note.id))
            plan = PlanCommand(note_uuid=str(note.id))
            return [
                rfv.originate(),
                exam.originate(),
                diagnose.originate(),
                plan.originate(),
                JSONResponse({"message": "Command data accepted for creation"}, status_code=HTTPStatus.ACCEPTED)
            ]
    ```
###  notes.py 
Defines an API endpoint for working with clinical notes. The API supports listing, creating, and retrieving notes, with filtering and pagination features. Authentication is handled through an API key.
**Endpoints**
  - **GET /notes/**
    - Returns a paginated list of notes.
    - Supports filters:
      - `patient_id`: Filter notes for a specific patient.
      - `note_type`: Filter by note type (by code or by system| code).  
---|---  
      - `datetime_of_service`, `datetime_of_service__gt`, `datetime_of_service__gte`, `datetime_of_service__lt`, `datetime_of_service__lte`: Date/time based filters.
    - Pagination:
      - `limit`: Number of results (default 10, min 1, max 100).
      - `offset`: Pagination offset (default 0, min 0).
    - If more results exist after the current page, a `next_page` link is included.
    - Returns a JSON object with `notes` (list), `count` (number of notes returned), and `next_page` (URL or None).
  - **POST /notes/**
    - Creates a new note.
    - Requires a JSON body with:
      - `note_type_id`, `datetime_of_service` (as string), `patient_id`, `practice_location_id`, `provider_id`, `title`
    - If required fields are missing, returns an error with status 422.
    - Otherwise, initiates note creation and immediately returns an accepted response (`202 Accepted`) with a confirmation message.
  - **GET /notes/ <note-id>/**
    - Returns details for a specific note by its ID.
    - If the note doesn't exist, returns a "not found" response.
    - If found, returns note details, including its state (from `CurrentNoteStateEvent`), patient/provider IDs, datetime, and type info (id, name, coding).
**Helpers and Utilities**
  - Uses utilities such as `get_note_from_path_params` and `note_not_found_response` for ID lookup and error handling.
  - Uses Django-style ORM filters and queryset slicing.
  - Uses the `arrow` library for date parsing.
  - All endpoints expect authentication via the `simpleapi-api-key`.
    ```python
    import arrow
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note.note import Note as NoteEffect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPI, api
    from canvas_sdk.v1.data.note import Note, CurrentNoteStateEvent
    from charting_api_examples.util import get_note_from_path_params, note_not_found_response
    class NoteAPI(APIKeyAuthMixin, SimpleAPI):
        PREFIX = "/notes"
        """
        GET /plugin-io/api/charting_api_examples/notes/
        Headers: "Authorization <your value for 'simpleapi-api-key'>"
        """
        @api.get("/")
        def index(self) -> list[Response | Effect]:
            notes = Note.objects.select_related('patient', 'provider', 'note_type_version').order_by("dbid")
            query_params = self.request.query_params
            # User specified, default 10, min 1, max 100
            limit = min(max(int(query_params.get("limit", 10)), 1), 100)
            # User specified, default 0, min 0, no max
            offset = max(int(query_params.get("offset", 0)), 0)
            if "patient_id" in query_params:
                notes = notes.filter(patient__id=query_params["patient_id"])
            if "note_type" in query_params:
                # You can search by just the code value or you can search by the
                # system and code in the format system|code (e.g
                # http://snomed.info/sct|308335008).
                if "|" in query_params["note_type"]:
                    system, code = query_params["note_type"].split("|")
                    notes = notes.filter(note_type_version__system=system, note_type_version__code=code)
                else:
                    notes = notes.filter(note_type_version__code=query_params["note_type"])
            if "datetime_of_service" in query_params:
                notes = notes.filter(datetime_of_service=query_params["datetime_of_service"])
            if "datetime_of_service__gt" in query_params:
                notes = notes.filter(datetime_of_service__gt=query_params["datetime_of_service__gt"])
            if "datetime_of_service__gte" in query_params:
                notes = notes.filter(datetime_of_service__gte=query_params["datetime_of_service__gte"])
            if "datetime_of_service__lt" in query_params:
                notes = notes.filter(datetime_of_service__lt=query_params["datetime_of_service__lt"])
            if "datetime_of_service__lte" in query_params:
                notes = notes.filter(datetime_of_service__lte=query_params["datetime_of_service__lte"])
            # If there are more results matching the filter after the ones we're
            # returning, provide the link to the next page with the proper offset.
            # If there aren't any more results, return None so the client can tell
            # that there are no more results to fetch.
            link_to_next = None
            if notes[offset+limit:].count() > 0:
                requested_uri = self.context.get("absolute_uri")
                if "offset" in query_params:
                    link_to_next = requested_uri.replace(f"offset={offset}", f"offset={offset+limit}")
                else:
                    param_separator = "?" if len(query_params) == 0 else "&"
                    link_to_next = requested_uri + f"{param_separator}offset={offset+limit}"
            # Apply limit and offset
            notes = notes[offset:offset+limit]
            count = len(notes)
            return [
                JSONResponse({
                    "next_page": link_to_next,
                    "count": count,
                    "notes": [{
                        "id": str(note.id),
                        "patient_id": str(note.patient.id),
                        "provider_id": str(note.provider.id),
                        "datetime_of_service": str(note.datetime_of_service),
                        "note_type": {
                            "id": str(note.note_type_version.id),
                            "name": note.note_type_version.name,
                            "coding": {
                                "display": note.note_type_version.display,
                                "code": note.note_type_version.code,
                                "system": note.note_type_version.system,
                            },
                        },
                    } for note in notes]
                })
            ]
        """
        POST /plugin-io/api/charting_api_examples/notes/
        Headers: "Authorization <your value for 'simpleapi-api-key'>"
        Body: {
    		"note_type_id": "c5df4f03-58e4-442b-ad6c-0d3dadc6b726",
            "datetime_of_service": "2025-02-21 23:31:42",
    		"patient_id": "5350cd20de8a470aa570a852859ac87e",
    		"practice_location_id": "306b19f0-231a-4cd4-ad2d-a55c885fd9f8",
    		"provider_id": "6b33e69474234f299a56d480b03476d3",
    		"title": "My Note Title",
        }
        """
        @api.post("/")
        def create(self) -> list[Response | Effect]:
            required_attributes = {
                "note_type_id",
                "datetime_of_service",
                "patient_id",
                "practice_location_id",
                "provider_id",
                "title",
            }
            request_body = self.request.json()
            missing_attributes = required_attributes - request_body.keys()
            if len(missing_attributes) > 0:
                return [
                    JSONResponse(
                        {"error": f"Missing required attribute(s): {', '.join(missing_attributes)}"},
                        # Normally you should use a constant, but this status
                        # code's constant changes in 3.13 from
                        # UNPROCESSABLE_ENTITY to UNPROCESSABLE_CONTENT. Using the
                        # number directly here avoids that future breakage.
                        status_code=422,
                    )
                ]
            note_type_id = request_body["note_type_id"]
            datetime_of_service = arrow.get(request_body["datetime_of_service"]).datetime
            patient_id = request_body["patient_id"]
            practice_location_id = request_body["practice_location_id"]
            provider_id = request_body["provider_id"]
            title = request_body["title"]
            note_effect = NoteEffect(
                note_type_id=note_type_id,
                datetime_of_service=datetime_of_service,
                patient_id=patient_id,
                practice_location_id=practice_location_id,
                provider_id=provider_id,
                title=title,
            )
            return [
                note_effect.create(),
                JSONResponse({"message": "Note data accepted for creation"}, status_code=HTTPStatus.ACCEPTED)
            ]
        """
        GET /plugin-io/api/charting_api_examples/notes/<note-id>/
        Headers: "Authorization <your value for 'simpleapi-api-key'>"
        """
        @api.get("/<id>/")
        def read(self) -> list[Response | Effect]:
            note = get_note_from_path_params(self.request.path_params)
            if not note:
                return note_not_found_response()
            status_code = HTTPStatus.OK
            current_note_state = CurrentNoteStateEvent.objects.get(note=note).state
            response = {
                "note": {
                    "id": str(note.id),
                    "patient_id": str(note.patient.id),
                    "provider_id": str(note.provider.id),
                    "datetime_of_service": str(note.datetime_of_service),
                    "state": current_note_state,
                    "note_type": {
                        "id": str(note.note_type_version.id),
                        "name": note.note_type_version.name,
                        "coding": {
                            "display": note.note_type_version.display,
                            "code": note.note_type_version.code,
                            "system": note.note_type_version.system,
                        },
                    },
                },
            }
            return [JSONResponse(response, status_code=status_code)]
    ```
###  billing_line_items.py 
This file defines an API endpoint for adding billing line items (represented by CPT codes) to a note.
**Key Components**
  - Imports utility and SDK classes for effects, API handling, and response generation.
  - Defines a class, `BillingLineItemAPI`, which inherits API authentication and handling functionalities.
  - Registers an HTTP POST endpoint at `/notes/<note-id>/billing_line_items/`.
  - Expects an API key in the request header for authentication.
  - Expects the request body to be JSON with a "cpt_code" attribute.
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.billing_line_item import AddBillingLineItem
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPI, api
    from canvas_sdk.v1.data.note import Note
    from charting_api_examples.util import get_note_from_path_params, note_not_found_response
    class BillingLineItemAPI(APIKeyAuthMixin, SimpleAPI):
        PREFIX = "/notes"
        """
        POST /plugin-io/api/charting_api_examples/notes/<note-id>/billing_line_items/
        Headers: "Authorization <your value for 'simpleapi-api-key'>"
        Body: {
            "cpt_code": "98006"
        }
        """
        @api.post("/<id>/billing_line_items/")
        def add_billing_line_item(self) -> list[Response | Effect]:
            required_attributes = {"cpt_code",}
            request_body = self.request.json()
            missing_attributes = required_attributes - request_body.keys()
            if len(missing_attributes) > 0:
                return [
                    JSONResponse(
                        {"error": f"Missing required attribute(s): {', '.join(missing_attributes)}"},
                        # Normally you should use a constant, but this status
                        # code's constant changes in 3.13 from
                        # UNPROCESSABLE_ENTITY to UNPROCESSABLE_CONTENT. Using the
                        # number directly here avoids that future breakage.
                        status_code=422,
                    )
                ]
            note = get_note_from_path_params(self.request.path_params)
            if not note:
                return note_not_found_response()
            # To see what else you can do with billing line items, visit our docs:
            # https://docs.canvasmedical.com/sdk/effect-billing-line-items/#adding-a-billing-line-item
            effect = AddBillingLineItem(
                note_id=str(note.id),
                cpt=request_body["cpt_code"],
            )
            return [
                effect.apply(),
                JSONResponse({"message": "Billing line item data accepted for creation"}, status_code=HTTPStatus.ACCEPTED)
            ]
    ```
##  util.py 
This file provides utility functions for working with Note objects. The utilities include input validation, standard JSON error responses, and fetching Note objects by ID.
**Function: is_valid_uuid**
This function checks whether a given string is a valid UUID (specifically version 4).
  - Takes a single string argument.
  - Returns True if the string is a properly formatted version 4 UUID, False otherwise.
**Function: note_not_found_response**
This function returns a standardized JSON error response indicating that a requested Note was not found.
  - Uses JSONResponse from the SDK.
  - Sets the response status to HTTP 404 (NOT FOUND) and the body to {"error": "Note not found."}.
**Function: get_note_from_path_params**
This function attempts to retrieve a Note object using a dictionary of path parameters.
  - Extracts the "id" from path_params.
  - Validates the ID as a UUID using is_valid_uuid.
  - If invalid, returns None.
  - If valid, attempts to retrieve a Note object with the given ID (using Note.objects.get).
  - If the Note does not exist, catches the DoesNotExist exception and returns None.
  - Returns the Note object if found, or None if not found/invalid.
**Imports and External Dependencies**
  - uuid.UUID: For validating UUIDs.
  - http.HTTPStatus: For standardized HTTP status codes.
  - canvas_sdk.effects.simple_api.JSONResponse: For returning consistent API responses.
  - canvas_sdk.v1.data.note.Note: For interacting with Note objects from the Canvas SDK.
    ```python
    from uuid import UUID
    from http import HTTPStatus
    from canvas_sdk.effects.simple_api import JSONResponse
    from canvas_sdk.v1.data.note import Note
    def is_valid_uuid(possible_uuid):
        try:
            uuid_obj = UUID(possible_uuid, version=4)
        except ValueError:
            return False
        return str(uuid_obj) == possible_uuid
    def note_not_found_response():
        return JSONResponse(
            {"error": "Note not found."},
            status_code=HTTPStatus.NOT_FOUND,
        )
    def get_note_from_path_params(path_params) -> Note | None:
        note_id = path_params["id"]
        # Ensure the note id is a valid UUID
        if not is_valid_uuid(note_id):
            return None
        try:
            note = Note.objects.get(id=note_id)
        except (Note.DoesNotExist):
            return None
        return note
    ```

---

# Example Chart Application

Source: https://docs.canvasmedical.com/sdk/example-example_chart_app/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/example_chart_app) for this plugin on GitHub.
An example custom UI Application for the patient chart. This particular application loads the active staff user and displays some attributes about them (ex: their name), and it also loads templated HTML and JavaScript to make a REST call to a user-defined endpoint, right in the Canvas EMR.
##  SDK Features 
  - Creates a `GET` [Simple API](/sdk/handlers-simple-api-http/) endpoint that retrieves the logged in [Staff user](/sdk/data-staff/) from the event context, [renders a template](/sdk/layout-effect/#custom-html-and-django-templates), and returns HTML content
  - Creates a `POST` [Simple API](/sdk/handlers-simple-api-http/) endpoint that [creates a task](/sdk/effect-tasks/#adding-a-task)
  - Defines a custom template containing JavaScript that makes a REST call to the user-defined `POST` endpoint above
  - Adds an [Application](/sdk/handlers-applications/) effect that, on open, returns a [LaunchModalEffect](/sdk/layout-effect/#modals) in the right chart pane with content from the `GET` endpoint
##  Configuration 
These SimpleAPI endpoints use the [StaffSessionAuthMixin](/sdk/handlers-simple-api-http/#staff-session)
The `CANVAS_MANIFEST.json` file defines attributes specific to the Application, including scope (`patient_specific`) and icon image.
##  Structure 
    ```plaintext
    example_chart_app/
    ├── applications/
    │   ├── __init__.py
    │   ├── my_application.py     # Defines API endpoints and Application
    ├── assets
    |   ├──rx.png                 # Image file
    ├── templates/
    │   └── custom_ui.html        # HTML template for visualization UI
    ├── CANVAS_MANIFEST.json      # Plugin configuration
    └── README.md                 # Documentation
    ```
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "example_chart_app",
        "description": "Used to test various canvas plugins functionality",
        "url_permissions": [],
        "components": {
            "handlers": [
                {
                    "class": "example_chart_app.applications.my_application:MyApi",
                    "description": "Provides api for the application",
                    "data_access": {
                        "event": "",
                        "read": [],
                        "write": []
                    }
                }
            ],
            "applications": [
                {
                    "class": "example_chart_app.applications.my_application:MyChartApplication",
                    "name": "Example Chart App",
                    "description": "Show a custom, interactive UI in the chart",
                    "scope": "patient_specific",
                    "icon": "assets/rx.png"
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  templates/ 
###  custom-ui.html 
This is the html template called by the [`render_to_string` function](/sdk/layout-effect/#custom-html-and-django-templates) with a `logged_in_staff` object. It contains styling and custom Javascript to call the user-defined POST endpoint when a specific element is clicked.
##  applications/ 
###  my_application.py 
This file defines an application plugin for Canvas Medical using the Canvas SDK. It includes a custom application (`MyChartApplication`) and an API (`MyApi`) for rendering a modal user interface pane and handling related actions, such as adding tasks.
**MyChartApplication Class**
  - Subclasses the `Application` class from the Canvas SDK.
  - The `on_open` method is triggered when the application is opened. It retrieves the current patient's ID from `self.context`.
  - It returns a `LaunchModalEffect`, which opens a custom modal UI in the right chart pane. The URL for this modal includes the patient ID as a query parameter.
**MyApi Class**
  - Subclasses both `StaffSessionAuthMixin` and `SimpleAPI`, enabling API definition with authentication.
  - Defines two endpoints using the `@api` decorator: a GET and a POST.
**GET /custom-ui**
  - Endpoint: `/custom-ui`
  - Retrieves the logged-in staff user via the header `"canvas-logged-in-user-id"` and the Canvas SDK Staff data model (but it could retrieve any data!)
  - Renders a template (`templates/custom-ui.html`) with context including the logged-in staff and the selected patient ID.
  - Returns the rendered HTML as an `HTMLResponse` with HTTP 200 (OK) status.
**POST /add-task**
  - Endpoint: `/add-task`
  - Creates a new task for the specified patient (using `patient_id` from the posted JSON payload).
  - Sets the task to be due in 5 days from the current UTC time and sets its status to open.
  - Returns two responses:
    - The effect to add a task (which also triggers any related UI updates).
    - A JSON response with a success message and HTTP 202 (Accepted) status.
**Miscellaneous**
  - Imports various components and utilities from the Canvas SDK, such as effects for UI actions, response types, authentication mixins, and template rendering.
  - Uses the `arrow` library for time/date handling.
**Summary**
The code provides a Canvas plugin that opens a modal UI displaying custom content for a selected patient. It can also create a new patient-related task when a specific endpoint is called, handling user authentication and returning appropriate UI and API responses. The flow is tailored to staff users interacting with patient charts.
    ```python
    import arrow
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.effects.simple_api import Response, JSONResponse, HTMLResponse
    from canvas_sdk.effects.task import AddTask, TaskStatus
    from canvas_sdk.handlers.application import Application
    from canvas_sdk.handlers.simple_api import StaffSessionAuthMixin, SimpleAPI, api
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data.staff import Staff
    class MyChartApplication(Application):
        def on_open(self) -> Effect:
            patient_id = self.context['patient']['id']
            return LaunchModalEffect(
                url=f"/plugin-io/api/example_chart_app/custom-ui?patient={patient_id}",
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
            ).apply()
    class MyApi(StaffSessionAuthMixin, SimpleAPI):
        @api.get("/custom-ui")
        def custom_ui(self) -> list[Response | Effect]:
            logged_in_staff = Staff.objects.get(id=self.request.headers["canvas-logged-in-user-id"])
            context = {
                "logged_in_staff": logged_in_staff,
                "patient_id": self.request.query_params["patient"],
            }
            return [
                HTMLResponse(
                    render_to_string("templates/custom-ui.html", context),
                    status_code=HTTPStatus.OK,
                )
            ]
        @api.post("/add-task")
        def add_task(self) -> list[Response | Effect]:
            add_task = AddTask(
                title="This came from the custom patient ui.",
                patient_id=self.request.json()["patient_id"],
                due=arrow.utcnow().shift(days=5).datetime,
                status=TaskStatus.OPEN,
            )
            return [
                add_task.apply(),
                JSONResponse(
                    {"message": "Task will be created"},
                    status_code=HTTPStatus.ACCEPTED
                )
            ]
    ```
##  assets/ 
###  rx.png 
This is an image file used as the Application icon within the Canvas UI.

---

# Extend AI PDF

Source: https://docs.canvasmedical.com/sdk/example-extend_ai_pdf/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/extend_ai_pdf) for this plugin on GitHub.
##  Description 
Plugin that provides a SimpleAPI for intelligent document processing using the Extend AI client. It supports listing processors, running document extraction on PDF files, checking run status, managing stored files, and retrieving processing results. Includes a chart application that renders a form interface for PDF processing directly from the chart.
##  Configuration 
This example plugin defines the following "secrets" in the manifest file:
    ```plaintext
        "variables": [
            {"name": "ExtendAiKey", "sensitive": true}
        ],
    ```
Once defined in the `MANIFEST.json`, set the secrets for your plugin in the Admin UI of your Canvas EMR. [Read more](https://docs.canvasmedical.com/sdk/secrets/)
###  ExtendAiKey 
Your Extend AI API key.
##  CANVAS_MANIFEST.json 
    ```json
    {
      "sdk_version": "0.81.0",
      "plugin_version": "0.0.1",
      "name": "pdf_manip",
      "description": "use extent.ai to extract information from a PDF document",
      "components": {
        "handlers": [
          {
            "class": "pdf_manip.handlers.pdf_manip:PdfManip",
            "description": "PDF extractor based on extent.ai"
          }
        ],
        "applications": [
          {
            "class": "pdf_manip.handlers.pdf_form_app:PdfFormApp",
            "name": "PDF Upload",
            "description": "Extend.ai manip",
            "icon": "static/pdf_manip.png",
            "scope": "patient_specific",
            "show_in_panel": false
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [
        {"name": "ExtendAiKey", "sensitive": true}
      ],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
##  handlers/ 
###  pdf_manip.py 
**Purpose**
This code defines a SimpleAPI handler that exposes REST endpoints for processing PDF documents using the Extend AI client from the Canvas SDK.
**Class Overview**
  - The main class, `PdfManip`, extends `StaffSessionAuthMixin` and `SimpleAPI`.
  - It creates an Extend AI client using an API key stored in plugin secrets.
**Main Workflow**
  - `GET /processors` — Lists all available Extend AI processors.
  - `GET /processors/<processor_id>` — Retrieves configuration for a specific processor.
  - `POST /execute` — Starts a processor run on a document from a public S3 URL.
  - `GET /status/<run_id>` — Checks the status of a run and cleans up files if completed.
  - `GET /result/<run_id>` — Retrieves the processing result for a completed run.
  - `GET /stored_files` — Lists all files stored in Extend AI.
  - `POST /delete_files` — Deletes specified files from Extend AI storage.
**Extend AI Client Integration**
  - The `_extend_client` method creates a `Client` instance from `canvas_sdk.clients.extend_ai.libraries`.
  - Error handling uses the `RequestFailed` exception from the Extend AI client structures.
    ```python
    from datetime import datetime
    from http import HTTPStatus
    from canvas_sdk.clients.extend_ai.constants import RunStatus, VersionName
    from canvas_sdk.clients.extend_ai.libraries import Client
    from canvas_sdk.clients.extend_ai.structures import RequestFailed
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin, api
    from pdf_manip.constants.secrets import Secrets
    class PdfManip(StaffSessionAuthMixin, SimpleAPI):
        """API handler for Extend AI PDF processing operations."""
        PREFIX = None
        USER_TYPE_STAFF = "Staff"
        def _extend_client(self) -> Client:
            """Create and return a configured Extend AI client."""
            return Client(self.secrets[Secrets.extend_ai_key])
        @api.get("/processors")
        def list_processors(self) -> list[Response | Effect]:
            """Retrieve all available Extend AI processors."""
            try:
                content: list | dict = [p.to_dict() for p in self._extend_client().list_processors()]
                status_code = HTTPStatus(HTTPStatus.OK)
            except RequestFailed as e:
                content = {"information": e.message}
                status_code = HTTPStatus(e.status_code)
            return [JSONResponse(content, status_code=status_code)]
        @api.get("/processors/<processor_id>")
        def get_processor(self) -> list[Response | Effect]:
            """Retrieve the configuration for a specific processor by ID."""
            try:
                processor_id = self.request.path_params["processor_id"]
                response = self._extend_client().processor(processor_id, VersionName.DRAFT.value)
                content = response.config.to_dict()
                status_code = HTTPStatus(HTTPStatus.OK)
            except RequestFailed as e:
                content = {"information": e.message}
                status_code = HTTPStatus(e.status_code)
            return [JSONResponse(content, status_code=status_code)]
        @api.get("/result/<run_id>")
        def run_result(self) -> list[Response | Effect]:
            """Retrieve the processing result for a completed run."""
            try:
                run_id = self.request.path_params["run_id"]
                response = self._extend_client().run_status(run_id)
                if response.status == RunStatus.PROCESSED:
                    content = {"result": response.output.to_dict()}
                    status_code = HTTPStatus(HTTPStatus.OK)
                else:
                    content = {"result": response.status}
                    status_code = HTTPStatus(HTTPStatus.UNPROCESSABLE_ENTITY)
            except RequestFailed as e:
                content = {"information": e.message}
                status_code = HTTPStatus(e.status_code)
            return [JSONResponse(content, status_code=status_code)]
        @api.get("/status/<run_id>")
        def run_status(self) -> list[Response | Effect]:
            """Check the status of a processor run and clean up files if completed."""
            try:
                run_id = self.request.path_params["run_id"]
                extend_ai = self._extend_client()
                response = extend_ai.run_status(run_id)
                if response.status == RunStatus.PROCESSED:
                    for file in response.files:
                        extend_ai.delete_file(file.id)
                content = {"runId": response.id, "status": response.status.value}
                status_code = HTTPStatus(HTTPStatus.OK)
            except RequestFailed as e:
                content = {"information": e.message}
                status_code = HTTPStatus(e.status_code)
            return [JSONResponse(content, status_code=status_code)]
        @api.get("/stored_files")
        def extend_stored_files(self) -> list[Response | Effect]:
            """List all files stored in Extend AI."""
            try:
                content: list | dict = [f.to_dict() for f in self._extend_client().list_files()]
                status_code = HTTPStatus(HTTPStatus.OK)
            except RequestFailed as e:
                content = {"information": e.message}
                status_code = HTTPStatus(e.status_code)
            return [JSONResponse(content, status_code=status_code)]
        @api.post("/delete_files")
        def extend_delete_files(self) -> list[Response | Effect]:
            """Delete specified files from Extend AI storage."""
            try:
                content: list | dict = [
                    {
                        "id": file_id,
                        "deleted": self._extend_client().delete_file(file_id),
                    }
                    for file_id in self.request.json().get("fileIds") or []
                ]
                status_code = HTTPStatus(HTTPStatus.OK)
            except RequestFailed as e:
                content = {"information": e.message}
                status_code = HTTPStatus(e.status_code)
            return [JSONResponse(content, status_code=status_code)]
        @api.post("/execute")
        def run_start(self) -> list[Response | Effect]:
            """Start a processor run on a document from a public S3 URL."""
            try:
                received = self.request.json()
                aws_s3_url = received.get("fileAwsS3Url")
                processor_id = received.get("processorId")
                response = self._extend_client().run_processor(
                    processor_id=processor_id,
                    file_name=f"processed-{datetime.now().isoformat(timespec='seconds')}",
                    file_url=aws_s3_url,
                    config=None,
                )
                content = {"runId": response.id, "status": response.status.value}
                status_code = HTTPStatus(HTTPStatus.OK)
            except RequestFailed as e:
                content = {"information": e.message}
                status_code = HTTPStatus(e.status_code)
            return [JSONResponse(content, status_code=status_code)]
    ```
###  pdf_form_app.py 
**Purpose**
This code defines an Application handler that launches a modal form in the right chart pane for interacting with the Extend AI PDF processing API endpoints.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    from canvas_sdk.templates import render_to_string
    class PdfFormApp(Application):
        """Application handler that displays the PDF processing form in a modal."""
        PLUGIN_API_BASE_ROUTE = "/plugin-io/api/pdf_manip"
        def on_open(self) -> Effect:
            """Render and launch the PDF processing form modal in the right chart pane."""
            content = render_to_string(
                "templates/pdf_form.html",
                {
                    "processorsURL": f"{self.PLUGIN_API_BASE_ROUTE}/processors",
                    "statusURL": f"{self.PLUGIN_API_BASE_ROUTE}/status",
                    "executeURL": f"{self.PLUGIN_API_BASE_ROUTE}/execute",
                    "resultURL": f"{self.PLUGIN_API_BASE_ROUTE}/result",
                    "storedFilesURL": f"{self.PLUGIN_API_BASE_ROUTE}/stored_files",
                    "deleteFilesURL": f"{self.PLUGIN_API_BASE_ROUTE}/delete_files",
                },
            )
            return LaunchModalEffect(
                content=content,
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
            ).apply()
    ```

---

# LLM

Source: https://docs.canvasmedical.com/sdk/example-llm/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/llm) for this plugin on GitHub.
##  Description 
Plugin that provides a SimpleAPI for interacting with multiple LLM providers (Anthropic, Google, OpenAI) through the Canvas SDK's unified LLM client. It supports image analysis with structured JSON output, multi-turn chat conversations, and file content analysis. Includes a chart application that renders a form interface for LLM interactions directly from the chart.
##  Configuration 
This example plugin defines the following "secrets" in the manifest file:
    ```plaintext
        "variables": [
            {"name": "AnthropicKey", "sensitive": true},
            {"name": "GoogleKey", "sensitive": true},
            {"name": "OpenaiKey", "sensitive": true}
        ],
    ```
Once defined in the `MANIFEST.json`, set the secrets for your plugin in the Admin UI of your Canvas EMR. [Read more](https://docs.canvasmedical.com/sdk/secrets/)
###  AnthropicKey 
Your [Anthropic API key](https://console.anthropic.com/settings/keys).
###  GoogleKey 
Your [Google AI API key](https://aistudio.google.com/apikey).
###  OpenaiKey 
Your [OpenAI API key](https://platform.openai.com/api-keys).
##  CANVAS_MANIFEST.json 
    ```json
    {
      "sdk_version": "0.81.0",
      "plugin_version": "0.0.1",
      "name": "llm_manip",
      "description": "use LLM to interact with the user",
      "components": {
        "handlers": [
          {
            "class": "llm_manip.handlers.llm_manip:LlmManip",
            "description": "LLM communication wrapper"
          }
        ],
        "applications": [
          {
            "class": "llm_manip.handlers.llm_form_app:LlmFormApp",
            "name": "LLM Interactions",
            "description": "LLM interactions with the user",
            "icon": "static/llm_manip.png",
            "scope": "patient_specific",
            "show_in_panel": false
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [
        {"name": "AnthropicKey", "sensitive": true},
        {"name": "GoogleKey", "sensitive": true},
        {"name": "OpenaiKey", "sensitive": true}
      ],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
##  handlers/ 
###  llm_manip.py 
**Purpose**
This code defines a SimpleAPI handler that exposes REST endpoints for interacting with LLM providers using the Canvas SDK's unified LLM client.
**Class Overview**
  - The main class, `LlmManip`, extends `SimpleAPI`.
  - It supports three LLM providers: Anthropic (Claude), Google (Gemini), and OpenAI (GPT Models).
  - It demonstrates structured JSON output using Pydantic models (`LlmResponse`, `Result`).
**Main Workflow**
  - `POST /animals_count/<llm_provider>` — Analyzes an image URL to count animals using LLM vision capabilities with structured JSON output.
  - `POST /chat/<llm_provider>` — Processes a multi-turn chat conversation with system, user, and model roles.
  - `POST /file/<llm_provider>` — Analyzes uploaded file content using multipart form data.
**LLM Client Integration**
  - The `_llm_client` method creates provider-specific clients (`LlmAnthropic`, `LlmGoogle`, `LlmOpenai`) with their respective settings classes.
  - Structured output is configured via `client.set_schema()` with Pydantic models extending `BaseModelLlmJson`.
  - File attachments are supported via `LlmFileUrl` for URLs and `FileContent` for binary content.
    ```python
    import base64
    from http import HTTPStatus
    from pydantic import Field
    from canvas_sdk.clients.llms.constants import FileType
    from canvas_sdk.clients.llms.libraries import LlmAnthropic, LlmApi, LlmGoogle, LlmOpenai
    from canvas_sdk.clients.llms.structures import BaseModelLlmJson, FileContent, LlmFileUrl
    from canvas_sdk.clients.llms.structures.settings import (
        LlmSettingsAnthropic,
        LlmSettingsGemini,
        LlmSettingsGpt4,
    )
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, PlainTextResponse, Response
    from canvas_sdk.handlers.simple_api import Credentials, SimpleAPI, api
    from canvas_sdk.handlers.simple_api.api import FileFormPart, StringFormPart
    from llm_manip.constants.secrets import Secrets
    class Result(BaseModelLlmJson):
        """Structured response model for animal counting results."""
        count_dogs: int = Field(description="the number of dogs")
        count_cats: int = Field(description="the number of cats")
        count_total: int = Field(description="the number of animals")
    class LlmResponse(BaseModelLlmJson):
        """Structured response model for LLM animal analysis with optional result."""
        comment: str = Field(description="the comment")
        result: Result | None
    class LlmManip(SimpleAPI):
        """Simple API handler for LLM-based image analysis and chat operations."""
        PREFIX = None
        LLM_ANTHROPIC = 0
        LLM_GOOGLE = 1
        LLM_OPENAI = 2
        def authenticate(self, credentials: Credentials) -> bool:
            """Authenticate API requests."""
            return True
        def _llm_client(self, provider: int) -> LlmApi:
            """Create and configure a LLM client with credentials from secrets."""
            if provider == self.LLM_ANTHROPIC:
                return LlmAnthropic(
                    LlmSettingsAnthropic(
                        api_key=self.secrets[Secrets.anthropic_key],
                        model="claude-sonnet-4-5",
                        temperature=1.0,
                        max_tokens=8192,
                    )
                )
            elif provider == self.LLM_GOOGLE:
                return (
                    LlmGoogle(
                        LlmSettingsGemini(
                            api_key=self.secrets[Secrets.anthropic_key],
                            model="models/gemini-2.5-flash",
                            temperature=1.0,
                        )
                    ),
                )
            else:
                return LlmOpenai(
                    LlmSettingsGpt4(
                        api_key=self.secrets[Secrets.openai_key],
                        model="gpt-4o",
                        temperature=2.0,
                    )
                )
        @api.post("/animals_count/<llm_provider>")
        def animals_count(self) -> list[Response | Effect]:
            """Analyze an image URL to count animals using LLM vision capabilities."""
            client = self._llm_client(self.request.path_params["llm_provider"])
            url = self.request.json().get("url")
            if not url:
                url = "https://images.unsplash.com/photo-1563460716037-460a3ad24ba9?w=125"
            client.set_schema(LlmResponse)
            client.set_system_prompt(
                ["Your task is to read the pictures provided by the user and count the animals in it."]
            )
            client.set_user_prompt(["Identify the content of the provided picture."])
            client.add_url_file(LlmFileUrl(url=url, type=FileType.IMAGE))
            responses = client.attempt_requests(attempts=2)
            content = [r.to_dict() for r in responses]
            return [JSONResponse(content, status_code=HTTPStatus(HTTPStatus.OK))]
        @api.post("/chat/<llm_provider>")
        def chat(self) -> list[Response | Effect]:
            """Process a multi-turn chat conversation with the LLM."""
            client = self._llm_client(self.request.path_params["llm_provider"])
            for turn in self.request.json():
                if not isinstance(turn, dict):
                    continue
                if turn.get("role") == "system":
                    client.set_system_prompt([turn.get("prompt", "")])
                elif turn.get("role") == "user":
                    client.set_user_prompt([turn.get("prompt", "")])
                else:
                    client.set_model_prompt([turn.get("prompt", "")])
            response = client.attempt_requests(attempts=1)[0]
            return [PlainTextResponse(response.response, status_code=response.code)]
        @api.post("/file/<llm_provider>")
        def file(self) -> list[Response | Effect]:
            """Analyze file content using LLM."""
            content = b""
            mime_type = ""
            user_input = ""
            form_data = self.request.form_data()
            if "file" in form_data and isinstance(form_data["file"], FileFormPart):
                content = form_data["file"].content
                mime_type = form_data["file"].content_type
            if "input" in form_data and isinstance(form_data["input"], StringFormPart):
                user_input = form_data["input"].value
            if not (content and mime_type and user_input):
                return [PlainTextResponse("nothing to do", status_code=HTTPStatus(HTTPStatus.OK))]
            client = self._llm_client(self.request.path_params["llm_provider"])
            file = FileContent(
                mime_type=mime_type,
                content=base64.b64encode(content),
                size=len(content),
            )
            client.file_contents.append(file)
            client.set_system_prompt(["Answer to the question about the file, clearly and concisely."])
            client.set_user_prompt([user_input or "what is in the file?"])
            response = client.attempt_requests(attempts=1)[0]
            return [PlainTextResponse(response.response, status_code=response.code)]
    ```
###  llm_form_app.py 
**Purpose**
This code defines an Application handler that launches a modal form in the right chart pane for interacting with the LLM API endpoints.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    from canvas_sdk.templates import render_to_string
    class LlmFormApp(Application):
        """Application handler for launching the LLM interaction form interface."""
        PLUGIN_API_BASE_ROUTE = "/plugin-io/api/llm_manip"
        def on_open(self) -> Effect:
            """Render and launch the LLM interaction modal form."""
            content = render_to_string(
                "templates/llm_form.html",
                {
                    "animalsCountURL": f"{self.PLUGIN_API_BASE_ROUTE}/animals_count",
                    "chatURL": f"{self.PLUGIN_API_BASE_ROUTE}/chat",
                    "fileURL": f"{self.PLUGIN_API_BASE_ROUTE}/file",
                },
            )
            return LaunchModalEffect(
                content=content,
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
            ).apply()
    ```

---

# Patient Creation Platform Sync

Source: https://docs.canvasmedical.com/sdk/example-patient_creation_platform_sync/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/example_patient_sync) for this plugin on GitHub.
##  Description 
An example of bidirectional patient creation between Canvas and a 3rd party system.
At a high level, this plugin:
  1. Adds an API endpoint to which the external system can POST a new patient object with a given system_id, which creates a patient in Canvas with an external_identifier.
  2. Configures a webhook for the PATIENT_CREATED event to automatically synchronize patient data. When a patient is created in Canvas, the webhook triggers an update (or creation) in the external system via its patient GET/POST/PATCH API, ensuring the Canvas ID is always included.
##  Sample CURL request 
Once the API endpoint POST action is created, test it is working with the following CURL command (or use a popular GUI like Postman or Bruno). Replace "training" with your Canvas instance name:
    ```plaintext
    curl --request POST \
      --url https://training.canvasmedical.com/plugin-io/api/example_patient_sync/patients \
      --header 'content-type: application/json' \
      --header 'authorization: 97f2a0f033666d29ff09ee42b3afd7e4'
      --data '{
      "firstName": "Alice",
      "lastName": "Example",
      "sexAtBirth": "F",
      "dateOfBirth": "1980-02-22",
      "partnerId": "pat_12345678"
    }'
    ```
##  Defining and Setting Secrets 
This example plugin defines four "secrets" in the manifest file:
    ```plaintext
        "variables": [
            {"name": "PARTNER_URL_BASE", "sensitive": false},
            {"name": "PARTNER_API_BASE_URL", "sensitive": false},
            {"name": "PARTNER_SECRET_API_KEY", "sensitive": true},
            {"name": "simpleapi-api-key", "sensitive": true}
        ],
    ```
Once defined in the `MANIFEST.json`, set the secrets for your plugin in the Admin UI of your Canvas EMR. [Read more](https://docs.canvasmedical.com/sdk/secrets/)
###  PARTNER_URL_BASE 
This string value will be set as the "system" in the patient external identifier that is created. A patient can have many external identifiers, so make sure this is a unique value that is searchable to find their external ID in the future. [Read more](https://docs.canvasmedical.com/sdk/effect-create-patient-external-identifier/)
###  PARTNER_API_BASE_URL 
This string value will be used when making REST API calls to a partner system (to create or update a patient record, for example). It may or may not be the same as the PARTNER_URL_BASE.
###  PARTNER_SECRET_API_KEY 
If accessing a partner API requires authorization, this can define the auth secret to enable the API handshake.
###  simpleapi-api-key 
This is the authorization needed for Canvas when using APIKeyAuthMixin. [Read more](https://docs.canvasmedical.com/sdk/handlers-simple-api-http/#session)
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.40.0",
        "plugin_version": "0.0.1",
        "name": "example_patient_sync",
        "description": "Example bidirectional patient synchronization between Canvas and a 3rd party system",
        "components": {
            "handlers": [
                {
                    "class": "example_patient_sync.handlers.patient_sync:PatientSync",
                    "description": "Create or update patients in an external system based on Canvas events",
                },
                {
                    "class": "example_patient_sync.routes.patient_create_api:PatientCreateApi",
                    "description": "Create a patient in Canvas when a user is created in an external system",
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [
            {"name": "PARTNER_URL_BASE", "sensitive": false},
            {"name": "PARTNER_API_BASE_URL", "sensitive": false},
            {"name": "PARTNER_SECRET_API_KEY", "sensitive": true},
            {"name": "simpleapi-api-key", "sensitive": true}
        ],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  routes/ 
###  patient_create_api.py 
**Purpose**
The code defines an HTTP API endpoint for creating new patient records in Canvas from a third-party system. It authenticates requests using an API key and expects data in JSON format.
**Authentication**
The endpoint uses APIKeyAuthMixin, which requires clients to provide a valid API key in the request headers for authorization.
**Endpoint Details**
  - **Route:** POST /patients
  - **Description:** Accepts and processes patient creation requests sent by external systems.
**Request Handling**
  - Expects a JSON body describing the patient. If the JSON body is not a dictionary, returns a "400 Bad Request".
  - Extracts and processes the following fields from the request:
    - `firstName`: Patient's first name.
    - `lastName`: Patient's last name.
    - `dateOfBirth`: Patient's date of birth, parsed and converted to a date object.
    - `sexAtBirth`: Patient's sex at birth; attempts to standardize and map to one of the PersonSex enum values (`SEX_FEMALE`, `SEX_MALE`, `SEX_OTHER`, `SEX_UNKNOWN`). Unrecognized values are ignored.
    - `partnerId`: An external identifier for the patient, which is combined with a secret value (`PARTNER_URL_BASE`) to create a unique identifier object.
**Patient Creation**
  - Constructs a Patient object with the collected and parsed data.
  - Attaches the external identifier from the requesting system.
**Response**
  - Issues two actions in its response list:
    - Requests the creation of the Patient record (an Effect for persistence in Canvas).
    - Returns a JSON response (HTTP 202 Accepted) containing the external identifier information (system and value), indicating the request was accepted.
**Error Handling**
  - If the request body is not valid JSON or not a dictionary, the endpoint immediately returns a 400 Bad Request with an error message.
**Dependencies**
  - Relies on the Canvas SDK for authentication, response creation, effect handling, and data models.
  - Uses the arrow library for robust date parsing.
    ```python
    from http import HTTPStatus
    from typing import cast
    import arrow
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient import Patient, PatientExternalIdentifier
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPI, api
    from canvas_sdk.v1.data.common import PersonSex
    # Authentication is handled by the APIKeyAuthMixin, which checks the API key in the request headers
    # https://docs.canvasmedical.com/sdk/handlers-simple-api-http/#api-key-1
    class PatientCreateApi(APIKeyAuthMixin, SimpleAPI):
        """API endpoint for use by third-party system to create patients in Canvas when that system is the point of origination for that patient record."""
        # Docs: https://docs.canvasmedical.com/sdk/handlers-simple-api-http/
        # POST https://<instance-name>.canvasmedical.com/plugin-io/api/example_patient_sync/patients
        @api.post("/patients")
        def post(self) -> list[Response | Effect]:
            """Handle POST requests for patient sync."""
            json_body = self.request.json()
            if not isinstance(json_body, dict):
                return [
                    JSONResponse(
                        content="Invalid JSON body.", status_code=HTTPStatus.BAD_REQUEST
                    ).apply()
                ]
            birthdate = None
            date_of_birth_str = json_body.get("dateOfBirth")
            if isinstance(date_of_birth_str, str) and date_of_birth_str:
                birthdate = arrow.get(date_of_birth_str).date()
            sex_at_birth = None
            sex_at_birth_str = json_body.get("sexAtBirth")
            if sex_at_birth_str:
                s = cast(str, sex_at_birth_str).strip().upper()
                if s in ("F", "FEMALE"):
                    sex_at_birth = PersonSex.SEX_FEMALE
                elif s in ("M", "MALE"):
                    sex_at_birth = PersonSex.SEX_MALE
                elif s in ("O", "OTHER"):
                    sex_at_birth = PersonSex.SEX_OTHER
                elif s in ("U", "UNKNOWN"):
                    sex_at_birth = PersonSex.SEX_UNKNOWN
                else:
                    sex_at_birth = None
            partner_id = str(json_body.get("partnerId"))
            external_id = PatientExternalIdentifier(
                system=self.secrets['PARTNER_URL_BASE'],
                value=partner_id,
            )
            patient = Patient(
                birthdate=birthdate,
                first_name=str(json_body.get("firstName")),
                last_name=str(json_body.get("lastName")),
                sex_at_birth=sex_at_birth,
                external_identifiers=[external_id],
            )
            response = {"external_identifier": {"system": self.secrets['PARTNER_URL_BASE'], "value": partner_id}}
            return [
                patient.create(),
                JSONResponse(content=response, status_code=HTTPStatus.ACCEPTED).apply(),
            ]
    ```
##  handlers/ 
###  patient_sync.py 
**Summary**
This file defines a synchronization handler for patient data between the Canvas Medical platform and an external partner system. It listens for the event when a patient is created on Canvas and then ensures that this patient also exists (and is linked via an external identifier) in the partner system. The handler manages bidirectional lookup and updates of patient IDs between the two systems.
**Details of Operation**
  - The core class, `PatientSync`, inherits from `BaseHandler` and is triggered by the `PATIENT_CREATED` event in Canvas.
  - It uses configuration secrets and environment variables to determine endpoints, authentication headers, and other partner-specific parameters.
  - When a new patient is created in Canvas, the handler:
    1. Checks if the patient already has an external identifier linking them to the partner system.
    2. If not, attempts to look up the patient in the partner system using the Canvas patient ID by issuing a GET request.
    3. If an existing patient ID is found in the partner system, or after determining a new patient needs to be created, it prepares a payload with patient details.
    4. Issues a POST request to the partner API to either create or update the patient there.
    5. If creating, the handler expects the partner system to return the newly created patient's external ID.
    6. Handles duplicate creation attempts (HTTP 409) by simply returning without making changes.
    7. When a new external identifier is obtained, triggers an Effect to update the Canvas patient record with this identifier.
**Technical Implementation**
  - Secrets such as API keys and base URLs are used for secure access and configuration.
  - The handler functions as a stateless, event-driven adapter to maintain patient cross-system consistency.
  - HTTP request functionality is abstracted via Canvas SDK utilities.
  - Effects (a pattern used in Canvas plugins) are queued to perform changes in Canvas asynchronously and safely.
  - Logging is imported but not shown in use in the provided code.
**Key Methods**
  - `lookup_external_id_by_system_url`: Searches Canvas patient external identifiers for the partner system's record.
  - `get_patient_from_system_api`: Fetches patient details from the external partner via GET request.
  - `compute`: Main workflow coordinating the above logic, handling deduplication, updates, and creation logic for patients in both systems.
**Error and Edge Cases**
  - Handles the situation where the partner system returns a duplicate on creation.
  - Deals with missing IDs by attempting lookups and only initiating creation when necessary.
  - Only updates Canvas when a new cross-system ID must be set.
**Purpose**
This plugin component ensures that every patient created in Canvas is also represented in a connected partner system, with persistent, synchronized external identifiers to enable cross-platform interoperability and data consistency.
    ```python
    from typing import Any
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient import CreatePatientExternalIdentifier
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.utils import Http
    from canvas_sdk.v1.data.patient import Patient
    from logger import log
    class PatientSync(BaseHandler):
        """Handler for synchronizing patient data between systems."""
        RESPONDS_TO = [
            EventType.Name(EventType.PATIENT_CREATED),
        ]
        @property
        def partner_url_base(self) -> str:
            """Return the base URL for the external partner platform."""
            return self.secrets["PARTNER_URL_BASE"]
        def partner_api_base_url(self) -> str:
            """Return the base URL for the external partner API."""
            return self.secrets["PARTNER_API_BASE_URL"]
        @property
        def partner_request_headers(self) -> dict[str, str]:
            """Return the request headers for external partner API requests."""
            partner_secret_api_key = self.secrets["PARTNER_SECRET_API_KEY"]
            return {"X-API-Key": partner_secret_api_key}
        @property
        def partner_patient_metadata(self) -> Any:
            """Return metadata for creation of the patient on external partner platform."""
            metadata = {"canvasPatientId": self.target}
            subdomain = self.environment["CUSTOMER_IDENTIFIER"]
            canvas_url = f"https://{subdomain}.canvasmedical.com"
            # This sets the canvas URL for the patient in the partner platform metadata
            # Combined with the canvasPatientId, this allows the partner platform to link back to the patient in Canvas
            metadata["canvasUrl"] = canvas_url
            return metadata
        def lookup_external_id_by_system_url(self, canvas_patient: Patient, system: str) -> str | None:
            """Get the system ID for a given patient and system from Canvas."""
            # If the patient already has a external identifier for the partner platform, identified by a matching system url, use the first one
            return (
                canvas_patient.external_identifiers.filter(system=system)
                .values_list("value", flat=True)
                .first()
            )
        def get_patient_from_system_api(self, canvas_patient_id: str) -> Any:
            """Look up a patient in the external system."""
            http = Http()
            return http.get(
                f"{self.partner_api_base_url}/patients/v2/{canvas_patient_id}",
                headers=self.partner_request_headers,
            )
        def compute(self) -> list[Effect]:
            """Compute the sync actions for the patient."""
            canvas_patient_id = self.target
            http = Http()
            canvas_patient = Patient.objects.get(id=canvas_patient_id)
            # by default assume we don't yet have a system patient ID
            # and that we need to update the patient in Canvas to add one
            system_patient_id = self.lookup_external_id_by_system_url(canvas_patient, self.partner_url_base)
            update_patient_external_identifier = system_patient_id is None
            # Here we check if the patient already has an external ID in Canvas for the partner platform
            if not system_patient_id:
                # Get the system external ID by making a GET request to the partner platform
                system_patient = self.get_patient_from_system_api(canvas_patient_id)
                system_patient_id = (
                    system_patient.json()["id"] if system_patient.status_code == 200 else None
                )
            # Great, now we know if the patient is assigned a system external ID with the partner
            # platform, and if we need to update it. At this point the system_patient_id can be 3 possible values:
            # 1. value we already had stored in Canvas in an external identifier,
            # 2. value we just got from our partner GET API lookup, or
            # 3. None
            # And we have a true/false call to action telling us if we need to add
            # an external identifier to our Canvas patient: `update_patient_external_identifier`
            # Generate the payload for creating or updating the patient in partner platform API
            partner_payload = {
                "externalId": canvas_patient.id,
                "firstName": canvas_patient.first_name,
                "lastName": canvas_patient.last_name,
                "dateOfBirth": canvas_patient.birth_date.isoformat(),
            }
            base_request_url = f"{self.partner_api_base_url}/patients/v2"
            # If we have a patient's partner external id, we know this is an update, so we'll append it to the request URL
            request_url = (
                f"{base_request_url}/{system_patient_id}" if system_patient_id else base_request_url
            )
            resp = http.post(request_url, json=partner_payload, headers=self.partner_request_headers)
            # If your system's API returns the ID of the newly created record,
            # grab it from the response so we can add it to the Canvas patient record
            if system_patient_id is None:
                system_patient_id = resp.json().get("id")
            duplicate_patient_attempt = resp.status_code == 409
            if duplicate_patient_attempt:
                # If your system's API can let you know when a duplicate record was attempted to be added,
                # you can use that information to return early here.
                return []
            elif update_patient_external_identifier:
                # Queue up an effect to update the patient in Canvas and add the external identifier
                external_id = CreatePatientExternalIdentifier(
                    patient_id=canvas_patient.id,
                    system=self.partner_url_base,
                    value=str(system_patient_id)
                )
                return [external_id.create()]
            else:
                return [] # Done!
    ```

---

# Group Items in Patient Chart

Source: https://docs.canvasmedical.com/sdk/example-patient_summary_chart_groups/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/patient_summary_chart_groups) for this plugin on GitHub.
A plugin that groups Psychiatry conditions and medications in the patient summary chart.
##  SDK Features 
  - Responds to `PATIENT_CHART__CONDITIONS` and `PATIENT_CHART__MEDICATIONS` [events](/sdk/events/#patient-chart-configuration)
  - Loads the patient conditions and medications using event context
  - Iterates through conditions to retrieve the ICD10 CodeSystem and assigns to a [Group effect](/sdk/patient-chart-group-effect/#group) list of items
  - Iterates through medications to find an RxNorm match on a list of plugin-defined medication codes and assigns to a [Group effect](/sdk/patient-chart-group-effect/#group) list of items
  - Returns the [`PatientChartGroup` effect](/sdk/patient-chart-group-effect/) with `.apply()` called
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "patient_summary_chart_groups",
        "description": "A plugin that groups Psychiatry conditions and medications in the patient summary chart.",
        "components": {
            "handlers": [
                {
                    "class": "patient_summary_chart_groups.handlers.my_handler:Conditions",
                    "description": "A handler that groups Psychiatry conditions"
                },
                {
                    "class": "patient_summary_chart_groups.handlers.my_handler:Medications",
                    "description": "A handler that groups Psychiatry medications"
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  handlers/ 
###  my_handler.py 
This file defines two custom handlers, `Conditions` and `Medications`, using the Canvas SDK. These handlers listen for specific events related to a patient's medical chart and group relevant diagnoses or medications into a "Psychiatry" category, returning these as effects for further processing or display in the Canvas UI.
**Section:`Conditions` Handler**
  - Inherits from `BaseHandler`.
  - Listens to the `EventType.PATIENT_CHART__CONDITIONS` event (triggered when a patient's chart conditions are accessed).
  - For each condition in the event context, it looks at the `codings` list:
    - If the coding system is ICD-10 (`CodeSystems.ICD10`) and the code falls within the ICD-10 psychiatry range ("F01" to "F99") or starts with "R45." (indicating certain psychiatric symptoms), the condition is added to a group named "Psychiatry".
  - The resulting group is returned using a `PatientChartGroup` effect, applied to be consumed by other parts of the platform (such as UI rendering).
**Section:`Medications` Handler**
  - Inherits from `BaseHandler`.
  - Listens to the `EventType.PATIENT_CHART__MEDICATIONS` event (triggered when a patient's medication list is accessed).
  - Maintains an explicit list of RxNorm codes (`medication_codes`) representing psychiatric or relevant medications.
  - For each medication in the event context, it looks at the `codings` list:
    - If the coding system is RxNorm (`CodeSystems.RXNORM`) and the code (converted to integer) is in the handler's medication list, the medication is added to the "Psychiatry" group.
  - The resulting group is returned using a `PatientChartGroup` effect, again allowing psychiatric medications to be grouped in the UI.
**Section: Canvas SDK Constructs Used**
  - **Events:** Listens for specific event types (patient chart conditions or medications).
  - **Effects:** Returns grouping instructions as `PatientChartGroup` effects, making downstream processing or UI changes possible.
  - **Grouping:** Uses the `Group` object to label and prioritize (with `priority=100`) psychiatric items, and the `PatientChartGroup` to wrap effect logic for patient chart groupings.
**Section: Implementation Details**
  - The handlers use dictionary storage for groups but always construct only a single "Psychiatry" group.
  - ICD-10 and RxNorm code checks strictly conform to predefined domain ranges or explicit code lists.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.group import Group
    from canvas_sdk.effects.patient_chart_group import PatientChartGroup
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.commands.constants import CodeSystems
    class Conditions(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART__CONDITIONS)
        def compute(self) -> list[Effect]:
            groups: dict[str, Group] = {}
            groups.setdefault("Psychiatry", Group(priority=100, items=[], name="Psychiatry"))
            for condition in self.event.context:
               for coding in condition["codings"]:
                   if coding["system"] == CodeSystems.ICD10 and ("F01" <= coding["code"] <= "F99" or coding["code"].startswith("R45.")):
                       groups["Psychiatry"].items.append(condition)
                       break
            return [PatientChartGroup(items=groups).apply()]
    class Medications(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART__MEDICATIONS)
        medication_codes = [
            70223, 725, 17941, 1359, 89781, 314517, 1422, 42347, 1841, 3007, 2591497, 62174, 22656, 352372, 3288, 1598,
            3389, 3415, 3416, 3417, 3554, 10402, 11636, 1653781, 4024, 14584, 4328, 325526, 4850, 6130, 6373, 700810, 6664,
            6694, 6782, 6816, 6901, 7243, 326374, 31994, 7781, 2387302, 7966, 33272, 8133, 8150, 8152, 8702, 8704, 9260,
            36514, 1547099, 10689, 11289, 68503, 3920, 4457, 237005, 6378, 6754, 7814, 8001, 9601, 3264, 7242, 7895, 237099,
            203223, 3554, 2626143, 6711, 7407, 314875, 11256, 82819, 161203, 16735, 272, 2557217, 237099, 596, 704, 719,
            722, 725, 17381, 89013, 1673265, 641465, 784649, 38400, 1291301, 1292, 1373, 2690627, 2176312, 2121777, 1658314,
            1749, 19759, 19777, 1819, 42347, 1827, 477631, 19874, 2002, 1667655, 2296, 2356, 2372, 2373, 2403, 2406, 2556,
            2597, 2598, 2599, 2603, 2353, 2622, 2626, 3013, 2591497, 62174, 3247, 3251, 734064, 352372, 3288, 3322, 3332,
            91235, 3403, 3407, 203223, 3498, 3554, 2687966, 135447, 3634, 3637, 3638, 3642, 3648, 72625, 3755, 4024, 321988,
            2119365, 4077, 461016, 4118, 24474, 4328, 1665509, 4457, 4460, 4493, 4495, 4496, 4501, 4507, 42355, 25480, 4637,
            2672253, 325526, 4903, 40114, 26412, 5093, 2267703, 5553, 73178, 5691, 5975, 262150, 6011, 6026, 285228, 28439,
            2626143, 2272403, 237005, 1433212, 700810, 6448, 746070, 42351, 52105, 1546376, 28863, 6470, 28894, 6475,
            2275602, 1040028, 52356, 6646, 6673, 6680, 6711, 6719, 6760, 6779, 6813, 6816, 6823, 6852, 6901, 6904, 6910,
            6960, 588250, 15996, 30125, 7019, 31479, 7242, 7243, 31565, 7407, 7440, 7486, 3155, 7531, 61381, 26225, 1370971,
            7781, 2387302, 679314, 7895, 7909, 32937, 7966, 7974, 8042, 8047, 8766, 8076, 8123, 8156, 8331, 33739, 8338,
            8348, 2197878, 34345, 746741, 3143, 8627, 8701, 8704, 8742, 8770, 8782, 8787, 8825, 8826, 8886, 35185, 51272,
            9100, 596205, 60842, 9260, 35636, 183379, 616739, 2559612, 9624, 9639, 2562176, 41996, 36437, 36676, 1547099,
            10318, 1490468, 10355, 10390, 37985, 10437, 10454, 10464, 38077, 10502, 10510, 31914, 38260, 314875, 38365,
            38404, 10734, 10737, 10767, 1314420, 10800, 10804, 10805, 10834, 10898, 21406, 11017, 1665222, 253206, 40254,
            39786, 1086769, 11256, 1455099, 2694828, 220982, 74667, 115698, 39993, 2669905
        ]
        def compute(self) -> list[Effect]:
            groups: dict[str, Group] = {}
            groups.setdefault("Psychiatry", Group(priority=100, items=[], name="Psychiatry"))
            for medication in self.event.context:
                for coding in medication["codings"]:
                    if coding["system"] == CodeSystems.RXNORM and int(coding["code"]) in self.medication_codes:
                        groups["Psychiatry"].items.append(medication)
                        break
            return [PatientChartGroup(items=groups).apply()]
    ```
##  Customize 
  - The handler is extensible: additional groups or more refined code logic could be added in the future.   

---

# PayTheory Payment Processor

Source: https://docs.canvasmedical.com/sdk/example-paytheory_payment_processor/

> **Note:** [View the source](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/paytheory-payment-processor) for this plugin on GitHub.
This Canvas EMR plugin integrates [Pay Theory](https://paytheory.com) as a custom credit card [payment processor](/sdk/handlers-payment-processors/), letting Canvas collect payments and manage a patient's saved cards through a third-party provider instead of the built-in Stripe integration.
##  SDK Features 
  - Extends the [`CardPaymentProcessor`](/sdk/handlers-payment-processors/#cardpaymentprocessor) handler
  - Responds to the [`REVENUE__PAYMENT_PROCESSOR__*` events](/sdk/events/#payment-processor-events)
  - Renders tokenization forms with the [`PaymentProcessorForm`](/sdk/payment-processor-effect/#paymentprocessorform) effect and [Django templates](/sdk/layout-effect/#custom-html-and-django-templates)
  - Charges cards and returns a [`CardTransaction`](/sdk/payment-processor-effect/#cardtransaction) effect
  - Lists, adds, and removes saved cards with the [`PaymentMethod`](/sdk/payment-processor-effect/#paymentmethod), [`AddPaymentMethodResponse`](/sdk/payment-processor-effect/#addpaymentmethodresponse), and [`RemovePaymentMethodResponse`](/sdk/payment-processor-effect/#removepaymentmethodresponse) effects
  - Reads configuration from plugin [variables](/sdk/secrets/) and declares `url_permissions` for the Pay Theory JS SDK
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "paytheory_payment_processor",
        "description": "PayTheory credit card payment processor integration",
        "url_permissions": [
            {
                "url": "https://*.sdk.paytheory.com/index.js",
                "permissions": ["SCRIPTS"]
            }
        ],
        "components": {
            "handlers": [
                {
                    "class": "paytheory_payment_processor.handlers.paytheory_payment_processor:PayTheoryPaymentProcessor",
                    "description": "Handles credit card payments, tokenization, and payment method management via PayTheory",
                    "data_access": {
                        "event": "",
                        "read": [],
                        "write": []
                    }
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [
            {"name": "paytheory_merchant_id", "sensitive": true},
            {"name": "paytheory_public_key"},
            {"name": "paytheory_secret_key", "sensitive": true},
            {"name": "paytheory_partner"},
            {"name": "paytheory_environment"}
        ],
        "tags": {},
        "references": [],
        "license": "",
        "readme": "./README.md"
    }
    ```
The `url_permissions` above are abbreviated — the full manifest lists every Pay Theory SDK, token-service, and tags-static URL across the production, sandbox, and lab environments.
##  handlers/ 
###  paytheory_payment_processor.py 
**Purpose and Functionality**
This file defines `PayTheoryPaymentProcessor`, a subclass of `CardPaymentProcessor`. It implements the methods Canvas calls throughout a payment workflow: rendering the tokenization forms, charging a card, and listing/adding/removing a patient's saved cards. Card data is tokenized client-side by Pay Theory's JS SDK, so the plugin never handles raw card numbers.
**Core Logic**
  - `payment_form` / `add_card_form` render the Pay Theory JS SDK form (via a Django template) for paying or saving a card.
  - `charge` sends the tokenized payment method to Pay Theory's GraphQL API and maps the result onto a `CardTransaction`, treating `PENDING`/`SETTLED`/`SUCCESS`/`SUCCEEDED` statuses as successful.
  - `payment_methods` maps a patient to a Pay Theory payor (via `canvas_patient_id` metadata) and returns their saved cards as `PaymentMethod` effects.
  - `add_payment_method` / `remove_payment_method` save and disable cards for the patient's payor.
    ```python
    from decimal import Decimal
    from typing import Any
    from canvas_sdk.effects.payment_processor import (
        AddPaymentMethodResponse,
        CardTransaction,
        PaymentMethod,
        PaymentProcessorForm,
        RemovePaymentMethodResponse,
    )
    from canvas_sdk.handlers.payment_processors.card import CardPaymentProcessor
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Patient
    class PayTheoryPaymentProcessor(CardPaymentProcessor):
        """Custom payment processor for handling credit card payments with PayTheory."""
        def payment_form(self, patient: Patient | None = None) -> PaymentProcessorForm:
            content = render_to_string(
                "templates/form.html",
                {
                    "intent": self.PaymentIntent.PAY,
                    "public_api_key": self.public_api_key,
                    "sdk_url": self.sdk_url,
                },
            )
            return PaymentProcessorForm(content=content, intent=self.PaymentIntent.PAY)
        def charge(
            self, amount: Decimal, token: str, patient: Patient | None = None, **kwargs: Any
        ) -> CardTransaction:
            transaction = self.api.create_transaction(
                TransactionInput(payment_method_id=token, amount=amount)
            )
            status = (transaction.get("status") or "").upper()
            return CardTransaction(
                success=status in SUCCESS_STATUSES,
                transaction_id=transaction["transaction_id"],
                api_response=transaction,
            )
        def payment_methods(self, patient: Patient | None = None) -> list[PaymentMethod]:
            if not patient:
                return []
            payor_id = self.get_or_create_payor_id(patient)
            if not payor_id:
                return []
            return [self._to_payment_method(m) for m in self.api.get_payment_methods(payor_id=payor_id)]
        def add_payment_method(
            self, token: str, patient: Patient, **kwargs: Any
        ) -> AddPaymentMethodResponse:
            return AddPaymentMethodResponse(success=True)
        def remove_payment_method(self, token: str, patient: Patient) -> RemovePaymentMethodResponse:
            result = self.api.disable_payment_method(payment_method_id=token)
            return RemovePaymentMethodResponse(success=result)
    ```
The excerpt above is abridged; see the [source on GitHub](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/paytheory-payment-processor) for the full implementation, the Pay Theory API client, and the form template.

---

# Launch an Application from Patient Portal

Source: https://docs.canvasmedical.com/sdk/example-portal-customization-launch_application/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/example_patient_portal_page) for this plugin on GitHub.
This plugin demonstrates how to embed custom patient facing content and tools to the Canvas patient portal. It provides an example of how to expose new patient-facing content or features, such as educational materials, forms, or interactive tools. On open, the plugin can launch an application and return effects to update the portal UI or patient data as needed.
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "example_patient_portal_page",
        "description": "Edit the description in CANVAS_MANIFEST.json",
        "url_permissions": [
            {
                "url": "https://www.canvasmedical.com/extensions",
                "permissions": ["ALLOW_SAME_ORIGIN", "SCRIPTS", "MICROPHONE", "CAMERA"]
            }
        ],
        "components": {
            "applications": [
                {
                    "class": "example_patient_portal_page.applications.my_application:MyApplication",
                    "name": "My Cool Tool",
                    "description": "Defines the menu item and what it should launch.",
                    "scope": "portal_menu_item",
                    "icon": "assets/icon.png"
                }
            ],
            "handlers": [
                {
                    "class": "example_patient_portal_page.handlers.my_web_app:MyWebApp",
                    "description": "Serves the application"
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  handlers/ 
###  my_web_app.py 
This file defines a simple web application, MyWebApp, that serves HTML, JavaScript, and CSS content.
**Authentication**
The app uses session credentials to check if a user is logged in before providing access to its endpoints. This is done in the authenticate method, which returns True only if a logged-in user exists.
**Endpoints**
  - **/app/patient-portal-application** :
    - Retrieves the current logged-in Patient using an ID supplied in the request headers.
    - Renders an HTML template ("static/index.html") and supplies the patient's first and last name as context variables.
    - Returns a rendered HTML page as the response.
  - **/app/main.js** :
    - Serves the contents of "static/main.js" as JavaScript.
  - **/app/styles.css** :
    - Serves the contents of "static/styles.css" as CSS.
**Template Rendering**
All files (HTML, JS, CSS) are rendered using the Canvas SDK's render_to_string function, allowing the inclusion of dynamic server-side data, especially for the HTML response.
**Security**
Only authenticated (logged-in) users can access any endpoint. The app enforces this globally by overriding the authenticate method.
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import HTMLResponse, Response
    from canvas_sdk.handlers.simple_api import SessionCredentials, SimpleAPI, api
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data.patient import Patient
    #
    # Check out https://docs.canvasmedical.com/sdk/handlers-simple-api-http
    class MyWebApp(SimpleAPI):
        PREFIX = "/app"
        # Using session credentials allows us to ensure only logged in users can
        # access this.
        def authenticate(self, credentials: SessionCredentials) -> bool:
            return credentials.logged_in_user != None
        # Serve templated HTML
        @api.get("/patient-portal-application")
        def index(self) -> list[Response | Effect]:
            logged_in_user = Patient.objects.get(id=self.request.headers["canvas-logged-in-user-id"])
            context = {
                "first_name": logged_in_user.first_name,
                "last_name": logged_in_user.last_name,
            }
            return [
                HTMLResponse(
                    render_to_string("static/index.html", context),
                    status_code=HTTPStatus.OK,
                )
            ]
        # Serve the contents of a js file
        @api.get("/main.js")
        def get_main_js(self) -> list[Response | Effect]:
            return [
                Response(
                    render_to_string("static/main.js").encode(),
                    status_code=HTTPStatus.OK,
                    content_type="text/javascript",
                )
            ]
        # Serve the contents of a css file
        @api.get("/styles.css")
        def get_css(self) -> list[Response | Effect]:
            return [
                Response(
                    render_to_string("static/styles.css").encode(),
                    status_code=HTTPStatus.OK,
                    content_type="text/css",
                )
            ]
    ```
##  assets/ 
###  icon.png 
This icon is displayed in the portal menu.
##  applications/ 
###  my_application.py 
The code defines a custom application called `MyApplication`, which is the mechanism for registering the application in the portal menu..
**Key Functionality**
  - The core implementation is within the `on_open` method, which handles the application's "open" event.
  - When the application is opened, it triggers a launch effect (`LaunchModalEffect`) that opens an iframe modal.
  - The iframe modal displays the content found at the URL `/plugin-io/api/example_patient_portal_page/app/patient-portal-application`.
  - The effect specifically targets the main page area (`target=LaunchModalEffect.TargetType.PAGE`) for embedding.
  - The `on_open` method is a customization point where additional logic could be inserted—for example, dynamic URL selection based on application state or data.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class MyApplication(Application):
        """An embeddable application that can be registered to Canvas."""
        def on_open(self) -> Effect:
            """Handle the on_open event."""
            # Implement this method to handle the application on_open event.
            # You can look up data here to be used in knowing what to launch, if
            # what you're launching depends on some dynamic criteria.
            return LaunchModalEffect(
                # This URL is what will get iframed. It can be hosted elsewhere,
                # or it could be hosted by your plugin! Canvas plugins can serve
                # html, css, js, or json.
                #
                # If embedding a remote URL, be sure to declare it in the URL
                # permissions section of your plugin's CANVAS_MANIFEST.json
                url="/plugin-io/api/example_patient_portal_page/app/patient-portal-application",
                target=LaunchModalEffect.TargetType.PAGE,
            ).apply()
    ```
##  static/ 
###  main.js 
Static javascript referenced by the html template.
###  styles.css 
Stylesheets referenced by the html template.
###  index.html 
Templated HTML to render when the menu item is clicked.

---

# Customize Patient Portal with Widgets

Source: https://docs.canvasmedical.com/sdk/example-portal-customization-widgets/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/patient_portal_plugin) for this plugin on GitHub.
##  Description 
The Patient Portal Widgets Plugin provides various widgets for the patient portal. The plugin listens to the `PATIENT_PORTAL__WIDGET_CONFIGURATION` event.
##  Widgets 
###  Header Widget 
The Header Widget displays the patient's preferred name and has quick links for messaging and scheduling.
For more, visit the [Canvas SDK documentation](https://docs.canvasmedical.com/sdk/data-patient/)
###  Care Team Widget 
It is used to display a compact widget in the Patient Portal that lists the active care team members for a patient.
It renders a scrollable list in a compact plugin format of all active members.
For more information, visit the [Canvas SDK documentation](https://docs.canvasmedical.com/sdk/data-care-team/).
###  Footer Widget 
The Footer Widget displays the support contact information for the patient.
##  Secrets 
The Patient Portal Plugin uses the following secrets:
  - `BACKGROUND_COLOR`: The background color for the widgets. Defaults to `#17634d`.
  - `EMERGENCY_CONTACT`: The emergency contact information. Defaults to `1-888-555-5555`.
In order to deal with `SECRETS` take a look at the [SDK documentation](https://docs.canvasmedical.com/sdk/secrets/).
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "patient_portal_plugin",
        "description": "Patient Portal Plugin for Canvas",
        "components": {
            "handlers": [
                {
                    "class": "patient_portal_plugin.handlers.patient_portal_handler:PatientPortalHandler",
                    "description": "The handler that listens for the patient portal `PATIENT_PORTAL__WIDGET_CONFIGURATION` and responds with the patient portal widgets"
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [
            {"name": "BACKGROUND_COLOR", "sensitive": false},
            {"name": "EMERGENCY_CONTACT", "sensitive": false}
        ],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  templates/ 
###  care_team_widget.html 
###  header_widget.html 
###  footer_widget.html 
##  handlers/ 
###  patient_portal_handler.py 
**Purpose**
The code defines a handler, PatientPortalHandler, for the Canvas Medical SDK that renders custom widgets on the patient portal within Canvas. It listens for a specific widget configuration event and responds by displaying a set of widgets (header, care team, and footer) with certain configurable properties.
**Event Handling**
The handler is triggered (via RESPONDS_TO) when the event type PATIENT_PORTAL__WIDGET_CONFIGURATION occurs. When Canvas requests portal widget configuration for a patient, this handler gets called.
**Widgets Produced**
  - **Header Widget** : Collects basic patient information (first name, last name, etc.), constructs a "preferred full name," and passes it to an HTML template along with a configurable background color (using either a secret or a default).
  - **Care Team Widget** : Fetches the patient's active care team members. For each member, gathers name components, professional role, profile photo URL, and composes formatted display strings. This list is rendered in a compact widget, styled with the background color as a title color.
  - **Footer Widget** : Renders a footer using a background color and an emergency contact number, both customizable via secrets, falling back to sensible defaults if not specified.
**Widget Rendering**
For each widget, an appropriate HTML template is rendered with the relevant payload/context, and the widget is then wrapped as a PortalWidget with defined size and priority. These effects are returned as a list which the Canvas platform uses to display each widget on the patient portal.
**Customization and Defaults**
Two elements are customizable via the plugin's secrets dictionary:
  - BACKGROUND_COLOR: Sets the color for visual elements (widgets, titles).
  - EMERGENCY_CONTACT: Sets the emergency contact number in the footer.
If these are not provided, default values are used:
  - DEFAULT_BACKGROUND_COLOR = "#17634d"
  - DEFAULT_EMERGENCY_CONTACT = "1-888-555-5555"
**Summary**
This file enables a Canvas plugin to inject and style custom patient-facing widgets: a personalized header, a care team overview, and an emergency contact panel, all triggered when the platform requests configuration for the patient portal widgets. It leverages data models and template rendering of the Canvas SDK, with runtime customization via plugin secrets.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.widgets import PortalWidget
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Patient
    from canvas_sdk.v1.data.care_team import CareTeamMembership, CareTeamMembershipStatus
    # Inherit from BaseHandler to properly get registered for events
    class PatientPortalHandler(BaseHandler):
        """Handler responsible for rendering a patient portal widgets."""
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__WIDGET_CONFIGURATION)
        # Default background and title color for the portal's widgets if not provided in secrets
        DEFAULT_BACKGROUND_COLOR = "#17634d"
        # Default emergency contact number if not provided in secrets
        DEFAULT_EMERGENCY_CONTACT = "1-888-555-5555"
        def compute(self) -> list[Effect]:
            """This method gets called when an event of the type RESPONDS_TO is fired."""
            return [
                self.header_widget,
                self.care_team_widget,
                self.footer_widget,
            ]
        @property
        def header_widget(self) -> Effect:
            """Constructs the header widget for the patient portal."""
            # Get the patient needed fields to generate the preferred full name
            patient = Patient.objects.only("first_name", "last_name", "suffix", "nickname").get(id=self.target)
            payload = {
                "preferred_full_name": patient.preferred_full_name,
                "background_color": self.background_color,
            }
            header_widget = PortalWidget(
                content=render_to_string("templates/header_widget.html", payload),
                size=PortalWidget.Size.EXPANDED,
                priority=10,
            )
            return header_widget.apply()
        @property
        def care_team_widget(self) -> Effect:
            """Constructs the care team widget for the patient portal."""
            patient_care_team = CareTeamMembership.objects.values(
                "staff__first_name",
                "staff__last_name",
                "staff__prefix",
                "staff__suffix",
                "staff__photos__url",
                "role_display",
            ).filter(
                patient__id=self.target,
                status=CareTeamMembershipStatus.ACTIVE,
            )
            care_team = []
            for member in patient_care_team:
                # Aliasing the member's name components for clarity
                name = f"{member['staff__first_name']} {member['staff__last_name']}"
                prefixed_name = f"{member['staff__prefix']} " if member['staff__prefix'] else name
                professional_name = f"{prefixed_name}, {member['staff__suffix']}" if member['staff__suffix'] else prefixed_name
                photo_url = member['staff__photos__url']
                role = member['role_display']
                care_team.append(
                    {
                        "name": name,
                        "prefixed_name": prefixed_name,
                        "professional_name": professional_name,
                        "photo_url": photo_url,
                        "role": role,
                    }
                )
            payload = {
                "care_team": care_team,
                "title_color": self.background_color,
            }
            care_team_widget = PortalWidget(
                content=render_to_string("templates/care_team_widget.html", payload),
                size=PortalWidget.Size.COMPACT,
                priority=11,
            )
            return care_team_widget.apply()
        @property
        def footer_widget(self) -> Effect:
            """This method gets called when an event of the type RESPONDS_TO is fired."""
            return PortalWidget(
                content=render_to_string("templates/footer_widget.html", {
                    "background_color": self.background_color,
                    "emergency_contact": self.emergency_contact,
                }),
                size=PortalWidget.Size.EXPANDED,
                priority=12,
            ).apply()
        @property
        def background_color(self) -> str:
            """Get the background color from secrets, defaulting to a specific color if not set."""
            return self.secrets.get("BACKGROUND_COLOR") or self.DEFAULT_BACKGROUND_COLOR
        @property
        def emergency_contact(self) -> str:
            """Get the emergency contact from secrets, defaulting to a specific contact if not set."""
            return self.secrets.get("EMERGENCY_CONTACT") or self.DEFAULT_EMERGENCY_CONTACT
    ```

---

# Send All Prescriptions

Source: https://docs.canvasmedical.com/sdk/example-send_all_prescriptions/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/send_all_prescriptions) for this plugin on GitHub.
A Canvas plugin that adds a "Send Prescriptions" button to note footers, allowing healthcare providers to send all committed prescriptions in a note with a single click.
##  SDK Features 
  - Creates an [ActionButton](/sdk/handlers-action-buttons/) that uses the [Note](/sdk/data-note/) context to get all committed prescribe [Commands](/sdk/data-command/) in a Note
  - Returns a list of [PrescribeCommand](sdk/commands/#prescribe) effects with [`send`](/sdk/commands/#send) action request
##  Structure 
    ```plaintext
    send_all_prescriptions/
    ├── CANVAS_MANIFEST.json          # Plugin configuration
    ├── README.md                     # Documentation
    ├── handlers/
    │   └── handler.py                # Defines SendPrescriptionButtonHandler class
    ```
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "1.0.0",
        "name": "send_all_prescriptions",
        "description": "Adds a 'Send Prescriptions' button to note footers that allows providers to send all committed prescriptions in a note with a single click, streamlining the prescription workflow.",
        "components": {
            "handlers": [
                {
                    "class": "send_all_prescriptions.handlers.handler:SendPrescriptionButtonHandler",
                    "description": "Action button that sends all committed prescriptions in the current note.",
                    "data_access": {
                        "event": "",
                        "read": [],
                        "write": []
                    }
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [],
        "tags": {},
        "references": ["https://docs.canvasmedical.com/sdk/handlers-action-buttons/", "https://docs.canvasmedical.com/sdk/commands/#prescribe"],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  handlers/ 
###  handler.py 
This file defines a custom button handler. It provides functionality to send all prescription commands associated with a specific note when the button is activated.
  - The main class, `SendPrescriptionButtonHandler`, inherits from `ActionButton` and represents a custom action button shown in the UI (specifically, at the note footer).
  - The button is labeled "Send Prescriptions" and assigned a unique key "SEND_ALL_PRESCRIPTIONS".
**Button Handling Logic**
  - The `handle` method is the core logic, executed when the user clicks the button.
  - It obtains the `note_id` from the plugin execution context (self.context).
  - It queries the database for all commands of type `"prescribe"` that are committed (i.e., have an associated committer) and belong to the given note.
  - For each qualifying command, it creates a `PrescribeCommand`, sets its UUID to match the command, and calls `send()`, which returns an `Effect`.
  - All created effects are collected into a list and returned; these effects trigger the actual process of sending prescriptions.
    ```python
    from canvas_sdk.commands import PrescribeCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.handlers.action_button import ActionButton
    from canvas_sdk.v1.data import Command
    class SendPrescriptionButtonHandler(ActionButton):
        BUTTON_TITLE = "Send Prescriptions"
        BUTTON_KEY = "SEND_ALL_PRESCRIPTIONS"
        BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_FOOTER
        def handle(self) -> list[Effect]:
            note_id = self.context.get("note_id")
            effects = []
            # get all committed prescribe commands
            prescribe_commands = Command.objects.filter(note_id=note_id, schema_key="prescribe", committer__isnull=False)
            for command in prescribe_commands:
                prescribe = PrescribeCommand()
                prescribe.command_uuid = str(command.id)
                effects.append(prescribe.send())
            return effects
    ```
##  Customization 
###  Button Appearance 
You can customize the button by modifying the class attributes:
    ```python
    BUTTON_TITLE = "Your Custom Title"    # Change button text
    BUTTON_KEY = "YOUR_UNIQUE_KEY"        # Change button identifier
    ```
###  Button Location 
Change where the button appears by modifying:
    ```python
    BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_FOOTER  # or other locations
    ```

---

# SendGrid Email

Source: https://docs.canvasmedical.com/sdk/example-sendgrid_email/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/sendgrid_email) for this plugin on GitHub.
##  Description 
Plugin that provides a SimpleAPI for sending emails, querying sent emails, managing inbound and outbound webhooks, and handling email status callbacks using the Canvas SDK's SendGrid client. It supports inline images, file attachments, inbound email parsing, and outbound event tracking. Includes a chart application that renders a form interface for email management directly from the chart.
##  Configuration 
This example plugin defines the following "secrets" in the manifest file:
    ```plaintext
        "variables": [
            {"name": "SendgridAPIKey", "sensitive": true}
        ],
    ```
Once defined in the `MANIFEST.json`, set the secrets for your plugin in the Admin UI of your Canvas EMR. [Read more](https://docs.canvasmedical.com/sdk/secrets/)
###  SendgridAPIKey 
Your [SendGrid API key](https://docs.sendgrid.com/ui/account-and-settings/api-keys).
##  CANVAS_MANIFEST.json 
    ```json
    {
      "sdk_version": "0.85.0",
      "plugin_version": "0.0.1",
      "name": "email_sender",
      "description": "use Sendgrid to send emails, retrieve sent emails, manage inbound and outbound webhooks",
      "components": {
        "handlers": [
          {
            "class": "email_sender.handlers.email_manip:EmailManip",
            "description": "Emails with Sendgrid"
          }
        ],
        "applications": [
          {
            "class": "email_sender.handlers.email_form_app:EmailFormApp",
            "name": "Emails Sendgrid",
            "description": "Emails with Sendgrid",
            "icon": "static/email_sender.png",
            "scope": "patient_specific",
            "show_in_panel": false
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [
        {"name": "SendgridAPIKey", "sensitive": true}
      ],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
##  handlers/ 
###  email_manip.py 
**Purpose**
This code defines a SimpleAPI handler that exposes REST endpoints for managing email operations via the Canvas SDK's SendGrid client.
**Class Overview**
  - The main class, `EmailManip`, extends `SimpleAPI`.
  - It creates a SendGrid `EmailClient` using an API key stored in plugin secrets.
  - It uses the plugin cache system for storing webhook callback data.
**Main Workflow**
  - `POST /send_email` — Sends an email with optional inline images and file attachments.
  - `POST /emails_sent` — Queries sent emails with optional filters for recipient and date.
  - `GET /email_events/<message_id>` — Retrieves email events for a specific message.
  - `POST /inbound_webhook` — Enables/disables the SendGrid inbound parse webhook.
  - `GET /inbound_webhook` — Gets the current inbound webhook configuration status.
  - `POST /outbound_webhook` — Enables/disables the SendGrid outbound event webhook.
  - `GET /outbound_webhook` — Gets the current outbound webhook configuration status.
  - `POST /inbound_email` — Receives and caches parsed inbound emails from SendGrid.
  - `GET /inbound_email` — Retrieves the most recent inbound email from cache.
  - `POST /outbound_email_status` — Receives and caches outbound email status events.
  - `GET /outbound_email_status` — Retrieves the most recent outbound status events from cache.
**SendGrid Client Integration**
  - The `_sendgrid_client` method creates an `EmailClient` instance from `canvas_sdk.clients.sendgrid.libraries`.
  - Email composition uses structured types: `Address`, `Recipient`, `BodyContent`, `Attachment`, and `Email`.
  - Error handling uses the `RequestFailed` exception from the SendGrid client structures.
    ```python
    from datetime import UTC, datetime, timedelta
    from http import HTTPStatus
    from email_sender.constants.constants import Constants
    from canvas_sdk.caching.plugins import get_cache
    from canvas_sdk.clients.sendgrid.constants import (
        CriterionOperation,
        RecipientType,
    )
    from canvas_sdk.clients.sendgrid.libraries import EmailClient
    from canvas_sdk.clients.sendgrid.structures import (
        Address,
        Attachment,
        BodyContent,
        CriterionDatetime,
        Email,
        EmailEvent,
        EventWebhook,
        LoggedEmailCriteria,
        ParsedEmail,
        ParseSetting,
        Recipient,
        RequestFailed,
        Settings,
    )
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import Credentials, SimpleAPI, api
    from logger import log
    class EmailManip(SimpleAPI):
        """API handler for SendGrid email operations including sending, webhooks, and logging."""
        PREFIX = None
        def authenticate(self, credentials: Credentials) -> bool:
            """Authenticate the API request. Always returns True (no authentication required)."""
            return True
        def _sendgrid_client(self) -> EmailClient:
            """Create and return a configured SendGrid email client."""
            settings = Settings(key=self.secrets[Constants.sendgrid_api_key])
            return EmailClient(settings)
        @api.get("/email_events/<message_id>")
        def email_events(self) -> list[Response | Effect]:
            """Retrieve email events for a specific message ID from SendGrid."""
            message_id = self.request.path_params["message_id"]
            client = self._sendgrid_client()
            try:
                result = [
                    JSONResponse(
                        client.logged_email(message_id).to_dict(),
                        status_code=HTTPStatus(HTTPStatus.OK),
                    )
                ]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.post("/emails_sent")
        def emails_sent(self) -> list[Response | Effect]:
            """Query sent emails from SendGrid with optional filters for recipient and date."""
            content = self.request.json()
            to_email = content.get("emailTo")
            on_day = content.get("onDay")
            max_logs = content.get("maxLogs")
            client = self._sendgrid_client()
            try:
                message_created_at = []
                if on_day:
                    date_time = datetime.strptime(on_day, "%Y-%m-%d")
                    message_created_at = [
                        CriterionDatetime(
                            date_time=date_time,
                            operation=CriterionOperation.GREATER_THAN_OR_EQUAL,
                        ),
                    ]
                    next_date = date_time + timedelta(days=1)
                    if next_date < datetime.now():
                        message_created_at.append(
                            CriterionDatetime(
                                date_time=next_date,
                                operation=CriterionOperation.LOWER_THAN_OR_EQUAL,
                            )
                        )
                criteria = LoggedEmailCriteria(
                    message_id="",
                    subject="",
                    to_email=to_email,
                    reason="",
                    status=[],
                    message_created_at=message_created_at,
                )
                result = [
                    JSONResponse(
                        [email.to_dict() for email in client.logged_emails(criteria, max_logs)],
                        status_code=HTTPStatus(HTTPStatus.OK),
                    )
                ]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.post("/send_email")
        def send_email(self) -> list[Response | Effect]:
            """Send an email via SendGrid with optional inline images and attachments."""
            content = self.request.json()
            email_from = content.get("emailFrom")
            email_to = content.get("emailTo")
            email_cc = content.get("emailCc")
            subject = content.get("subject")
            body = content.get("body")
            inline_url = content.get("inlineUrl")
            attachment_url = content.get("attachmentUrl")
            client = self._sendgrid_client()
            try:
                sender = Address(email=email_from, name="Sender")
                reply_tos = [Address(email=email_from, name="ReplyTo")]
                recipients = [
                    Recipient(address=Address(email=email_to, name="RecTo"), type=RecipientType.TO)
                ]
                if email_cc:
                    cc = Recipient(address=Address(email=email_cc, name="RecCc"), type=RecipientType.CC)
                    recipients.append(cc)
                subject = f"{subject} - {datetime.now(UTC).strftime('%H:%M:%S')}"
                bodies = [BodyContent(type="text/plain", value=body)]
                attachments = []
                if inline_url:
                    attached = Attachment.from_url_inline(
                        inline_url, {}, "inline_picture.png", "pictureId"
                    )
                    attachments.append(attached)
                    html_body = BodyContent(
                        type="text/html",
                        value=f"<html><body>{body}<br/>"
                        '<img src="cid:pictureId" width="200px"/><br/>'
                        "Bye!</body></html>",
                    )
                    bodies.append(html_body)
                if attachment_url:
                    attached = Attachment.from_url(attachment_url, {}, "attached_picture.png")
                    attachments.append(attached)
                email = Email(
                    sender=sender,
                    reply_tos=reply_tos,
                    recipients=recipients,
                    subject=subject,
                    bodies=bodies,
                    attachments=attachments,
                    send_at=Email.now(),
                )
                result = [
                    JSONResponse(
                        {"successful": client.simple_send(email)},
                        status_code=HTTPStatus(HTTPStatus.OK),
                    )
                ]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        def parser_url(self) -> str:
            """Build the URL for the inbound email parser webhook endpoint."""
            host = f"https://{self.environment[Constants.customer_identifier]}.canvasmedical.com"
            return f"{host}{Constants.plugin_api_base_route}/inbound_email"
        @api.post("/inbound_webhook")
        def inbound_webhook_toggle(self) -> list[Response | Effect]:
            """Enable or disable the SendGrid inbound parse webhook."""
            content = self.request.json()
            enabled = content.get("enabled")
            hostname = content.get("hostname")
            client = self._sendgrid_client()
            try:
                result = [JSONResponse({"enabled": enabled}, status_code=HTTPStatus(HTTPStatus.OK))]
                parser_url = self.parser_url()
                parsers = [
                    parser.hostname
                    for parser in client.parser_setting_list()
                    if parser.url == parser_url
                ]
                if enabled and not parsers:
                    setting = ParseSetting(
                        url=self.parser_url(),
                        hostname=hostname,
                        spam_check=True,
                        send_raw=False,
                    )
                    client.parser_setting_add(setting)
                if not enabled and parsers:
                    client.parser_setting_delete(parsers[0])
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.get("/inbound_webhook")
        def inbound_webhook_get(self) -> list[Response | Effect]:
            """Get the current status of the inbound parse webhook configuration."""
            client = self._sendgrid_client()
            try:
                parser_url = self.parser_url()
                parsers = [
                    parser for parser in client.parser_setting_list() if parser.url == parser_url
                ]
                response = {"enabled": bool(parsers), "hostname": ""}
                if parsers:
                    response["hostname"] = parsers[0].hostname
                result = [JSONResponse(response, status_code=HTTPStatus(HTTPStatus.OK))]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        def webhook_url(self) -> str:
            """Build the URL for the outbound email status webhook endpoint."""
            host = f"https://{self.environment[Constants.customer_identifier]}.canvasmedical.com"
            return f"{host}{Constants.plugin_api_base_route}/outbound_email_status"
        @api.post("/outbound_webhook")
        def outbound_webhook_toggle(self) -> list[Response | Effect]:
            """Enable or disable the SendGrid outbound event webhook."""
            content = self.request.json()
            enabled = content.get("enabled")
            client = self._sendgrid_client()
            try:
                result = [JSONResponse({"enabled": enabled}, status_code=HTTPStatus(HTTPStatus.OK))]
                webhook_url = self.webhook_url()
                webhook_ids = [
                    webhook.id for webhook in client.event_webhook_list() if webhook.url == webhook_url
                ]
                if enabled and not webhook_ids:
                    event = EventWebhook(
                        url=webhook_url,
                        enabled=True,
                        group_resubscribe=False,
                        group_unsubscribe=False,
                        delivered=True,
                        spam_report=True,
                        bounce=True,
                        unsubscribe=False,
                        processed=True,
                        open=True,
                        click=True,
                        dropped=True,
                        friendly_name="Canvas Plugin Webhook",
                    )
                    client.event_webhook_add(event)
                if not enabled and webhook_ids:
                    client.event_webhook_delete(webhook_ids[0])
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.get("/outbound_webhook")
        def outbound_webhook_get(self) -> list[Response | Effect]:
            """Get the current status of the outbound event webhook configuration."""
            client = self._sendgrid_client()
            try:
                webhook_url = self.webhook_url()
                enabled = any(
                    webhook.id for webhook in client.event_webhook_list() if webhook.url == webhook_url
                )
                result = [JSONResponse({"enabled": enabled}, status_code=HTTPStatus(HTTPStatus.OK))]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.get("/outbound_email_status")
        def last_outbound_status(self) -> list[Response | Effect]:
            """Retrieve the most recent outbound email status events from cache."""
            return [
                JSONResponse(
                    self.cache_retrieve("outbound_email_status"), status_code=HTTPStatus(HTTPStatus.OK)
                )
            ]
        @api.post("/outbound_email_status")
        def outbound_status_save(self) -> list[Response | Effect]:
            """Receive and cache outbound email status events from SendGrid webhook."""
            events = [EmailEvent.from_dict(item) for item in self.request.json()]
            self.cache_save("outbound_email_status", [e.to_dict() for e in events])
            log.info(f"outbound status received:{len(events)}")
            return [Response(status_code=HTTPStatus(HTTPStatus.OK))]
        @api.get("/inbound_email")
        def last_inbound_email(self) -> list[Response | Effect]:
            """Retrieve the most recent inbound email from cache."""
            return [
                JSONResponse(
                    self.cache_retrieve("inbound_treatment"),
                    status_code=HTTPStatus(HTTPStatus.OK),
                )
            ]
        @api.post("/inbound_email")
        def inbound_email_save(self) -> list[Response | Effect]:
            """Receive and cache parsed inbound emails from SendGrid webhook."""
            form = self.request.form_data()
            message = {}
            files = []
            for key, value in form.multi_items():
                if (
                    hasattr(value, "file")
                    and hasattr(value, "filename")
                    and hasattr(value, "content_type")
                ):
                    files.append((key, value))
                else:
                    if hasattr(value, "value"):
                        message[key] = value.value
                    elif isinstance(value, str):
                        message[key] = value
                    else:
                        message[key] = str(value)
            parsed = ParsedEmail.from_dict(message)
            self.cache_save("inbound_treatment", [parsed.to_dict()])
            log.info(f"inbound email received from {parsed.email_from} to {parsed.email_to}")
            return [Response(status_code=HTTPStatus(HTTPStatus.OK))]
        @classmethod
        def cache_save(cls, key: str, payload: list) -> None:
            """Store a payload in the plugin cache under the given key."""
            get_cache().set(key, payload)
        @classmethod
        def cache_retrieve(cls, key: str) -> list:
            """Retrieve a cached payload by key, returning an empty list if not found."""
            return get_cache().get(key) or []
    ```
###  email_form_app.py 
**Purpose**
This code defines an Application handler that launches a modal form in the right chart pane for interacting with the SendGrid email API endpoints.
    ```python
    from email_sender.constants.constants import Constants
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    from canvas_sdk.templates import render_to_string
    class EmailFormApp(Application):
        """Application handler that displays the email sender form in a modal."""
        def on_open(self) -> Effect:
            """Render and launch the email form modal in the right chart pane."""
            content = render_to_string(
                "templates/email_form.html",
                {
                    "sendEmailURL": f"{Constants.plugin_api_base_route}/send_email",
                    "emailsSentURL": f"{Constants.plugin_api_base_route}/emails_sent",
                    "emailEventsURL": f"{Constants.plugin_api_base_route}/email_events",
                    "outboundWebhookURL": f"{Constants.plugin_api_base_route}/outbound_webhook",
                    "outboundStatusesURL": f"{Constants.plugin_api_base_route}/outbound_email_status",
                    "inboundWebhookURL": f"{Constants.plugin_api_base_route}/inbound_webhook",
                    "inboundEmailURL": f"{Constants.plugin_api_base_route}/inbound_email",
                },
            )
            return LaunchModalEffect(
                content=content,
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
            ).apply()
    ```

---

# Twilio SMS/MMS

Source: https://docs.canvasmedical.com/sdk/example-twilio_sms_mms/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/twilio_sms_mms) for this plugin on GitHub.
##  Description 
Plugin that provides a SimpleAPI for sending and receiving SMS/MMS messages using the Canvas SDK's Twilio client. It supports listing phone numbers, sending messages, retrieving message history and media, managing inbound webhooks, handling delivery status callbacks, and auto-replying to inbound messages. Includes a chart application that renders a form interface for SMS management directly from the chart.
##  Configuration 
This example plugin defines the following "secrets" in the manifest file:
    ```plaintext
        "variables": [
            {"name": "TwilioAccountSID", "sensitive": true},
            {"name": "TwilioAPIKey", "sensitive": true},
            {"name": "TwilioAPISecret", "sensitive": true}
        ],
    ```
Once defined in the `MANIFEST.json`, set the secrets for your plugin in the Admin UI of your Canvas EMR. [Read more](https://docs.canvasmedical.com/sdk/secrets/)
###  TwilioAccountSID 
Your [Twilio Account SID](https://www.twilio.com/docs/iam/api/account).
###  TwilioAPIKey 
Your [Twilio API Key SID](https://www.twilio.com/docs/iam/api-keys).
###  TwilioAPISecret 
Your [Twilio API Key Secret](https://www.twilio.com/docs/iam/api-keys).
##  CANVAS_MANIFEST.json 
    ```json
    {
      "sdk_version": "0.85.0",
      "plugin_version": "0.0.1",
      "name": "twilio_sms_mms",
      "description": "use Twillio to send and receive SMS/MMS",
      "components": {
        "handlers": [
          {
            "class": "twilio_sms_mms.handlers.sms_manip:SmsManip",
            "description": "SMS/MMS with Twilio"
          }
        ],
        "applications": [
          {
            "class": "twilio_sms_mms.handlers.sms_form_app:SmsFormApp",
            "name": "SMS Twilio",
            "description": "SMS/MMS with Twilio",
            "icon": "static/twilio_sms_mms.png",
            "scope": "patient_specific",
            "show_in_panel": false
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [
        {"name": "TwilioAccountSID", "sensitive": true},
        {"name": "TwilioAPIKey", "sensitive": true},
        {"name": "TwilioAPISecret", "sensitive": true}
      ],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
##  handlers/ 
###  sms_manip.py 
**Purpose**
This code defines a SimpleAPI handler that exposes REST endpoints for managing SMS/MMS operations via the Canvas SDK's Twilio client.
**Class Overview**
  - The main class, `SmsManip`, extends `StaffSessionAuthMixin` and `SimpleAPI`.
  - It creates a Twilio `SmsClient` using credentials stored in plugin secrets (Account SID, API Key, API Secret).
**Main Workflow**
  - `GET /phone_list` — Retrieves all phone numbers associated with the Twilio account, including capabilities and webhook configuration.
  - `GET /message_list/<number>/<direction>` — Lists messages for a specific phone number filtered by direction (from/to).
  - `GET /message/<message_sid>` — Retrieves details of a specific message.
  - `GET /medias/<message_sid>` — Retrieves all media attachments for a specific message.
  - `DELETE /message_delete/<message_sid>` — Deletes a specific message.
  - `POST /sms_send` — Sends an SMS message with optional status callback URL.
  - `POST /inbound_webhook/<phone_sid>` — Configures the inbound webhook URL for a Twilio phone number.
  - `POST /outbound_api_status` — Handles status callbacks for outbound SMS messages.
  - `POST /inbound_treatment` — Processes incoming messages and sends automatic replies with optional media.
**Twilio Client Integration**
  - The `_twillio_client` method creates an `SmsClient` instance from `canvas_sdk.clients.twilio.libraries`.
  - Error handling uses the `RequestFailed` exception from the Twilio client structures.
  - Inbound message handling generates TwiML responses for automatic replies.
    ```python
    from http import HTTPStatus
    from canvas_sdk.clients.twilio.constants import DateOperation, HttpMethod
    from canvas_sdk.clients.twilio.libraries import SmsClient
    from canvas_sdk.clients.twilio.structures import (
        RequestFailed,
        Settings,
        SmsMms,
        StatusInbound,
        StatusOutboundApi,
    )
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import HTMLResponse, JSONResponse, Response
    from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin, api
    from logger import log
    from ..constants.constants import Constants
    class SmsManip(StaffSessionAuthMixin, SimpleAPI):
        """API handler for Twilio SMS/MMS operations."""
        PREFIX = None
        def _twillio_client(self) -> SmsClient:
            """Create and configure a Twilio SMS client."""
            settings = Settings(
                account_sid=self.secrets[Constants.twillio_account_sid],
                key=self.secrets[Constants.twillio_api_key],
                secret=self.secrets[Constants.twillio_api_secret],
            )
            return SmsClient(settings)
        @api.get("/phone_list")
        def phone_list(self) -> list[Response | Effect]:
            """Retrieve the list of phone numbers associated with the Twilio account."""
            client = self._twillio_client()
            try:
                result = [
                    JSONResponse(
                        [
                            {
                                "sid": p.sid,
                                "phoneNumber": p.phone_number,
                                "label": p.friendly_name,
                                "capabilities": p.capabilities.to_dict(),
                                "statusCallback": p.status_callback,
                                "status": p.status,
                                "inboundWebhook": {
                                    "url": p.sms_url,
                                    "method": p.sms_method.value,
                                },
                            }
                            for p in client.account_phone_numbers()
                        ],
                        status_code=HTTPStatus(HTTPStatus.OK),
                    ),
                ]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.get("/message_list/<number>/<direction>")
        def message_list(self) -> list[Response | Effect]:
            """Retrieve a list of messages for a specific phone number."""
            number = self.request.path_params["number"]
            direction = self.request.path_params["direction"]
            number_from = number if direction == "from" else ""
            number_to = number if direction == "to" else ""
            client = self._twillio_client()
            try:
                result = [
                    JSONResponse(
                        [
                            {
                                "sid": p.sid,
                                "sent": p.date_sent.isoformat(),
                                "status": p.status.value,
                                "mediaCount": p.count_media,
                            }
                            for p in client.retrieve_all_sms(
                                number_to, number_from, "", DateOperation.ON_EXACTLY
                            )
                        ],
                        status_code=HTTPStatus(HTTPStatus.OK),
                    ),
                ]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.get("/message/<message_sid>")
        def message(self) -> list[Response | Effect]:
            """Retrieve details of a specific message."""
            message_sid = self.request.path_params["message_sid"]
            client = self._twillio_client()
            try:
                result = [
                    JSONResponse(
                        client.retrieve_sms(message_sid).to_dict(),
                        status_code=HTTPStatus(HTTPStatus.OK),
                    ),
                ]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.get("/medias/<message_sid>")
        def media_list(self) -> list[Response | Effect]:
            """Retrieve all media attachments for a specific message."""
            message_sid = self.request.path_params["message_sid"]
            client = self._twillio_client()
            try:
                result = [
                    Response(
                        content_type=p.content_type,
                        content=client.retrieve_raw_media(message_sid, p.sid),
                    )
                    for p in client.retrieve_media_list(message_sid)
                ]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.delete("/message_delete/<message_sid>")
        def message_delete(self) -> list[Response | Effect]:
            """Delete a specific message from Twilio."""
            message_sid = self.request.path_params["message_sid"]
            client = self._twillio_client()
            try:
                result = [
                    JSONResponse(
                        {
                            "sid": message_sid,
                            "deleted": client.delete_sms(message_sid),
                        },
                        status_code=HTTPStatus(HTTPStatus.OK),
                    )
                ]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.post("/inbound_webhook/<phone_sid>")
        def inbound_webhook(self) -> list[Response | Effect]:
            """Configure the inbound webhook URL for a Twilio phone number."""
            phone_sid = self.request.path_params["phone_sid"]
            content = self.request.json()
            webhook_url = content["url"]
            method = HttpMethod(content["method"])
            client = self._twillio_client()
            try:
                response = client.set_inbound_webhook(phone_sid, webhook_url, method)
                result = [JSONResponse({"result": response}, status_code=HTTPStatus(HTTPStatus.OK))]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.post("/sms_send")
        def sms_send(self) -> list[Response | Effect]:
            """Send an SMS message via Twilio."""
            content = self.request.json()
            number_from = content.get("numberFrom")
            number_from_id = content.get("numberFromSid")
            number_to = content.get("numberTo")
            callback_url = content.get("callbackUrl")
            text = content.get("text")
            client = self._twillio_client()
            try:
                sms_mms = SmsMms(
                    number_from=number_from,
                    number_from_sid=number_from_id,
                    number_to=number_to,
                    message=text,
                    media_url="",
                    status_callback_url=callback_url,
                )
                response = client.send_sms_mms(sms_mms)
                result = [JSONResponse(response.to_dict(), status_code=HTTPStatus(HTTPStatus.OK))]
            except RequestFailed as e:
                result = [
                    JSONResponse({"information": e.message}, status_code=HTTPStatus(e.status_code))
                ]
            return result
        @api.post("/outbound_api_status")
        def outbound_api_status(self) -> list[Response | Effect]:
            """Handle status callbacks for outbound SMS messages."""
            status = StatusOutboundApi.callback_outbound_api(self.request.text())
            log.info(f"sms_extern: sid/status: {status.sms_sid}/{status.sms_status}")
            return [Response(status_code=HTTPStatus(HTTPStatus.OK))]
        @api.post("/inbound_treatment")
        def inbound_treatment(self) -> list[Response | Effect]:
            """Handle inbound SMS messages with automatic replies."""
            inbound = StatusInbound.callback_inbound(self.request.text())
            if "hello" in inbound.body.lower():
                reply = "Hello!"
                image = "<Media>https://img.freepik.com/free-psd/hand-drawn-summer-frame-illustration_23-2151631028.jpg</Media>"
            else:
                reply = "Say hello!"
                image = ""
            response = (
                '<?xml version="1.0" encoding="UTF-8"?>\n'
                "<Response>"
                f"<Message><Body>{reply}</Body>{image}</Message>"
                "</Response>"
            )
            return [
                HTMLResponse(
                    content=response,
                    status_code=HTTPStatus(HTTPStatus.OK),
                )
            ]
    ```
###  sms_form_app.py 
**Purpose**
This code defines an Application handler that launches a modal form in the right chart pane for interacting with the Twilio SMS/MMS API endpoints.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    from canvas_sdk.templates import render_to_string
    from ..constants.constants import Constants
    class SmsFormApp(Application):
        """Application handler for the SMS/MMS form interface."""
        def on_open(self) -> Effect:
            """Render and launch the SMS form modal in the right chart pane."""
            host = f"https://{self.environment[Constants.customer_identifier]}.canvasmedical.com"
            content = render_to_string(
                "templates/sms_form.html",
                {
                    "smsSendURL": f"{Constants.plugin_api_base_route}/sms_send",
                    "phoneListURL": f"{Constants.plugin_api_base_route}/phone_list",
                    "setInboundWebhookURL": f"{Constants.plugin_api_base_route}/inbound_webhook",
                    "messageListURL": f"{Constants.plugin_api_base_route}/message_list",
                    "messageURL": f"{Constants.plugin_api_base_route}/message",
                    "mediaURL": f"{Constants.plugin_api_base_route}/medias",
                    "deleteMessageURL": f"{Constants.plugin_api_base_route}/message_delete",
                    "defaultCallbackURL": f"{host}{Constants.plugin_api_base_route}/outbound_api_status",
                },
            )
            return LaunchModalEffect(
                content=content,
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
            ).apply()
    ```

---

# Upsert Patient Metadata

Source: https://docs.canvasmedical.com/sdk/example-upsert_patient_metadata/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/upsert_patient_metadata) for this plugin on GitHub.
This plugin showcases how to store patient metadata key/value pairs from a plugin using the Canvas SDK.
In this example, we extract key-value pairs from a plan command's narrative and store them as patient metadata.
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "upsert_patient_metadata",
        "description": "Edit the description in CANVAS_MANIFEST.json",
        "components": {
            "handlers": [
                {
                    "class": "upsert_patient_metadata.handlers.my_handler:MyHandler",
                    "description": "A handler that does xyz..."
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
##  handlers/ 
###  my_handler.py 
This file defines a Canvas plugin handler that uses the update of a plan command as an excuse to trigger. When a user updates a plan command and includes certain key-value data in the narrative, this handler extracts that information and saves it as patient metadata.
**Narrative Parsing**
The handler retrieves the narrative text from the event context. It uses regular expressions to look for patterns of the form:
  - `key=somekey`
  - `value=somevalue`
The separator between key/value and their contents can be any character except alphanumerics, underscores, asterisks, hashes, or whitespace. For example, `key=blood_pressure*value=120/80`.
**Action Taken**
If both a key and value are found in the narrative:
  - It logs an informational message including the patient id, key, and value.
  - It returns a list containing one Effect: an upsert (create or update) of patient metadata (via PatientMetadata) for that patient, saving the found key and value.
If either the key or value is missing, no action is performed.
    ```python
    import re
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_metadata import PatientMetadata
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    class MyHandler(BaseHandler):
        """
        Extracts key-value pairs from plan update narratives and stores them as patient metadata.
        Parses narrative text for patterns like "key=somekey*value=somevalue" where the separator
        can be any non-alphanumeric character. If both key and value are found, creates or updates
        the corresponding patient metadata entry.
        Triggers on: PLAN_COMMAND__POST_UPDATE events
        Effects: PatientMetadata upsert operations
        """
        RESPONDS_TO = EventType.Name(EventType.PLAN_COMMAND__POST_UPDATE)
        def compute(self) -> list[Effect]:
            """This method gets called when an event of the type RESPONDS_TO is fired."""
            patient_id = self.context["patient"]["id"]
            fields = self.context.get("fields", {})
            narrative = fields.get("narrative", "")
            key_match = re.search(r"key=([^*#_\s]+)", narrative)
            value_match = re.search(r"value=([^*#_\s]+)", narrative)
            key = key_match.group(1) if key_match else None
            value = value_match.group(1) if value_match else None
            log.info(
                f"Upserting patient metadata for patient {patient_id} with key: {key} and value: {value}"
            )
            if not key or not value:
                return []
            return [PatientMetadata(patient_id=patient_id, key=str(key)).upsert(str(value))]
    ```

---

# Vitals Visualizer

Source: https://docs.canvasmedical.com/sdk/example-vitals_visualizer_plugin/

> **Note:** [View the source](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/vitals_visualizer_plugin) for this plugin on GitHub.
A Canvas plugin that displays a "Visualize" button in the vitals section of the chart summary and shows interactive vital signs visualizations.
##  SDK Features 
  - Creates and responds to a [Simple API](/sdk/handlers-simple-api-http/) endpoint that [renders a template](/sdk/layout-effect/#custom-html-and-django-templates) and returns HTML content
  - Parses [Observation data model](/sdk/data-observation/) to obtain vitals data and format into readable content
  - Adds a "Visualize" [Action Button](/sdk/handlers-action-buttons/) to the vitals section of the patient chart summary.
  - Returns a [LaunchModalEffect](/sdk/layout-effect/#modals) in the right chart pane with content from the vitals endpoint.
##  Configuration 
This SimpleAPI endpoint uses the [StaffSessionAuthMixin](/sdk/handlers-simple-api-http/#staff-session)
##  Structure 
    ```plaintext
    vitals_visualizer_plugin/
    ├── handlers/
    │   ├── __init__.py
    │   ├── vitals_button.py      # Action button handler
    │   └── vitals_api.py         # API endpoint with visualization
    ├── templates/
    │   └── vitals_visualization.html # HTML template for visualization UI
    ├── CANVAS_MANIFEST.json      # Plugin configuration
    └── README.md                 # Documentation
    ```
##  CANVAS_MANIFEST.json 
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.1.0",
        "name": "vitals_visualizer_plugin",
        "description": "A plugin that adds visualization capabilities to patient vital signs in the chart summary",
        "components": {
            "handlers": [
                {
                    "class": "vitals_visualizer_plugin.handlers.vitals_button:VitalsVisualizerButton",
                    "description": "A button that opens vitals visualization modal",
                    "data_access": {
                        "event": "SHOW_CHART_SUMMARY_VITALS_SECTION_BUTTON",
                        "read": ["v1.Observation"],
                        "write": []
                    }
                },
                {
                    "class": "vitals_visualizer_plugin.handlers.vitals_api:VitalsVisualizerAPI",
                    "description": "API endpoint that serves vitals visualization data and UI",
                    "data_access": {
                        "event": "",
                        "read": ["v1.Observation"],
                        "write": []
                    }
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [],
        "tags": [],
        "license": "NONE",
        "readme": "./README.md"
    }
    ```
##  templates/ 
###  vitals_visualization.html 
This is the html template called by the[ `render_to_string` function](/sdk/layout-effect/#custom-html-and-django-templates) with a `vitals_data` object. It contains styling and custom JavaScript to form the chart.
##  handlers/ 
###  vitals_api.py 
The `vitals_api.py` file defines a class-based API endpoint called `VitalsVisualizerAPI` for a Canvas Medical plugin. This endpoint provides both a user interface (HTML) and data (as JSON) for visualizing patient vitals—specifically weight, body temperature, and oxygen saturation.
  - **API Endpoint** : The endpoint is accessed at `/visualize`, and requires staff authentication via `StaffSessionAuthMixin`.
  - **Request Handling** : The main entry point is the `get()` method, which expects a `patient_id` as a query parameter.
    - If `patient_id` is missing, it returns a 400 JSON error response.
    - If present, it fetches and compiles the patient's vital sign data, then generates and returns an HTML interface for visualization.
  - **Vitals Data Extraction** : The `_get_vitals_data(patient_id)` method:
    - Queries Canvas Medical's `Observation` resource for the specified patient.
    - Filters for observations in the "vital-signs" category that are not deleted, not entered in error, and are not "Vital Signs Panel" summary records.
    - Extracts individual observations for:
      - **Weight** (converting from ounces to pounds),
      - **Body Temperature** (with default units °F if missing),
      - **Oxygen Saturation** (with default units % if missing).
    - Organizes the data into a dictionary keyed by vital sign name, each containing a list of timestamped values.
  - **HTML Visualization Rendering** : The `_generate_visualization_html(vitals_data)` method:
    - Serializes the vitals data as JSON.
    - Passes it as context to a template called `vitals_visualization.html` for rendering the UI.
  - **Error Handling and Logging** : All major steps have try/except blocks, logging errors and returning JSON error responses if needed.
**How the Components Work Together**
  - The endpoint provides a combined UI/data interface for staff to review prescribed vitals over time for a selected patient.
  - The code is built for integration into the Canvas Medical system utilizing their SDK, data models, and permission system.
  - All HTML and logic for visualization are rendered server-side using a templating mechanism.
**Dependencies and Assumptions**
  - Depends on `Observation` model/data from Canvas Medical's API SDK.
  - Uses Canvas SDK facilities for routing, API responses, session authentication, and template rendering.
  - Relies on templates being in the `templates/` folder, specifically one for vitals visualization.
  - Expects a structured logging setup.
**Returned Data Types**
  - Templated HTML (for visualization) or JSON (for errors), wrapped in Canvas SDK response objects (`HTMLResponse`, `JSONResponse`).
    ```python
    import json
    from typing import Any, Dict, List
    from canvas_sdk.effects.simple_api import HTMLResponse, JSONResponse
    from canvas_sdk.handlers.simple_api import SimpleAPIRoute, StaffSessionAuthMixin
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Observation
    from logger import log
    class VitalsVisualizerAPI(StaffSessionAuthMixin, SimpleAPIRoute):
        """API endpoint that serves vitals visualization data and UI."""
        PATH = "/visualize"
        def get(self) -> list[HTMLResponse | JSONResponse]:
            """Return the vitals visualization UI and data."""
            patient_id = self.request.query_params.get("patient_id")
            if not patient_id:
                return [JSONResponse({"error": "Patient ID is required"}, status_code=400)]
            try:
                vitals_data = self._get_vitals_data(patient_id)
                html_content = self._generate_visualization_html(vitals_data)
                return [HTMLResponse(content=html_content)]
            except Exception as e:
                log.error(f"Error in VitalsVisualizerAPI: {str(e)}")
                return [JSONResponse({"error": str(e)}, status_code=500)]
        def _get_vitals_data(self, patient_id: str) -> Dict[str, List[Dict[str, Any]]]:
            """Get vitals data for the patient using Canvas vitals structure."""
            try:
                # Get individual vital observations from vital signs panels
                vital_observations = (
                    Observation.objects.for_patient(patient_id)
                    .filter(
                        category="vital-signs",
                        effective_datetime__isnull=False,
                        deleted=False,
                    )
                    .exclude(name="Vital Signs Panel")
                    .exclude(entered_in_error__isnull=False)
                    .select_related("is_member_of")
                    .order_by("effective_datetime")
                )
                vitals_data = {
                    "weight": [],
                    "body_temperature": [],
                    "oxygen_saturation": [],
                }
                for obs in vital_observations:
                    if not obs.value or obs.name in ["note", "pulse_rhythm"]:
                        continue
                    if obs.name == "weight":
                        try:
                            value_oz = float(obs.value)
                            value_lbs = value_oz / 16
                            vitals_data["weight"].append(
                                {
                                    "date": obs.effective_datetime.isoformat(),
                                    "value": round(value_lbs, 1),
                                    "units": "lbs",
                                }
                            )
                        except (ValueError, TypeError):
                            continue
                    elif obs.name == "body_temperature":
                        try:
                            value = float(obs.value)
                            vitals_data["body_temperature"].append(
                                {
                                    "date": obs.effective_datetime.isoformat(),
                                    "value": value,
                                    "units": obs.units or "°F",
                                }
                            )
                        except (ValueError, TypeError):
                            continue
                    elif obs.name == "oxygen_saturation":
                        try:
                            value = float(obs.value)
                            vitals_data["oxygen_saturation"].append(
                                {
                                    "date": obs.effective_datetime.isoformat(),
                                    "value": value,
                                    "units": obs.units or "%",
                                }
                            )
                        except (ValueError, TypeError):
                            continue
                return vitals_data
            except Exception as e:
                log.error(f"Error collecting vitals data: {str(e)}")
                return {"weight": [], "body_temperature": [], "oxygen_saturation": []}
        def _generate_visualization_html(
            self, vitals_data: Dict[str, List[Dict[str, Any]]]
        ) -> str:
            """Generate the HTML for the vitals visualization using template."""
            context = {"vitals_data": json.dumps(vitals_data)}
            return render_to_string("templates/vitals_visualization.html", context)
    ```
###  vitals_button.py 
This file adds a "Visualize" button to the patient chart's vitals section, which, when clicked, opens a modal with a visual representation of the patient's vitals data, using the Canvas plugin and effect framework.
**Class Details**
  - The class `VitalsVisualizerButton` inherits from `ActionButton`.
  - It specifies metadata such as title ("Visualize"), a unique key (`vitals_visualizer_button`), the section of the UI where it appears (vitals summary), and its priority (1).
**Functionality**
  - When a user clicks the button, the `handle` method is triggered.
  - This method constructs a URL to an API endpoint for visualizing vitals: `/plugin-io/api/vitals_visualizer_plugin/visualize?patient_id=<id>`, where `<id>` is the current patient ID.
  - The button initiates a `LaunchModalEffect`, opening a large modal on the right side of the chart pane with the title "Vitals Visualization".
  - The modal displays the contents served by the constructed URL (likely a vitals graph or dashboard).
**Integration with Canvas SDK**
  - Uses SDK classes:
    - `ActionButton` for button behaviors and placement.
    - `LaunchModalEffect` to open a modal window within the Canvas UI.
    - The effect is returned in a list, as required by the SDK's handler pattern.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.action_button import ActionButton
    class VitalsVisualizerButton(ActionButton):
        """A button that opens the vitals visualization modal."""
        BUTTON_TITLE = "Visualize"
        BUTTON_KEY = "vitals_visualizer_button"
        BUTTON_LOCATION = ActionButton.ButtonLocation.CHART_SUMMARY_VITALS_SECTION
        PRIORITY = 1
        def handle(self) -> list[Effect]:
            """Handle button click by opening vitals visualization modal."""
            # The API endpoint will be at /plugin-io/api/vitals_visualizer_plugin/visualize
            # We need to pass the patient ID in the URL
            patient_id = self.target
            return [
                LaunchModalEffect(
                    url=f"/plugin-io/api/vitals_visualizer_plugin/visualize?patient_id={patient_id}",
                    target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE_LARGE,
                    title="Vitals Visualization"
                ).apply()
            ]
    ```

---

# Example Plugins

Source: https://docs.canvasmedical.com/sdk/examples/

The pages below showcase example plugins written with the Canvas SDK. All pages describe the file structure, the functionality, and link to GitHub where you can grab the code yourself and start iterating.
[ API Samples ](/sdk/example-api_samples/)[ Charting Interface ]()[ Patient Portal Customization ]()[ Integrations ]()

---

# Action Buttons

Source: https://docs.canvasmedical.com/sdk/handlers-action-buttons/

Action buttons are UI elements that trigger specific actions when clicked in the Canvas UI. These buttons can be placed in different locations and can interact with runtime data to execute custom code.
> **Danger:** **With great power comes great responsibility.** Your handler runs **synchronously** inside a worker. Slow handler code — especially code that makes a blocking network call to an external service (an LLM API, a third-party HTTP endpoint) — holds that worker for its entire duration. If the external service slows down or goes offline, every invocation piles up until the worker pool is exhausted, and your **entire Canvas instance can be negatively impacted or even temporarily stop responding to requests**. Long timeouts and retries multiply the damage: a 300 second timeout retried three times pins a single worker for over ten minutes. Keep your handler fast, and move long-running or failure-prone work off the synchronous path — see [Keep your handler fast](/sdk/handlers-basehandler/#keep-your-handler-fast).
##  Overview 
An `ActionButton` class allows you to define custom buttons that appear in different sections of the Canvas UI. When a user clicks the button, the action associated with the button is executed. Action buttons can be added to various locations in the UI, and you can control their visibility and behavior through effects in a handler class.
There are no limitations on the number of action buttons you can create. You can define multiple buttons in a single handler class or create separate classes for each button.
##  Creating an action button 
An action button is a [handler](/sdk/handlers-basehandler/). Subclass `ActionButton`, say where it goes with `BUTTON_LOCATION`, and implement `handle()` to say what a click does:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.action_button import ActionButton
    class PatientSummaryButton(ActionButton):
        BUTTON_TITLE = "Summary"
        BUTTON_KEY = "PATIENT_SUMMARY"
        BUTTON_LOCATION = ActionButton.ButtonLocation.CHART_PATIENT_HEADER
        def handle(self) -> list[Effect]:
            return [
                LaunchModalEffect(
                    target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
                    content="<html>Your content here</html>",
                ).apply()
            ]
    ```
Then register the class under `handlers` in your [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#handlers):
    ```json
    {
      "components": {
        "handlers": [
          {
            "class": "my_plugin.buttons.patient_summary:PatientSummaryButton",
            "description": "Shows a summary modal from the patient header."
          }
        ]
      }
    }
    ```
###  Class attributes 
Attribute| Required| Description  
---|---|---  
`BUTTON_TITLE`| Required| The label shown on the button. Emoji are supported.  
`BUTTON_KEY`| Required| A unique identifier for the button. Canvas routes the click back to your `handle()` by this value, so give each button its own.  
`BUTTON_LOCATION`| Required| Where the button appears, as a `ButtonLocation` value.  
`PRIORITY`| Optional| Orders this button against others in the same location, lower first. Defaults to `0`, and buttons sharing a priority have no guaranteed order.  
`BUTTON_TEXT_COLOR`| Optional| The label colour as a HEX value, for example `"#FF0000"`. Defaults to whichever of black or white contrasts with the background.  
`BUTTON_BACKGROUND_COLOR`| Optional| The background colour as a HEX value, for example `"#4CAF50"`. Defaults to Canvas's grey button styling.  
###  Methods 
Method| Returns| Required| Description  
---|---|---|---  
`handle()`| `list[Effect]`| Required| Runs when the button is clicked. Return the [effects](/sdk/effects/) the click should produce, or an empty list for none.  
`visible()`| `bool`| Optional| Runs each time the button's location loads, to decide whether the button is shown. Defaults to `True`. See Dynamic, state-responsive buttons.  
    ```python
        def visible(self) -> bool:
            """Only offer the button on an encounter note."""
            note_id = self.event.context.get("note_id")
            return Note.objects.filter(dbid=note_id, note_type_version__category="encounter").exists()
    ```
###  Button locations 
The `ActionButton` class defines several locations where the button can be placed. The location is defined using the `ButtonLocation` enum. Supported button locations include:
**Location**| **Description**  
---|---  
`NOTE_HEADER`| The button will appear in the header of each note.  
`NOTE_FOOTER`| The button will appear in the footer of each note.  
`NOTE_HEADER_DROPDOWN`| The button will appear in the note header dropdown.  
`CHART_PATIENT_HEADER`| The button will appear in the patient header on both the chart and profile pages.  
`CHART_SUMMARY_SOCIAL_DETERMINANTS_SECTION`| The button will appear in the Social Determinants section of the chart summary.  
`CHART_SUMMARY_GOALS_SECTION`| The button will appear in the Goals section of the chart summary.  
`CHART_SUMMARY_CONDITIONS_SECTION`| The button will appear in the Conditions section of the chart summary.  
`CHART_SUMMARY_MEDICATIONS_SECTION`| The button will appear in the Medications section of the chart summary.  
`CHART_SUMMARY_ALLERGIES_SECTION`| The button will appear in the Allergies section of the chart summary.  
`CHART_SUMMARY_CARE_TEAMS_SECTION`| The button will appear in the Care Teams section of the chart summary.  
`CHART_SUMMARY_VITALS_SECTION`| The button will appear in the Vitals section of the chart summary.  
`CHART_SUMMARY_IMMUNIZATIONS_SECTION`| The button will appear in the Immunizations section of the chart summary.  
`CHART_SUMMARY_SURGICAL_HISTORY_SECTION`| The button will appear in the Surgical History section of the chart summary.  
`CHART_SUMMARY_FAMILY_HISTORY_SECTION`| The button will appear in the Family History section of the chart summary.  
`CHART_SUMMARY_CODING_GAPS_SECTION`| The button will appear in the Coding Gaps section of the chart summary.  
`NOTE_BODY_AUTOMATION`| The button appears as an entry in the note body's "/" (slash) command list while a clinician documents a note.  
##  Dynamic, state-responsive buttons 
Action buttons are not rendered once and cached. Canvas re-evaluates every `ActionButton` handler each time its location loads — and again whenever the location is reloaded. On each evaluation Canvas fires the [`SHOW_*_BUTTON`](/sdk/events/#action-buttons-events) event for that location and your handler's `visible()` method decides whether the button is included.
This is what makes buttons _dynamic_ : because `visible()` runs against live data every time, the same button can appear, disappear, or change its title depending on the note, the patient, or the logged-in user.
###  Reading the runtime context 
Two different events reach an `ActionButton`, and they do not carry the same context. `visible()` runs on the [`SHOW_*_BUTTON`](/sdk/events/#action-buttons-events) event for the button's location, while `handle()` runs on `ACTION_BUTTON_CLICKED` once the button is clicked. Read both through `self.event`.
####  While deciding visibility 
What `visible()` sees depends on where the button lives:
Accessor| Note and header locations| Chart summary sections  
---|---|---  
`self.event.target.id`| The id of the patient the button is rendered for| The id of the patient  
`self.event.context["user"]`| The logged-in user, as `{"type": "Staff", "id": "<staff id>"}`| The same  
`self.event.context["note_id"]`| The **database id** of the note, or `None` on a location that has no note| Not present  
"Note and header locations" means `NOTE_HEADER`, `NOTE_FOOTER`, `NOTE_BODY`, `NOTE_BODY_AUTOMATION`, `NOTE_HEADER_DROPDOWN` and `CHART_PATIENT_HEADER`. Every `CHART_SUMMARY_*_SECTION` location gets the patient and the user only, because a chart summary is not rendered inside a note.
`note_id` is a database id rather than a UUID, so look the note up with `dbid`:
    ```python
        def visible(self) -> bool:
            note_id = self.event.context["note_id"]
            return Note.objects.filter(dbid=note_id, note_type_version__category="encounter").exists()
    ```
####  When the button is clicked 
Accessor| Value  
---|---  
`self.event.context["key"]`| The `BUTTON_KEY` of the button that was clicked. Canvas uses this to route the click, so `handle()` only runs for your own.  
`self.event.context["user"]`| The logged-in user, as `{"type": "Staff", "id": "<staff id>"}`  
`self.event.context["note_id"]`| The database id of the note the button was clicked from. Present only when the button lives on a note.  
`self.event.context["line_number"]`| The note body line the clinician typed the trigger on. Present only for a `NOTE_BODY_AUTOMATION` entry.  
`self.event.target.id`| The id of the patient the button was clicked from  
###  Reloading buttons 
Because visibility is computed from live data, Canvas needs to know _when_ to re-evaluate it. A button's location is reloaded automatically after its own `handle()` runs, but you will often want to reload in response to something else changing — for example, recomputing the footer after a command is committed, or after the note transitions to a new state.
Return one of these [Reload Action Buttons](/sdk/effect-reload-action-buttons/) effects (imported from `canvas_sdk.effects.action_button`) from any handler's `handle()` or `compute()` to refresh a location's buttons:
Effect| Re-evaluates  
---|---  
`ReloadNoteActionButtonsEffect(id=<note id>)`| Every button bound to that note  
`ReloadPatientActionButtonsEffect(id=<patient id>)`| Every button bound to that patient  
A reload re-fires the [`SHOW_*_BUTTON`](/sdk/events/#action-buttons-events) events, so every button recomputes `visible()` from scratch — the button set is rebuilt rather than patched. Any handler can emit a reload, not just an `ActionButton`; Example 4 below uses plain event handlers to keep the footer in sync as the note changes.
##  Note body automations 
A note body automation puts your plugin's own entry in the note body's "/" (slash) menu, the inline list clinicians use to insert commands while documenting a note. The location exists so an automation can come from a plugin rather than only from Canvas: one entry standing in for the several [commands](/sdk/commands/) a workflow would otherwise have the clinician insert by hand.
    ```python
    from canvas_sdk.commands import PlanCommand, TaskCommand
    from canvas_sdk.commands.commands.task import AssigneeType, TaskAssigner
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.batch_originate import BatchOriginateCommandEffect
    from canvas_sdk.handlers.action_button import ActionButton
    from canvas_sdk.v1.data.note import Note
    class LipidPanelAutomation(ActionButton):
        BUTTON_TITLE = "Order lipid panel follow-up"
        BUTTON_KEY = "LIPID_PANEL_AUTOMATION"
        BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_BODY_AUTOMATION
        def visible(self) -> bool:
            # Offer the entry only to the note's own provider.
            note_id = self.event.context.get("note_id")
            user_id = (self.event.context.get("user") or {}).get("id")
            if not note_id or not user_id:
                return False
            return Note.objects.filter(dbid=note_id, provider__id=user_id).exists()
        def handle(self) -> list[Effect]:
            note = Note.objects.filter(dbid=self.event.context["note_id"]).first()
            if note is None:
                return []
            plan = PlanCommand(
                note_uuid=str(note.id),
                narrative="Recheck lipid panel in 3 months",
            )
            task = TaskCommand(
                note_uuid=str(note.id),
                title="Call patient with lipid panel results",
                assign_to=TaskAssigner(to=AssigneeType.STAFF, id=note.provider.dbid),
            )
            # One batch, so both commands reach the note in a single update.
            return [
                BatchOriginateCommandEffect(
                    commands=[plan, task],
                    replace_line=True,
                ).apply()
            ]
    ```
It is an ordinary action button, with no separate automation class. Set `BUTTON_LOCATION` to `NOTE_BODY_AUTOMATION`, give it the usual `BUTTON_TITLE`, `BUTTON_KEY` and `PRIORITY`, and scope it with `visible()`. Canvas asks each plugin for its entries through the [`SHOW_NOTE_BODY_AUTOMATION_BUTTON`](/sdk/events/#action-buttons-events) event, whose context carries the signed-in staff member alongside the note and the patient, so an entry can be limited to particular staff as well as to particular notes or patients.
###  How Canvas renders the entry 
Behaviour| Detail  
---|---  
Position| After the native commands, ordered by `PRIORITY` then title  
Marker| A plug icon, which distinguishes it from Canvas's native automations  
When the list is built| Once, as the note loads, rather than on every keystroke  
Filtering| Client-side against `BUTTON_TITLE` as the clinician types  
The trigger line| Cleared as soon as the entry is selected, whatever `handle()` returns  
###  What `handle()` can return 
An entry is not limited to originating commands. `handle()` may return any effects, or none at all. What the location is meant for is the first row:
Returned from `handle()`| Where the commands land  
---|---  
A [`BatchOriginateCommandEffect`](/sdk/effect-batch-originate/) with `replace_line=True`| On the line the clinician typed the trigger on, replacing it, with no trailing trigger text or blank-line padding. Canvas supplies the position, so leave `line_number` unset.  
A `BatchOriginateCommandEffect` without `replace_line`| At the bottom of the note, from the effect's own `line_number=-1` default  
A single command's `originate()`| Wherever that effect places it. One command needs no batch  
Anything else, or nothing| Nothing is added to the note, and the trigger line is still cleared  
Reach for the batch whenever an entry originates **more than one** command. It updates the note body once for the whole group rather than once per command, which is faster and keeps the group together: separate originate effects each update the note on their own, so they can interleave with other writes and land out of order.
An entry does not have to write to the note at all. Because it is an ordinary action button, it can put any tool of yours behind the "/" menu, which is a shorter reach for a clinician mid-note than the app drawer. This one opens a risk calculator, and writes nothing:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.action_button import ActionButton
    from canvas_sdk.templates import render_to_string
    class AscvdRiskCalculator(ActionButton):
        BUTTON_TITLE = "ASCVD risk calculator"
        BUTTON_KEY = "ASCVD_RISK_CALCULATOR"
        BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_BODY_AUTOMATION
        def handle(self) -> list[Effect]:
            return [
                LaunchModalEffect(
                    target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
                    content=render_to_string("templates/ascvd_calculator.html"),
                    title="ASCVD risk",
                ).apply()
            ]
    ```
The clinician types `/`, picks the calculator, and it opens over the note. The trigger line is cleared either way, so the note is left exactly as it was.
##  Examples 
###  Log information when a button is clicked 
This example demonstrates a simple action button that logs some information when clicked. The button is visible only during the month of January.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.handlers.action_button import ActionButton
    from datetime import datetime
    from logger import log
    class MyButton(ActionButton):
        BUTTON_TITLE = "🪵 Log Action"
        BUTTON_KEY = "LOG_ACTION"
        BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_HEADER
        def visible(self) -> bool:
            # Only show this button in January
            return datetime.now().month == 1
        def handle(self) -> list[Effect]:
            log.info("Button clicked!")
            log.info(self.event.context)
            log.info(self.event.target)
            return []
    ```
###  Commit every command in a note 
This example adds a button to the note footer that commits every staged command in the note. The button is always visible, since it doesn't override `visible()`.
Rather than listing commands by hand, it builds each commit effect's name from the command's schema key, so it covers every command that has one. A few commands can't be committed this way and are skipped:
  - Prescribe, Refill, and Adjust Prescription, which a prescriber signs in Canvas
  - Imaging Order and Refer, which are signed with `sign()`
  - Reason for Visit, which is never committed
Commands that have no commit effect at all, such as custom commands and Chart Section Review, are skipped too.
    ```python
    import json
    import re
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.base import EffectType
    from canvas_sdk.handlers.action_button import ActionButton
    from canvas_sdk.v1.data.command import Command
    COMMIT_EFFECT_TYPES = {name for name in EffectType.keys() if name.startswith("COMMIT_")}
    NOT_COMMITTABLE = {
        "prescribe", "refill", "adjustPrescription", "imagingOrder", "refer", "reasonForVisit",
    }
    class CommitButtonHandler(ActionButton):
        BUTTON_TITLE = "Commit all commands"
        BUTTON_KEY = "COMMIT_ALL_COMMANDS"
        BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_FOOTER
        def handle(self) -> list[Effect]:
            note_id = self.context.get("note_id")
            effects = []
            for command in Command.objects.filter(note__dbid=note_id, state="staged"):
                if command.schema_key in NOT_COMMITTABLE:
                    continue
                # "changeMedication" becomes "COMMIT_CHANGE_MEDICATION_COMMAND"
                key = re.sub(r"(?<!^)(?=[A-Z])", "_", command.schema_key).upper()
                effect_name = f"COMMIT_{key}_COMMAND"
                if effect_name not in COMMIT_EFFECT_TYPES:
                    continue
                effects.append(
                    Effect(
                        type=EffectType.Value(effect_name),
                        payload=json.dumps({"command": str(command.id)}),
                    )
                )
            return effects
    ```
> **Info:** If you build a commit `Effect` yourself, as this example does, its payload key is `command`, not `command_uuid`. A command class's `.commit()` builds this payload for you.
###  Render HTML from a chart summary section 
In this example, we place a button in the Vitals section and define an action where the button, when clicked, displays custom HTML content to the user. For more info about `LaunchModalEffect`, check the [documentation](/sdk/layout-effect/#modals).
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.handlers.action_button import ActionButton
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from logger import log
    class VitalsButtonHandler(ActionButton):
        BUTTON_TITLE = "📊 Show Vitals Info"
        BUTTON_KEY = "SHOW_VITALS_INFO"
        BUTTON_LOCATION = ActionButton.ButtonLocation.CHART_SUMMARY_VITALS_SECTION
        def handle(self) -> list[Effect]:
            # This method will be called when the button is clicked
            log.info("Vitals info button clicked!")
            # Custom HTML content to display
            custom_html = """
            <div style="padding: 20px; background-color: #f0f8ff; border-radius: 5px;">
                <h3>Vitals Information</h3>
                <p>Patient's latest vitals data:</p>
                <ul>
                    <li>Heart Rate: 72 bpm</li>
                    <li>Blood Pressure: 120/80 mmHg</li>
                    <li>Respiratory Rate: 16 breaths/min</li>
                    <li>Temperature: 98.6°F</li>
                </ul>
                <p>For more details, please refer to the full report.</p>
            </div>
            """
            # Return a LaunchModalEffect to show the custom HTML content in a modal
            return [LaunchModalEffect(
                target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
                content=custom_html
            ).apply()]
        def visible(self) -> bool:
            # Optionally, make the button visible only under specific conditions
            return True
    ```
##  Note state action buttons 
`NoteStateActionButton` is a specialized `ActionButton` subclass for note footer buttons that transition a note from one state to another — locking, signing, pushing charges, deleting, and discharging, along with the appointment transitions check in, no show, cancel, and restore. It handles visibility, ordering, and the underlying state-transition effect for you, so a plugin can replace Canvas's default footer buttons with its own.
To create one, subclass `NoteStateActionButton` and set the `STATE_ACTION` class attribute to the target [`NoteStates`](/sdk/data-note/#notestates) value the button should transition the note into. Locking and signing carry extra rules, so the SDK also ships two ready-to-use subclasses — `LockNoteActionButton` and `SignNoteActionButton` — that you can register directly (or subclass) instead of setting `STATE_ACTION` yourself:
    ```python
    from canvas_sdk.handlers.action_button import (
        LockNoteActionButton,
        NoteStateActionButton,
        SignNoteActionButton,
    )
    from canvas_sdk.v1.data.note import NoteStates
    # Lock and Sign subclass the specialized bases — STATE_ACTION and their extra
    # rules are already set on those classes.
    class LockNoteButton(LockNoteActionButton):
        pass
    class SignNoteButton(SignNoteActionButton):
        pass
    # Every other transition subclasses NoteStateActionButton and sets STATE_ACTION.
    class UnlockNoteButton(NoteStateActionButton):
        STATE_ACTION = NoteStates.UNLOCKED
    class PushChargesNoteButton(NoteStateActionButton):
        STATE_ACTION = NoteStates.PUSHED
    class CheckInAppointmentButton(NoteStateActionButton):
        STATE_ACTION = NoteStates.CONVERTED
    class NoShowAppointmentButton(NoteStateActionButton):
        STATE_ACTION = NoteStates.NOSHOW
    class CancelAppointmentButton(NoteStateActionButton):
        STATE_ACTION = NoteStates.CANCELLED
    class RestoreAppointmentButton(NoteStateActionButton):
        STATE_ACTION = NoteStates.REVERTED
    class DeleteNoteButton(NoteStateActionButton):
        STATE_ACTION = NoteStates.DELETED
    class RestoreNoteButton(NoteStateActionButton):
        STATE_ACTION = NoteStates.UNDELETED
    class DischargeNoteButton(NoteStateActionButton):
        STATE_ACTION = NoteStates.DISCHARGED
    ```
Register each button as a handler in your `CANVAS_MANIFEST.json`, exactly like any other `ActionButton`.
Each button is configured automatically from its `STATE_ACTION`, so a subclass normally sets nothing else:
Attribute| Value  
---|---  
`BUTTON_LOCATION`| Always `NOTE_FOOTER`. Not overridable.  
`BUTTON_TITLE`| An imperative label for the target state, from the table below. Set it explicitly to override.  
`BUTTON_KEY`| `note_state_action__<state value>`, for example `note_state_action__LKD`. Set it explicitly to override.  
`visible()`| Implemented by the base class, which shows the button only when the transition is permitted. See Visibility.  
These are the supported transitions:
`STATE_ACTION`| Subclass| Default title| Default key  
---|---|---|---  
`NoteStates.LOCKED`| `LockNoteActionButton`| `Lock`| `note_state_action__LKD`  
`NoteStates.SIGNED`| `SignNoteActionButton`| `Sign`| `note_state_action__SGN`  
`NoteStates.UNLOCKED`| `NoteStateActionButton`| `Unlock`| `note_state_action__ULK`  
`NoteStates.PUSHED`| `NoteStateActionButton`| `Push charges`| `note_state_action__PSH`  
`NoteStates.DISCHARGED`| `NoteStateActionButton`| `Discharge`| `note_state_action__DSC`  
`NoteStates.DELETED`| `NoteStateActionButton`| `Delete`| `note_state_action__DLT`  
`NoteStates.UNDELETED`| `NoteStateActionButton`| `Restore`| `note_state_action__UND`  
`NoteStates.CONVERTED`| `NoteStateActionButton`| `Check in`| `note_state_action__CVD`  
`NoteStates.NOSHOW`| `NoteStateActionButton`| `No show`| `note_state_action__NSW`  
`NoteStates.CANCELLED`| `NoteStateActionButton`| `Cancel`| `note_state_action__CLD`  
`NoteStates.REVERTED`| `NoteStateActionButton`| `Restore`| `note_state_action__RVT`  
`Cancel` and `Restore` act on the note's appointment rather than on the note itself, so they do nothing on a note that has no appointment. `Sign` locks the note first when it is not already locked.
When a button is clicked, Canvas applies the transition's effect and reloads the footer so it reflects the note's new state.
###  Visibility 
A `NoteStateActionButton` appears only when its `STATE_ACTION` is a permitted transition from the note's current state and note type, so you don't need to override `visible()` yourself. When several are visible at once, Canvas orders them to match the order it offers the transitions for the current state.
Three buttons carry extra gates on top of that, which the base class applies for you:
Button| Also shown only when  
---|---  
`LockNoteActionButton`| The note type does **not** require a signature  
`SignNoteActionButton`| The note type **does** require a signature, and the current user has not signed since the last lock  
`Discharge`| The note type is an inpatient one  
Lock and Sign are the same underlying transition, split by whether the note type requires a signature. Because Sign hides itself only for the user who signed, a note can be signed by several users in turn, and it is re-locked only after an amend.
###  Replacing Canvas's default footer buttons 
Your state buttons appear _alongside_ Canvas's built-in state-transition buttons by default. To hide the native ones so yours replace them, answer the `NOTE_FOOTER__GET_CONFIGURATION` event with a [`NoteFooterConfiguration`](/sdk/effect-note-footer-configuration/) effect. Footer suppression is configured once per note (not per button):
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note_footer_configuration import NoteFooterConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class HideDefaultStateButtons(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.NOTE_FOOTER__GET_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [NoteFooterConfiguration(hide_default_state_buttons=True).apply()]
    ```
###  Customizing when a button appears 
Override `visible()` to layer your own rules on top of the built-in checks — call `super().visible()` first so you keep everything the base already enforces, then add your conditions. Subclassing `SignNoteActionButton` means `super().visible()` still applies the sign-specific rules (signature-required, lock-first, and already-signed). This Sign button additionally hides itself while the note has staged (uncommitted) commands, because a note can't be signed until its commands are committed (reason-for-visit is auto-managed and doesn't block signing, so it's excluded):
    ```python
    from canvas_sdk.handlers.action_button import SignNoteActionButton
    from canvas_sdk.v1.data.command import Command
    class SignNoteButton(SignNoteActionButton):
        def visible(self) -> bool:
            if not super().visible():
                return False
            note_id = self.event.context.get("note_id")
            return not (
                Command.objects.filter(note_id=note_id, state="staged")
                .exclude(schema_key="reasonForVisit")
                .exists()
            )
    ```
You can gate on anything in the runtime context. For example, to show a button only to the note's provider, compare the logged-in user against the note's provider (`note.provider.id` and the user id are both Staff ids):
    ```python
        def visible(self) -> bool:
            if not super().visible():
                return False
            note_id = self.event.context.get("note_id")
            user_id = (self.event.context.get("user") or {}).get("id")
            if not note_id or not user_id:
                return False
            return Note.objects.filter(dbid=note_id, provider__id=user_id).exists()
    ```
###  Keeping the footer in sync 
`visible()` is only re-evaluated when the footer is reloaded. A transition triggered by one of these buttons reloads the footer automatically, but changes from elsewhere don't — so pair the buttons with handlers that reload the footer when the note changes by another path. For example, reload whenever a command is committed (so the Sign button reappears the instant the last command is committed) and whenever the note's state changes:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.action_button import ReloadNoteActionButtonsEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.command import Command
    class ReloadFooterOnCommandCommit(BaseHandler):
        """Reload the footer whenever any command is committed."""
        RESPONDS_TO = [
            EventType.Name(value)
            for value in EventType.values()
            if EventType.Name(value).endswith("_COMMAND__POST_COMMIT")
        ]
        def compute(self) -> list[Effect]:
            command = Command.objects.filter(id=self.event.target.id).first()
            if not command or not command.note:
                return []
            return [ReloadNoteActionButtonsEffect(id=str(command.note.id)).apply()]
    class ReloadFooterOnNoteStateChange(BaseHandler):
        """Reload the footer whenever the note transitions to a new state."""
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self) -> list[Effect]:
            note_id = self.event.context.get("note_id")
            if not note_id:
                return []
            return [ReloadNoteActionButtonsEffect(id=note_id).apply()]
    ```
##  Reference plugin 
A complete, working plugin that ties these patterns together is available as the [**note-lifecycle-example**](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/note-lifecycle-example) plugin. It demonstrates:
  - a full set of state-responsive footer buttons (Lock, Sign, Unlock, Push charges, Check in, No show, Cancel, Restore, Delete, Discharge), each appearing only when its transition is valid from the note's current state — Lock and Sign built on `LockNoteActionButton` and `SignNoteActionButton`, the rest on `NoteStateActionButton`;
  - a `HideDefaultStateButtons` handler that hides Canvas's native footer buttons so the plugin's buttons replace them;
  - `ReloadFooterOnCommandCommit` and `ReloadFooterOnNoteStateChange` handlers that keep the visible button set in sync as the note evolves.
Use it as a starting point for your own footer.

---

# Applications

Source: https://docs.canvasmedical.com/sdk/handlers-applications/

Applications put your own tools inside Canvas, so staff and patients can use them without leaving the workflow they're in. An application can be a dashboard, a form, a third-party tool loaded in an iframe, or a full page you build in your plugin.
Applications can show up wherever they fit the work:
  - In the app drawer, on a patient's chart or across Canvas
  - As a tab in the patient chart, next to Chart and Profile
  - In the provider menu
  - In the patient portal menu, for patients
  - In the [Provider Companion](/sdk/companion/)
An application opens your content when a user selects it, and it can show a notification badge to flag what's waiting. Its scope decides where it appears.
##  Implementing an Application 
To add an application, create a handler class that inherits from `Application`, then register it in your manifest.
###  Methods 
  - **`on_open()`** (required) runs when a user opens the application. It usually returns a [`LaunchModalEffect`](/sdk/layout-effect/#modals) with a `url` to load in an iframe or `content` to render directly. Set a `title` so users can recognize the application when it's minimized. Return one `Effect` or a list of them.
  - **`on_context_change()`** (optional) runs when the user moves to another page while the application is open. Return an `Effect`, a list of them, or `None` to do nothing. See Context Change Events for when it fires and what it receives.
###  Opening for the current patient 
When an application opens on a patient chart, `on_open()` can read the current patient from `self.context`, which looks like `{'patient': {'id': '24cfe22ecf74420fb82dc40e44ca6166'}}`. Use it to open your application for that patient:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class MyApplication(Application):
        """An embeddable application that can be registered to Canvas."""
        def on_open(self) -> Effect:
            """Handle the on_open event."""
            patient_id = self.context['patient']['id']
            patient_specific_url = f"https://example.com/patient-specific-application?patient={patient_id}"
            return LaunchModalEffect(
                url=patient_specific_url,
                target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
            ).apply()
    ```
###  Registering the application 
Your [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#applications) must also describe the application. Reference your class in the "applications" section of the components so your application is registered in the app drawer on plugin installation.
This is also where you can define the title and icon that displays your app in the app drawer. The icon will be rendered at 48px by 48px, so should be square and simple enough to not lose detail at that size.
###  Example 
This application opens in the right chart pane and reloads with claim or queue details as the user moves through revenue pages:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class IFrameApp(Application):
        def on_open(self) -> Effect | list[Effect]:
            return LaunchModalEffect(url=f"https://www.your-iframe-app.com",
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE, title="Your Iframe App").apply()
        def on_context_change(self) -> Effect | list[Effect] | None:
            # Access the current URL that triggered the context change
            current_url = self.event.context.get("url", "")
            # Handle claim-specific context
            if claim := self.event.context.get("claim"):
                claim_id = claim["id"]
                return LaunchModalEffect(
                    url=f"https://www.your-iframe-app.com?claim_id={claim_id}&source_url={current_url}",
                    target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
                    title=f"Your Iframe App - Claim {claim_id}"
                ).apply()
            # Handle queue-specific context
            if queue := self.event.context.get("claim_queue"):
                queue_id = queue["dbid"]
                return LaunchModalEffect(
                    url=f"https://www.your-iframe-app.com?queue_id={queue_id}&source_url={current_url}",
                    target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
                    title=f"Your Iframe App - Queue {queue_id}"
                ).apply()
            # Handle general revenue page context
            if current_url.startswith("/revenue"):
                return LaunchModalEffect(
                    url=f"https://www.your-iframe-app.com?page=revenue&source_url={current_url}",
                    target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
                    title="Your Iframe App - Revenue"
                ).apply()
            # Return None when no relevant context - this will result in an empty effect list
            return None
    ```
##  Context Change Events 
Context change events are automatically triggered when users navigate between different URLs within Canvas. This feature allows your applications to react dynamically to the user's current context, providing relevant information and functionality based on where they are in the system.
###  Event Triggers 
Context change events are currently supported for revenue workflows and are triggered when:
  - A user navigates to a different URL within Canvas
  - The application is already open and running
  - The new URL is within the `/revenue` namespace
###  Context Data Structure 
When a context change event occurs, your `on_context_change()` method receives contextual information through `self.event.context`:
    ```python
    {
        "url": "/revenue/claims/123",           # Current URL that triggered the event
        "patient": {"id": "patient_key"},       # Patient information (when applicable)
        "user": {...},                          # User information
        "claim": {"id": "external_claim_id"},   # Claim context (for /revenue/claims/<id>)
        "claim_queue": {"dbid": "queue_id"}     # Queue context (for /revenue/queues/<id>)
    }
    ```
###  Supported URL Patterns 
URL Pattern| Context Provided| Description  
---|---|---  
`/revenue`| Base context only| General revenue page  
`/revenue/claims/<id>`| `claim` object with externally exposable ID| Specific claim details page  
`/revenue/queues/<id>`| `claim_queue` object with database ID| Specific queue management page  
###  Best Practices 
  1. **Always check for context existence** : Use safe dictionary access patterns to avoid KeyErrors
  2. **Handle multiple context types** : Your application may receive different types of context based on the URL
  3. **Return None appropriately** : When no relevant action is needed, return None to avoid unnecessary effects
###  Advanced Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class AdvancedRevenueApp(Application):
        def on_open(self) -> Effect | list[Effect]:
            return LaunchModalEffect(
                url="https://www.your-app.com/dashboard",
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
                title="Revenue Analytics"
            ).apply()
        def on_context_change(self) -> Effect | list[Effect] | None:
            current_url = self.event.context.get("url", "")
            patient = self.event.context.get("patient", {})
            user = self.event.context.get("user", {})
            # Build base parameters
            params = {
                "source_url": current_url,
                "user_id": user.get("id", ""),
                "patient_id": patient.get("id", "")
            }
            # Handle specific contexts
            if claim := self.event.context.get("claim"):
                params["claim_id"] = claim["id"]
                params["view"] = "claim_details"
                title = f"Revenue Analytics - Claim {claim['id']}"
            elif queue := self.event.context.get("claim_queue"):
                params["queue_id"] = queue["dbid"]
                params["view"] = "queue_management"
                title = f"Revenue Analytics - Queue {queue['dbid']}"
            elif current_url.startswith("/revenue"):
                params["view"] = "revenue_overview"
                title = "Revenue Analytics - Overview"
            else:
                # No relevant context for this application
                return None
            # Build query string
            query_string = "&".join(f"{k}={v}" for k, v in params.items() if v)
            return LaunchModalEffect(
                url=f"https://www.your-app.com/revenue?{query_string}",
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
                title=title
            ).apply()
    ```
##  Application Scopes 
The `scope` attribute determines where your application is visible within Canvas. The following scopes are available:
Scope| Description  
---|---  
`patient_specific`| Visible only within a patient's chart in the app drawer  
`global`| Visible outside of patient charts in the app drawer  
`full_chart`| Displayed as a tab in the patient chart navigation menu alongside Chart and Profile  
`provider_menu_item`| Displayed as a menu item in the provider menu  
`portal_menu_item`| Displayed as a menu item in the patient portal  
`provider_companion`| Visible on the [Provider Companion](/sdk/companion/) main page (legacy, use `provider_companion_global` for new apps)  
`provider_companion_global`| In the app launcher on the [Provider Companion](/sdk/companion/) main page  
`provider_companion_patient_specific`| As a tab on a patient's page in the [Provider Companion](/sdk/companion/)  
`provider_companion_note_specific`| As a tab within an opened note in the [Provider Companion](/sdk/companion/)  
###  Who sees an application 
Applications in the `global`, `patient_specific`, and `provider_menu_item` scopes are shown to every staff member, and `portal_menu_item` applications are shown to every patient in the patient portal. To limit what a user can do, check who opened the application in `on_open()`, using the user in `self.event.context`, and show a message instead of the content when that user shouldn't have access.
When a patient opens a `portal_menu_item` application, the event context identifies them only through `user`, for example `{"type": "Patient", "id": "..."}`. Canvas sets `url` to `None` and leaves out `patient` and other page context, so use the `user` ID to look up the patient's records.
###  Linking to a portal application 
A `portal_menu_item` application's URL ends in its identifier, base64-encoded. For example, `.../app/application/cGF0aWVudF9wb3J0YWxfY29uc2VudF9mb3Jtcy4uLg==` decodes to `plugin_name.module.path:ClassName`. Because the identifier is made of the plugin name, module path, and class name, renaming any of them changes the URL and breaks links to it. The browser's address bar also stays the same as the patient moves between applications.
To send a patient to a portal application from a plugin, return a [`RedirectEffect`](/sdk/effect-redirect/#redirects-in-the-patient-portal) with the application's `application_id` instead of building its URL. A redirect to an `/app/application/...` URL is blocked.
###  Full Chart Scope 
Applications with the `full_chart` scope appear as navigation tabs at the top of the patient chart, alongside the default "Chart" and "Profile" tabs. This is ideal for building comprehensive patient-level views or dashboards.
    ```json
    {
      "class": "my_plugin.apps.analytics:PatientAnalytics",
      "name": "Analytics",
      "description": "Patient analytics dashboard",
      "icon": "/assets/analytics-icon.png",
      "scope": "full_chart"
    }
    ```
A `full_chart` application is also the way to give custom patient data its own layout. The [patient metadata form](/sdk/patient-metadata-create-form-effect/) shows fields as one flat list in the profile, with no sections or headings. To group fields your own way, build the form in a `full_chart` application and save the values with the [patient metadata effect](/sdk/effect-patient-metadata/) from a [SimpleAPI](/sdk/handlers-simple-api-http/) endpoint, so they're stored the same way.
##  Provider Companion Applications 
Provider companion applications run in the Canvas provider companion — a mobile-optimized, provider-facing surface. They use the `Application` handler with one of three companion scopes (`provider_companion_global`, `provider_companion_patient_specific`, `provider_companion_note_specific`) declared in the manifest. The legacy `provider_companion` scope continues to work and is treated the same as `provider_companion_global`.
See [Provider Companion](/sdk/companion/) for the full guide — scope-by-scope examples, event context, code sharing across scopes, originating commands from a note, modal dismissal, and mobile UX guidance.
##  Embedded Applications 
**Embedded applications** are handler-based applications that render inside a specific Canvas surface rather than appearing in the app drawer. There are five kinds:
  - Note Applications, which add tabs inside a note
  - Scheduling Applications, which replace the built-in scheduling modal
  - Docked Applications, which pin a persistent pane to a window edge
  - Provider Menu Applications, which add an entry to the provider side menu
  - Panel Applications, which add an icon to the panel bar
They are declared under `handlers` (not `applications`), take no `scope`, and create no application record. A `ProviderMenuApplication` is separate from a drawer application that uses the `provider_menu_item` scope, and a `PanelApplication` is separate from a drawer application shown with `show_in_panel`; each pair can coexist.
See [Embedded Applications](/sdk/handlers-embedded-applications/) for the full guide.
##  Panel Display 
If you want to increase your application's visibility and display it alongside other panel buttons (instead of in the applications drawer), you can add the `show_in_panel` attribute. If you've added more than one application to that panel, you can set their priorities using the `panel_priority` attribute. A panel icon has no label, so Canvas shows the application's `name` in a tooltip when a user hovers over the icon.
For security reasons you also need to specify the domains that will be loaded within the iframe, or they will not be rendered. For more info on the format of the `url_permissions` field, check the [Additional Configuration](/sdk/layout-effect/#additional-configuration) for `LaunchModalEffect`.
Here's what your `CANVAS_MANIFEST.json` might look like:
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "0.0.1",
      "name": "my_application",
      "description": "This is a very nice application",
      "url_permissions": [
        {
          "url": "https://example.com/",
          "permissions": ["ALLOW_SAME_ORIGIN", "MICROPHONE", "SCRIPTS", "CAMERA", "CLIPBOARD_READ", "CLIPBOARD_WRITE"]
        }
      ],
      "components": {
        "handlers": [],
        "applications": [
          {
            "class": "my_application.apps.iframe:IFrameApp",
            "name": "My Application",
            "description": "Test App for patients",
            "icon": "/assets/cappuccino.png",
            "scope": "patient_specific",
            "show_in_panel": true,
            "panel_priority": 100
          }
        ],
        "commands": [],
        "content": [],
        "effects": [],
        "views": []
      },
      "variables": [],
      "tags": {},
      "references": [],
      "license": "",
      "diagram": false,
      "readme": "./README.md"
    }
    ```
##  Installing and updating applications 
When you install or upgrade a plugin, Canvas reconciles its applications to match `CANVAS_MANIFEST.json`. Canvas creates each application declared under `components.applications` that is new and updates each one that already exists. Canvas removes any registered application that the manifest no longer declares. The removed application's entry disappears from the app drawer and from any menu it appeared in, such as the provider menu, and its stored icon is deleted.
Reconciliation affects only the plugin being installed. Applications that belong to other plugins are left unchanged.
An application's identity is its `class` value, the `module:ClassName` string, and Canvas matches applications by `class` during reconciliation:
  - Editing only display fields (`name`, `description`, `icon`, `scope`, and so on) while keeping the same `class` updates the existing application in place.
  - Changing the `class` value, by editing either the module path or the class name, removes the old application and adds a new one rather than updating the existing application in place.
> **Note:** Per-application instance settings such as Open on load attach to a specific application. Because changing an application's `class` creates a new application, those settings do not carry over to the new application.
Application changes apply together with the plugin's other install or upgrade changes, such as commands and questionnaires, as a single all-or-nothing operation, so if an install fails, the plugin's applications are left unchanged.
##  Opening an Application on Load 
You can configure an application to open **automatically** , without the user clicking its icon, by enabling the **Open on load** setting for that application in your instance settings.
To enable it, go to the Plugins_IO > Applications section of your instance settings (`/admin/plugin_io/application/`), open the application you want, check **Open on load** , and save. If you don't have access to this setting, reach out to Canvas Support.
Behavior depends on the application's scope:
Scope| When it opens  
---|---  
`global`| Automatically when the app shell first loads.  
`patient_specific`| Automatically when a patient chart is opened.  
This is an instance-level setting configured per application in your instance settings. It is **not** part of `CANVAS_MANIFEST.json`, so the value you set is preserved when the plugin is reinstalled or updated.
> **Warning:** **Enable Open on load for at most one application per scope.** There is no priority or ordering logic for this setting, and no constraint preventing multiple applications in the same scope from being flagged. If more than one application in the same scope (for example, two `patient_specific` apps) has Open on load enabled, all of them will attempt to open, resulting in unpredictable behavior. Make sure only one application per scope is set to open on load.
> **Note:** This is distinct from a Note Application's [`open_by_default()`](/sdk/handlers-embedded-applications/#opening-by-default), which controls which **tab** is active when a note is viewed. **Open on load** controls whether a `global` or `patient_specific` application opens automatically on app/chart load.
##  Notification Badges 
You can display a notification badge — a small count — on an application in these scopes:
  - `global` and `patient_specific`: on the icon in the app drawer, or on the panel when a `patient_specific` application sets `show_in_panel`.
  - `provider_menu_item`: next to the label in the provider menu.
  - `portal_menu_item`: next to the label in the patient portal menu.
A badge is useful for surfacing how many items are waiting for attention, such as unread messages or open tasks. Applications in other scopes (`full_chart` and the Provider Companion scopes) do not display badges.
###  Initial count on load 
Override `compute_notification_badge()` on your `Application` handler to provide the count shown when Canvas loads applications. Return an integer to show a badge, or `None` (the default) to show no badge. A count of `0` shows no badge.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    from canvas_sdk.v1.data.task import Task, TaskStatus
    class InboxApp(Application):
        def on_open(self) -> Effect | list[Effect]:
            return LaunchModalEffect(
                url="https://www.your-app.com/inbox",
                title="Inbox",
            ).apply()
        def compute_notification_badge(self) -> int | None:
            """Return the badge count shown on the icon when applications load."""
            staff_id = self.event.context.get("staff", {}).get("id")
            if not staff_id:
                return None
            return Task.objects.filter(assignee__id=staff_id, status=TaskStatus.OPEN).count()
    ```
When the application is rendered on a patient chart (`patient_specific` scope), the event context also carries the patient, so you can compute a count specific to the staff member _and_ the patient they are viewing:
    ```python
    from canvas_sdk.v1.data.task import Task, TaskStatus
    def compute_notification_badge(self) -> int | None:
        staff_id = self.event.context.get("staff", {}).get("id")
        patient_id = self.event.context.get("patient", {}).get("id")
        if not (staff_id and patient_id):
            return None
        return Task.objects.filter(
            assignee__id=staff_id, patient__id=patient_id, status=TaskStatus.OPEN
        ).count()
    ```
For a `portal_menu_item` application, the count is computed for the patient logged in to the portal. The event context carries that patient and no staff member:
    ```python
    from canvas_sdk.v1.data.task import Task, TaskStatus
    def compute_notification_badge(self) -> int | None:
        patient_id = self.event.context.get("patient", {}).get("id")
        if not patient_id:
            return None
        return Task.objects.filter(patient__id=patient_id, status=TaskStatus.OPEN).count()
    ```
The badge event context contains:
Key| Description  
---|---  
`staff`| A dict with the staff `id` and `type` (present for staff-facing apps).  
`patient`| A dict with the patient `id` and `type` (present on a patient chart, and in the patient portal for the logged-in patient).  
> **Note:** Note Applications (`NoteApplication`) do not support notification badges.
###  Live updates 
To change the count after load — for example, in response to a new task or message — emit an `ApplicationNotificationBadge` effect from any event handler. The badge updates in real time without the user reloading the page. See the [Application Notification Badge](/sdk/effect-application-notification-badge/) effect for details.
##  Limitations and patterns 
###  Third-party scripts only run inside a plugin iframe 
Canvas does not provide a way to inject application-wide JavaScript (for example, Segment or Sentry snippets) into the Canvas front end. Third-party scripts can only run inside the iframe of a plugin's own application.
###  Application iframes and cookies 
An application iframe can use cookies for its own domain only when its URL's entry in [`url_permissions`](/sdk/canvas_manifest/#url-permissions) includes `ALLOW_SAME_ORIGIN`. Without it, each launch behaves like an incognito session, so a user may have to sign in to your application every time it opens.
###  Replacing a built-in view 
When a built-in Canvas view doesn't fit a workflow, an application can replace it with your own, built from the same data and actions the SDK exposes. Read what you need with the [data module](/sdk/data/), make changes with [effects](/sdk/effects/) returned from a [SimpleAPI](/sdk/handlers-simple-api-http/) endpoint in the same plugin, and lay out the page however the workflow needs.
For example, to present tasks with locked fields, predefined dropdowns, or custom labels beyond what the built-in Task command offers, build an application that opens on the right side of a note. Read tasks with the [Task](/sdk/data-task/) data model, and create or update them with the [task effects](/sdk/effect-tasks/). Give these tasks a label of their own so your application can find them and staff can filter them out of the general Tasks list.

---

# Base Handler

Source: https://docs.canvasmedical.com/sdk/handlers-basehandler/

The `BaseHandler` is the simplest of all handlers. Specify which events you are interested in, then provide the code to execute when one of those events is emitted. All the [handlers](/sdk/handlers/) inherit from `BaseHandler`, and many of yours will too.
> **Danger:** **With great power comes great responsibility.** Your handler runs **synchronously** inside a worker. Slow handler code — especially code that makes a blocking network call to an external service (an LLM API, a third-party HTTP endpoint) — holds that worker for its entire duration. If the external service slows down or goes offline, every invocation piles up until the worker pool is exhausted, and your **entire Canvas instance can be negatively impacted or even temporarily stop responding to requests**. Long timeouts and retries multiply the damage: a 300 second timeout retried three times pins a single worker for over ten minutes. Keep your handler fast, and move long-running or failure-prone work off the synchronous path — see [Keep your handler fast](/sdk/handlers-basehandler/#keep-your-handler-fast).
##  Handling Events With `BaseHandler`
To create a class that responds to one or more events, inherit from `BaseHandler`, set the `RESPONDS_TO` constant, and implement the `compute()` method.
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class MyEventHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.TASK_CREATED)
        def compute(self):
            # Your code goes here!
            return []
    ```
You can respond to one event, or several. To respond to multiple events, set `RESPONDS_TO` to a list of [event types](/sdk/events/).
    ```python
    # Respond when tasks are created:
    RESPONDS_TO = EventType.Name(EventType.TASK_CREATED)
    # Respond when tasks are created OR updated:
    RESPONDS_TO = [
        EventType.Name(EventType.TASK_CREATED),
        EventType.Name(EventType.TASK_UPDATED),
    ]
    ```
The `compute()` method must return a list of [Effects](/sdk/effects/). That list can be empty, of course. You have access to event information with `self.event`, `self.target`, and`self.context`, as well as configuration information for your plugin with `self.secrets` and for the running instance with `self.environment`. You can use our [Data Module](/sdk/data/) to retrieve additional information at runtime.
##  Keep your handler fast 
Your handler's entry point — `compute()` here, or `handle()` for an [Action Button](/sdk/handlers-action-buttons/) — runs synchronously on a bounded pool of plugin workers that is shared across your whole Canvas instance. Whatever you do inside it occupies one of those workers until it returns. Fast handlers free their worker in milliseconds; slow handlers hold it, and a handler that blocks on a slow or unavailable external dependency holds it for a long time. When enough handlers are blocked at once, the pool is exhausted and the instance can no longer respond to requests — providers experience this as the entire application becoming inaccessible, not just your plugin.
This matters most when your handler responds to a high-frequency event (for example, a note-state-change or task event that fires throughout the day) and does work that can hang:
  - **Calls to external HTTP APIs** , including LLM providers. These are the most common cause of instance-wide slowdowns, because a single provider-side outage turns every one of your handler invocations into a multi-second (or multi-minute) hang at the same time.
  - **Long timeouts combined with retries.** A 300 second timeout retried a few times can pin one worker for over ten minutes per event.
  - **Inefficient database queries.** Unbounded result sets, N+1 query patterns, and missing `select_related`/`prefetch_related` turn a fast-looking handler into a slow one as a patient's or instance's data grows. Filter and paginate with the [Data Module](/sdk/data/), fetch only the fields you need, and follow foreign keys with `select_related`/`prefetch_related` instead of looping.
  - **Heavy synchronous computation** that doesn't yield.
###  Move slow work off the synchronous path 
The platform can run effects asynchronously so they don't block the event that produced them:
  - Chain [`.set_async()`](/sdk/effects/#async-execution) on any effect to have the platform run it as a deferred task, with optional delay and retries. This is the right tool for **fire-and-forget side effects** (kick off a webhook, schedule a downstream write).
  - Use the [`HttpRequestEffect`](/sdk/effect-http-request/) to have the platform make an HTTP call on your behalf — chained with `.set_async()` so the platform's async runner manages the delay, retries, and backoff instead of your handler blocking on the network.
Note that `set_async()` defers _effects_ , not `compute()` itself — `compute()` always runs synchronously. A raw blocking call made _inside_ `compute()` (for example, a `requests.post(...)` directly to a third-party API) still pins the worker, regardless of whether the effects you return are async. If your handler needs to "call an external service, read the result, then decide what to do," decompose it: a thin synchronous handler that emits an async effect to a [SimpleAPI](/sdk/handlers-simple-api/) callback route, and let that route do the slow work off the event path and apply its effects when it finishes.
If you genuinely cannot move the work off the synchronous path, at minimum cut the reach of a failure: use a short timeout, limit retries, and gate the handler so it only runs for the cases that truly need it.

---

# CronTask

Source: https://docs.canvasmedical.com/sdk/handlers-crontask/

You can write a handler that subclasses `CronTask` to execute code on a schedule. You might use this to automate reporting on task performance (every hour, send the number of tasks created during the previous hour, and the number of tasks completed during the previous hour), to send birthday wishes to your patients (at 7am every morning, find patients born on this day and send them an email wishing them a happy birthday), or to send customized appointment reminders (every hour, find appointments that start on this hour the following day and send the patients of those appointments a message that says "Dr. X is looking forward to seeing you at (location) at (time)").
##  Example 
This example `CronTask` shows an extremely basic example that just logs the time. You can see the critical pieces here:
  - Subclass `CronTask`
  - Set your `SCHEDULE` with a cron string
  - Implement an `execute` method with the code you want to schedule to run, returning a list containing any effects you want to return, or an empty list if you do not wish to return any effects.
    ```python
    from canvas_sdk.handlers.cron_task import CronTask
    from canvas_sdk.effects import Effect
    from logger import log
    class LogTheTime(CronTask):
        # A cron string.
        #           ┌───────────── minute (0 - 59)
        #           │ ┌───────────── hour (0 - 23)
        #           │ │ ┌───────────── day of the month (1 - 31)
        #           │ │ │ ┌───────────── month (1 - 12)
        #           │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
        #           │ │ │ │ │
        #           │ │ │ │ │
        #           │ │ │ │ │
        SCHEDULE = "* * * * *"  # Run every minute, which is the most frequently something can run.
        def execute(self) -> list[Effect]:
            # The current timestamp can be found as an iso8601 string in
            # `self.target`
            log.info(f"The current time is {self.target}")
            # We don't need to return any effects
            return []
    ```
###  Output 
Here's what this scheduled task would output in the logs:
`INFO 2024-07-18 18:47:00,000 The current time is 2024-07-18T18:47:00.000000+00:00`

---

# Embedded Applications

Source: https://docs.canvasmedical.com/sdk/handlers-embedded-applications/

Each embedded application belongs to **a specific Canvas surface** , such as a note, the scheduling modal, or the provider side menu. Embedded applications are ordinary [handlers](/sdk/handlers-basehandler/). You subclass a base class, register it under `handlers` in your [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#handlers), and Canvas renders it in the appropriate surface.
There are five kinds:
Base class| Surface  
---|---  
`NoteApplication`| A tab within a patient's note  
`SchedulingApplication`| Replaces the built-in scheduling modal at every entry point  
`DockedApplication`| A persistent pane pinned to a window edge, always visible  
`ProviderMenuApplication`| An entry in the provider side menu (the navigation sidebar, also called the hamburger menu)  
`PanelApplication`| An entry in the panel bar or the app drawer  
##  How embedded applications work 
Embedded applications are [handlers](/sdk/handlers-basehandler/). You build one by subclassing one of the base classes above and registering it under `handlers` in your `CANVAS_MANIFEST.json`. The surface comes from that parent class.
Because the parent class defines the behavior, there's very little to configure:
  - The **surface** comes from the class you inherit. You don't set a `scope`. The provider menu and the panel bar each take a few extra class attributes, such as an icon URL, described in their own sections below.
  - When Canvas renders each kind:
    - **Note and Scheduling Applications** render on demand. When a note opens or a scheduling action is triggered, Canvas asks which embedded application is installed for that surface, then renders what your handler returns.
    - **Docked Applications** stay mounted at all times.
    - **Provider Menu and Panel Applications** are fetched when their menu loads and refreshed as the user navigates.
  - Embedded applications create no application record, so they don't appear under Plugins_IO > Applications.
  - Only a Panel Application can appear in the app drawer, as described in Panel Applications.
  - If no embedded application is installed for a surface, Canvas falls back to its built-in behavior: an unmodified note, or the built-in scheduling modal.
Since the surface is inherited from the parent class, register these under `handlers` rather than `applications`.
##  Note Applications 
Note Applications appear as tabs within a patient's note, allowing you to embed custom interfaces directly in the clinical documentation workflow.
###  Implementing a Note Application 
To create a Note Application, your handler class should inherit from `NoteApplication` and define the following class attributes:
Attribute| Description  
---|---  
`NAME`| (Required) The display title shown on the tab (supports emojis)  
`IDENTIFIER`| (Required) A unique key for the application (recommended format: `plugin_name__app_name`)  
`PRIORITY`| (Optional) Controls tab order — lower values appear first. Defaults to `0`  
> **Tip:** If your Note Application is named "Note", it may cause confusion with the built-in Note tab. Users can rename the built-in tab by updating the Constance Config setting `NOTE_BODY_TAB_LABEL` in your instance Settings, to avoid duplication.
Your class must implement the `on_open()` method, which is called when the user clicks on the tab. This method should return an `Effect` or list of `Effect`s, typically a `LaunchModalEffect` with `target` set to `LaunchModalEffect.TargetType.NOTE`
> **⚠️ Important** If you have an existing plugin that overrides `handle()`, it will continue to work. However, `handle()` is deprecated — migrate to `on_open()` at your earliest convenience.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import NoteApplication
    class PatientIntakeApp(NoteApplication):
        """Note application for patient intake workflow."""
        NAME = "📋 Patient Intake"
        IDENTIFIER = "my_plugin__patient_intake"
        def on_open(self) -> Effect | list[Effect]:
            """Launch the intake form when the tab is clicked."""
            note_id = self.event.context.get("note_id")
            patient_id = self.event.context.get("patient", {}).get("id")
            return LaunchModalEffect(
                target=LaunchModalEffect.TargetType.NOTE,
                content="<html>Your form HTML here</html>",
                title="Patient Intake Form"
            ).apply()
    ```
![note applications](/assets/images/note-application-tabs.png)
###  Manifest Configuration 
Register your Note Application under the `handlers` section of your `CANVAS_MANIFEST.json`. There is no `scope` or `icon` — the note tab is driven by the `NoteApplication` base class and the `NAME`/`IDENTIFIER` class attributes.
    ```json
    {
      "components": {
        "handlers": [
          {
            "class": "my_plugin.apps.intake:PatientIntakeApp",
            "description": "In-note patient intake tab."
          }
        ]
      }
    }
    ```
###  Context and Event Data 
Both `on_open()` and `handle()` have access to context data through `self.event.context`:
Key| Description  
---|---  
`note_id`| The database ID of the current note  
`note`| A dict containing the note's external `id` (UUID)  
`patient`| A dict containing the patient's `id`  
`user`| Information about the current user  
####  `on_open()` — recommended 
When using `on_open()`, the patient is available through `self.event.context`:
    ```python
    from canvas_sdk.effects import Effect
    def on_open(self) -> Effect | list[Effect]:
        note_id = self.event.context.get("note_id")
        patient_id = self.event.context.get("patient", {}).get("id")
        ...
    ```
`self.event.target.id` contains the application identifier used internally for routing, not the patient.
####  `handle()` — deprecated 
When using the deprecated `handle()`, `self.event.target.id` is automatically set to the patient UUID before `handle()` is called, preserving the original behavior that old plugins relied on:
    ```python
    from canvas_sdk.effects import Effect
    def handle(self) -> list[Effect]:
        patient_id = self.event.target.id  # backfilled from patient context
        ...
    ```
> **Note:** This backfilling only happens when `handle()` is called. Plugins that override `on_open()` directly should read the patient from `self.event.context` as shown above.
Property| `on_open()`| `handle()` (deprecated)  
---|---|---  
`self.event.target.id`| Application identifier (for routing)| Patient UUID (backfilled)  
`self.event.context["patient"]["id"]`| Patient UUID| Patient UUID  
`self.event.actor`| Authenticated user| Authenticated user  
###  Controlling Visibility 
You can control when your Note Application tab is visible by overriding the `visible()` method. This method has access to the same context and event data as `on_open()`:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import NoteApplication
    class ConditionalIntakeApp(NoteApplication):
        NAME = "📋 Intake"
        IDENTIFIER = "my_plugin__conditional_intake"
        def visible(self) -> bool:
            """Only show for specific conditions."""
            # Add your visibility logic here
            return True
        def on_open(self) -> Effect | list[Effect]:
            return LaunchModalEffect(
                target=LaunchModalEffect.TargetType.NOTE,
                content="<html>Form content</html>",
                title="Intake"
            ).apply()
    ```
###  Opening by Default 
You can make a Note Application tab open automatically when a note is first viewed by overriding `open_by_default()`. If multiple applications return `True`, the first one (by priority order) will be opened.
When a user opens a note from a command permalink, the note starts on the built-in Note tab instead, so the linked command is visible. Opening the note any other way still opens the default application.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import NoteApplication
    class AutoOpenApp(NoteApplication):
        NAME = "📋 Intake"
        IDENTIFIER = "my_plugin__auto_open_intake"
        def open_by_default(self) -> bool:
            """Open automatically when the note is viewed."""
            return True
        def on_open(self) -> Effect | list[Effect]:
            return LaunchModalEffect(
                target=LaunchModalEffect.TargetType.NOTE,
                content="<html>Form content</html>",
                title="Intake"
            ).apply()
    ```
###  Tab Ordering 
You can control the order in which Note Application tabs appear by setting the `PRIORITY` class attribute. Tabs are sorted in ascending order, so lower values appear first. The default is `0`.
    ```python
    from canvas_sdk.handlers.application import NoteApplication
    class HighPriorityApp(NoteApplication):
        NAME = "First Tab"
        IDENTIFIER = "my_plugin__first"
        PRIORITY = 1
    class LowPriorityApp(NoteApplication):
        NAME = "Second Tab"
        IDENTIFIER = "my_plugin__second"
        PRIORITY = 10
    ```
> **Note:** Note Applications do not support [notification badges](/sdk/handlers-applications/#notification-badges).
##  Scheduling Applications 
Scheduling Applications replace the built-in scheduling modal throughout Canvas. When you install a plugin with a scheduling application, it takes over all scheduling entry points: the schedule page, patient chart, calendar drag-and-drop, calendar reschedule, and note reschedule flows.
###  Implementing a Scheduling Application 
To create a Scheduling Application, your handler class should inherit from `SchedulingApplication` and define two required class attributes:
Attribute| Description  
---|---  
`NAME`| The display title shown in the modal  
`IDENTIFIER`| A unique key for the application (recommended format: `plugin_name__app_name`)  
Your class must implement the `on_open()` method, which is called when a scheduling action is triggered. This method should return an `Effect` or list of `Effect`s, typically a `LaunchModalEffect`.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import SchedulingApplication
    class CustomScheduler(SchedulingApplication):
        """Scheduling application for custom appointment booking."""
        NAME = "Schedule Appointment"
        IDENTIFIER = "my_plugin__scheduler"
        def on_open(self) -> Effect | list[Effect]:
            """Launch the scheduling form when triggered."""
            patient = self.event.context.get("patient", {})
            provider = self.event.context.get("provider", {})
            start = self.event.context.get("start", "")
            mode = self.event.context.get("mode", "schedule")
            return LaunchModalEffect(
                url=f"https://scheduler.example.com/book?patient={patient.get('id', '')}&provider={provider.get('id', '')}&start={start}&mode={mode}",
                title="Schedule Appointment"
            ).apply()
    ```
###  Context Data 
When `on_open()` is called, scheduling context is available through `self.event.context`. The available keys depend on which entry point triggered the scheduling action.
####  Entity Objects 
Entities are delivered as `{"id": <external id>}` objects, resolvable with the conventional `.objects.get(id=...)`:
Field| Resolves To| Value| Available From  
---|---|---|---  
`patient`| [Patient](/sdk/data-patient/#patient)| `{"id": <patient id>}`| Patient chart, reschedule flows  
`provider`| [Staff](/sdk/data-staff/#staff)| `{"id": <staff id>}`| Calendar, patient chart  
`location`| [PracticeLocation](/sdk/data-practicelocation/#practicelocation)| `{"id": <practice location id>}`| Current location context  
`appointment`| [Appointment](/sdk/data-appointment/#appointment)| `{"id": <appointment id>}`| Reschedule flows  
`note`| [Note](/sdk/data-note/#note)| `{"id": <note id>}`| Note reschedule flow  
####  Scalar Values 
Key| Description  
---|---  
`start`| ISO-8601 datetime of the selected slot (all entry points)  
`end`| ISO-8601 datetime for the slot end (calendar drag-and-drop only)  
`duration`| Slot length in minutes (reschedule flows only). Either `end` or `duration` is present, never both  
`mode`| One of `schedule`, `reschedule`, or `followup`  
`origin`| The launching surface: `schedule_page`, `patient_chart`, `calendar`, `calendar_reschedule`, or `note_reschedule`  
When `end` is not provided, derive it from `start + duration`.
####  Origins 
`origin` tells you which surface launched the scheduling action, which in turn determines the `mode` and whether the slot length arrives as `end` or `duration`:
`origin`| Launching surface| `mode`| Slot length  
---|---|---|---  
`schedule_page`| **New appointment** from the schedule page (no patient context)| `schedule` or `followup`| neither (`start` only)  
`patient_chart`| **New appointment** from a patient's chart| `schedule` or `followup`| neither (`start` only)  
`calendar`| Drag-and-drop on the calendar to create a slot| `schedule`| `end`  
`calendar_reschedule`| Rescheduling an existing appointment from the calendar| `reschedule`| `duration`  
`note_reschedule`| Rescheduling an appointment from within a note| `reschedule`| `duration`  
Which entities accompany each origin is shown in the Entity Objects table's "Available From" column above — for example, `patient_chart` and the reschedule flows include a `patient`, while `schedule_page` and `calendar` do not.
###  Manifest Configuration 
Register your Scheduling Application under the `handlers` section of your `CANVAS_MANIFEST.json`. There is **no** `scope` or `icon` — inheriting from `SchedulingApplication` is what tells Canvas to use it as the scheduling-modal override.
    ```json
    {
      "components": {
        "handlers": [
          {
            "class": "my_plugin.apps.scheduler:CustomScheduler",
            "description": "Custom appointment scheduling that overrides the built-in modal."
          }
        ]
      }
    }
    ```
When installed, this application replaces the built-in scheduling modal. If no scheduling application is installed, the existing built-in modal continues to work unchanged.
##  Docked Applications 
A Docked Application mounts as a persistent **docked pane** pinned to a window edge. It stays in place as the user moves between pages, including between a patient chart and global pages, rather than opening fresh each time.
Reach for a docked pane when a surface needs to follow the user instead of being opened and re-opened: a telephony or messaging bar that has to survive navigation mid-call, a live worklist the user works through while moving between charts, or an ambient scribe that keeps recording as the clinician moves around a note. Because the pane stays mounted, whatever state it holds survives that navigation, whether that's a scroll position, a half-filled form, or an open connection. A right chart pane keeps its state only while the user stays in one patient's chart. It closes when they open a different patient or leave the chart, while a docked pane stays open.
###  Implementing a Docked Application 
A Docked Application is a handler that inherits from `DockedApplication`, declares the pane's placement as class attributes, and implements `on_open()` to mount the pane's content:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import DockedApplication, DockEdge
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data.task import Task, TaskStatus
    class TaskDock(DockedApplication):
        """Docked application that keeps the signed-in user's open tasks on screen."""
        NAME = "My Tasks"
        IDENTIFIER = "my_plugin__task_dock"
        DOCK_EDGE = DockEdge.RIGHT
        DOCK_SIZE = "320px"
        def on_open(self) -> Effect | list[Effect]:
            """Mount the docked pane's content."""
            user_id = self.event.context.get("user", {}).get("id")
            tasks = Task.objects.filter(assignee__id=user_id, status=TaskStatus.OPEN).order_by("due")
            return LaunchModalEffect(
                target=LaunchModalEffect.TargetType.DOCKED_PANE,
                content=render_to_string("templates/task_dock.html", {"tasks": tasks}),
                title="My Tasks",
            ).apply()
    ```
The pane's markup lives in a Django template in your plugin rather than in a Python string, rendered by [`render_to_string`](/sdk/layout-effect/#custom-html-and-django-templates). Here that template is `templates/task_dock.html`:
    ```html
    <!DOCTYPE html>
    <html>
      <head>
        <title>My Tasks</title>
      </head>
      <body>
        <h1>My Tasks</h1>
        <ul>
          {% for task in tasks %}
            <li>{{ task.title }} (due {{ task.due }})</li>
          {% endfor %}
        </ul>
      </body>
    </html>
    ```
`on_open()` returns a [`LaunchModalEffect`](/sdk/layout-effect/#modals) with `target` set to `LaunchModalEffect.TargetType.DOCKED_PANE`. That target is what mounts the effect's rendered `content` (or a `url`) in the pane rather than in a modal. Canvas draws no chrome around a docked pane, so `title` is never displayed: it becomes the pane's accessible name for screen readers.
There is no app drawer entry that opens a docked pane and no Canvas-provided control that closes or minimizes it. For the staff who get one, the pane is simply on screen for the whole session, and which staff those are is the plugin's decision: see Controlling who gets a pane. The pane's own content can remove itself at runtime, which is how a plugin offers its own collapse or close control. See Sizing, Resizing, and Collapsing.
####  Class attributes 
Attribute| Required| Description  
---|---|---  
`NAME`| Required| The display title for the pane  
`IDENTIFIER`| Optional| A unique key for the application. When omitted, the identifier defaults to one derived automatically from the class's module and name. Set it explicitly in the recommended `plugin_name__app_name` format to give the application a stable, readable identifier.  
`DOCK_EDGE`| Required| Which window edge to pin the pane to, given as a `DockEdge` value  
`DOCK_SIZE`| Required| The pane's initial size and the initial ceiling for the plugin's own resize requests, as a CSS length string (for example, `320px`). See Sizing, Resizing, and Collapsing.  
`PRIORITY`| Optional| An integer controlling stacking order when multiple panes share an edge — lower values sit nearer the window edge. Defaults to `0`. See Multiple Docked Panes.  
####  DockEdge 
`DockEdge` is an enum of the four window edges a pane can be pinned to.
Name| Value| Edge to pin to  
---|---|---  
`LEFT`| `left`| Left edge of the window  
`RIGHT`| `right`| Right edge of the window  
`TOP`| `top`| Top edge of the window  
`BOTTOM`| `bottom`| Bottom edge of the window  
####  Controlling who gets a pane 
A docked pane is not all-or-nothing across an instance. Override `visible()` to decide, per staff member, whether the pane exists for them at all:
    ```python
    def visible(self) -> bool:
        """Only dock the pane for the care coordination team."""
        staff_id = self.event.context.get("user", {}).get("id")
        return Staff.objects.filter(id=staff_id, teams__name="Care Coordination").exists()
    ```
Returning `False` means that user gets no pane: Canvas never calls `on_open()` for them and sends them no context changes. `visible()` defaults to `True`, so a Docked Application that does not override it docks for everyone.
Two things to know about when this runs. Canvas asks for docked applications once as the EHR shell loads, so `visible()` is evaluated then and not again as the user navigates inside the shell. A change in the answer therefore takes effect on that user's next full page load. And the context `visible()` receives holds only `scope` and `user`, with no `patient` or `note`, because the question being asked is which panes this session gets rather than what is on screen. Gate on the staff member, or on anything you can look up from them, rather than on what they are currently viewing.
Do not use `on_open()` for this. Returning no docked-pane effect from `on_open()` also leaves the pane unmounted, but panes are mounted once per session and never retried, so the pane stays gone for the rest of the session with no way back.
###  Pane Context and Navigation 
Like other embedded applications, a Docked Application reads request context from `self.event.context`. It receives that context twice over: once when the pane first mounts, through `on_open()`, and again on each navigation, through `on_context_change()`. Both entry points get the same three keys:
Key| Value| Description  
---|---|---  
`url`| `str`| The path of the Canvas page the user is on. Always one of the pages a pane sees.  
`user`| `{"id": str, "type": str}`| The signed-in user, always present. `id` is the [Staff](/sdk/data-staff/#staff) id; `type` is the name of the person record behind the login, which is `Staff` in the EHR.  
`patient`| `{"id": str}`| The patient whose chart is open. Present only on a `/patient/<patient id>` path and absent entirely elsewhere, so read it as `self.event.context.get("patient", {})`.  
On a patient chart the whole context looks like this:
    ```python
    {
        "url": "/patient/b80b1cdc2e6a4aca90ccebc02e683f35",
        "user": {"id": "5eede137ecfe4124b8b773040e33be14", "type": "Staff"},
        "patient": {"id": "b80b1cdc2e6a4aca90ccebc02e683f35"},
    }
    ```
On the schedule, where no patient is in the path, the `patient` key is simply not there:
    ```python
    {
        "url": "/schedule",
        "user": {"id": "5eede137ecfe4124b8b773040e33be14", "type": "Staff"},
    }
    ```
####  `on_open()`
Fires once, when the pane mounts, and returns the effect that gives the pane its content:
    ```python
    def on_open(self) -> Effect | list[Effect]:
        url = self.event.context.get("url")
        user_id = self.event.context.get("user", {}).get("id")
        patient_id = self.event.context.get("patient", {}).get("id")
        ...
    ```
####  `on_context_change()`
Fires on each navigation after that, with the new `url` and the `patient` derived from the new path. This is how a pane stays context-aware as the user moves around Canvas.
It defaults to a no-op, so a pane that does not override it keeps whatever it last rendered. Override it to return the plugin's own content or hosted URL, rebuilt from the new context, such as a hosted URL that carries the new patient id:
    ```python
    def on_context_change(self) -> Effect | list[Effect]:
        patient_id = self.event.context.get("patient", {}).get("id", "")
        return LaunchModalEffect(
            target=LaunchModalEffect.TargetType.DOCKED_PANE,
            url=f"https://task-dock.example.com/panel?patient={patient_id}",
        ).apply()
    ```
The pane's document reloads only when `on_context_change()` returns a different `url` or `content`. Returning the same `url` or `content` as before leaves the pane's current document in place, preserving its scroll position and state, and so does returning no effect at all (`None` or an empty list). Whether to reload is your plugin's choice.
####  Pages a pane sees 
`url` is the path of the Canvas page around the pane, never the URL loaded inside the pane's own iframe. A pane navigating its own document is invisible to Canvas and produces no context change, and neither does a change to the page URL's hash.
Docked panes mount in the EHR shell, so `url` is always one of the paths that shell routes. Some of these pages are gated by permission or by a feature flag, so which of them a given user reaches will vary:
Path| Page  
---|---  
`/patient/<patient id>`| A patient's chart, including its sub-paths. The only path that carries a `patient` in context  
`/schedule`| The schedule calendar  
`/patients`| The patient list  
`/panel`| A patient panel  
`/populations`| Population health  
`/campaigns`| Campaigns  
`/revenue`| Revenue and claims  
`/data-integration`| Data integration  
`/questionnaire-builder`| The questionnaire builder  
`/application`| A full-page plugin application  
`/403`| Permission denied  
Everything else on the domain sits outside that shell, including `/admin`, `/login`, `/app/...`, `/companion/...` and `/plugin-io/...`. Moving to one of those is a full page load rather than a navigation: the pane is not on screen while the user is there, and returning to the EHR mounts it again from scratch, so `on_open()` fires rather than `on_context_change()`.
The patient portal is outside the shell as well, so a docked pane cannot appear there. A Docked Application is a staff-facing surface only.
Because the pane stays mounted across every navigation inside the shell, it keeps its state there. A right chart pane, by contrast, closes when the user opens a different patient or leaves the chart.
###  Multiple Docked Panes 
Docked panes stack rather than being limited to one per edge. Each edge holds up to two panes. When an edge already holds its two panes, an additional pane for that edge is not displayed — it is ignored rather than raising an install-time error.
Panes sharing an edge share a single track, and they split it evenly. On a left or right edge they stack top to bottom, each as wide as the track; on a top or bottom edge they sit side by side, each as tall as it. So two panes on one edge each get half the length of that edge, and the edge itself is only as thick as the larger of their two `DOCK_SIZE` values, since those sizes are alternatives rather than additions.
Which pane comes first is decided by priority: the lower `PRIORITY` value goes first, which means the top of the stack on a left or right edge and the left-hand position on a top or bottom edge. Panes with equal priority are ordered by their identifier. This mirrors the way the `PRIORITY` class attribute orders Note Application tabs. To get a predictable order, set an explicit `PRIORITY` on each pane, and set an explicit `IDENTIFIER` rather than relying on the auto-derived one.
Panes cannot crowd Canvas out of its own window. The left and right panes together take up at most half the window's width, and the top and bottom panes together at most half its height. If the panes on one of those pairs would exceed their half, all of them are scaled down in proportion rather than any one being dropped.
###  Sizing, Resizing, and Collapsing 
`DOCK_SIZE` sets the pane's initial size — its width on the `LEFT` and `RIGHT` edges, its height on the `TOP` and `BOTTOM` edges — and the initial ceiling for the plugin's own resize requests. The user and the plugin resize the pane under different rules.
A user can resize a pane by dragging its edge or with the keyboard arrow keys, using the standard splitter the pane exposes. A user resize can make the pane larger or smaller than `DOCK_SIZE`: it stops at 48px, and at the half-the-window limit described above, but is not otherwise bound by `DOCK_SIZE`. The size a user drags to becomes the pane's new ceiling, replacing `DOCK_SIZE`, and is stored in the browser (`localStorage`) keyed by the pane's identifier, so it survives page reload and navigation. Once a user has resized a pane, that persisted size takes precedence on future loads, so changing `DOCK_SIZE` in a later plugin version does not affect panes a user has already resized, until the stored size is cleared.
There is no host-provided control to close or minimize the pane. A plugin can, however, resize or collapse its own pane from inside its iframe (for example, by collapsing it to a thin rail). A plugin's own resize can shrink the pane freely, down to a thin rail. It cannot grow the pane past the current ceiling: a request at or above the ceiling is clamped to the ceiling rather than applied as given, so a plugin restores the pane to its full (ceiling) size by requesting any value at or above it. A plugin-driven resize is not bound by the 48px floor that applies to user resizing.
A pane is removed only when the plugin's own content requests it, by posting the same `CLOSE_MODAL` message that applications use to dismiss modals. See [Closing Modals from Applications](/sdk/layout-effect/#closing-modals-from-applications) for the full mechanism. Once removed, nothing re-mounts the pane short of a page reload.
A docked pane cannot navigate the host application directly; navigation is issued through a redirect effect. It does not reset the session idle-logout timer.
###  Manifest Configuration 
Register your Docked Application under the `handlers` section of your `CANVAS_MANIFEST.json`. As with Note and Scheduling Applications, there is **no** `scope` or `icon` — inheriting from `DockedApplication` is what tells Canvas to mount it as a docked pane.
    ```json
    {
      "components": {
        "handlers": [
          {
            "class": "my_plugin.apps.task_dock:TaskDock",
            "description": "Open task list docked to the right edge."
          }
        ]
      }
    }
    ```
##  Provider Menu Applications 
A provider menu application adds an entry to the **provider side menu** , the navigation sidebar also called the hamburger menu. A provider can open the menu from any page in the EHR. Use one when a plugin needs a launch point that isn't tied to a patient chart or a note.
###  Implementing a Provider Menu Application 
Subclass `ProviderMenuApplication` and implement `on_open()` to return the effect that runs when the entry is clicked, typically a [`LaunchModalEffect`](/sdk/layout-effect/#modals):
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import MenuPosition, ProviderMenuApplication
    class CareGaps(ProviderMenuApplication):
        """Provider menu entry that opens the care-gaps worklist."""
        NAME = "Care gaps"
        IDENTIFIER = "my_plugin__care_gaps"
        MENU_POSITION = MenuPosition.BOTTOM
        def on_open(self) -> Effect | list[Effect]:
            """Launch the worklist when the menu entry is clicked."""
            return LaunchModalEffect(
                url="https://care-gaps.example.com/worklist",
                title="Care gaps",
            ).apply()
    ```
Configure the entry with these class attributes:
Attribute| Required| Description  
---|---|---  
`NAME`| Required| The label shown for the menu entry.  
`IDENTIFIER`| Optional| A unique key for the application. Recommended in the `plugin_name__app_name` format; when omitted, it defaults to one derived from the class's module and name.  
`MENU_POSITION`| Optional| The group the entry joins, as a `MenuPosition` value. Defaults to `MenuPosition.TOP`.  
`ICON_URL`| Optional| Not displayed. The provider menu shows only the `NAME` label, so setting this has no visible effect.  
`PRIORITY`| Optional| An integer that orders entries within a group. Lower values appear first. Entries sort together with `provider_menu_item` drawer applications, which are ordered by their `menu_order` manifest field. Defaults to `0`.  
> **Info:** **Don't confuse`ProviderMenuApplication` with the `provider_menu_item` drawer scope.** A `ProviderMenuApplication` is a handler registered under `handlers`, configured with Python class attributes such as `MENU_POSITION`. `provider_menu_item` is a manifest scope for a drawer application in the `applications` array, configured with manifest fields such as `icon` (see [Application Scopes](/sdk/handlers-applications/#application-scopes)). Both place an entry in the provider menu, and they can coexist.
###  MenuPosition 
`MenuPosition` is an enum of the two groups in the provider menu:
Name| Value| Group  
---|---|---  
`TOP`| `top`| Top of the provider menu  
`BOTTOM`| `bottom`| Bottom of the provider menu  
Any other `MENU_POSITION` value raises a `ValueError` when Canvas loads the menu.
###  Visibility 
Provider menu and panel applications decide whether their entry appears by overriding `visible()`. Return `True` to show the entry and `False` to hide it. The default returns `True`, so the entry appears for every user on every page.
Canvas calls `visible()` when the menu loads and again each time the user navigates to another page, so an entry can appear on some pages and not others. `on_context_change()` is separate: it runs only while your application is open, not each time the menu refreshes its entries.
`visible()` reads the page and the user from `self.event.context`:
    ```python
    # On a patient chart
    {
        "user": {"type": "Staff", "id": "4150cd20de8a470aa570a852859ac87e"},
        "url": "/patient/b80b1cdc2e6a4aca90ccebc02e683f35",
        "patient": {"id": "b80b1cdc2e6a4aca90ccebc02e683f35"},
    }
    # On any other page
    {
        "user": {"type": "Staff", "id": "4150cd20de8a470aa570a852859ac87e"},
        "url": "/schedule",
    }
    ```
Key| Description  
---|---  
`user`| The signed-in user. `id` is the [Staff](/sdk/data-staff/) id.  
`url`| The path of the current page, without the domain. See Pages a pane sees for the paths Canvas sends.  
`patient`| Present only on a patient chart. `id` is the patient's id.  
Show the entry only on patient charts:
    ```python
    def visible(self) -> bool:
        """Show the entry only while a patient chart is open."""
        return self.event.context.get("patient") is not None
    ```
Show the entry only to staff with a given role, using the [Staff](/sdk/data-staff/) data model:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import ProviderMenuApplication
    from canvas_sdk.v1.data import Staff
    ALLOWED_ROLE_CODES = ["MD", "NP"]
    class CareGaps(ProviderMenuApplication):
        """Provider menu entry that only prescribers can see."""
        NAME = "Care gaps"
        IDENTIFIER = "my_plugin__care_gaps"
        def visible(self) -> bool:
            """Show the entry only to staff who hold an allowed role."""
            staff_id = self.event.context.get("user", {}).get("id")
            if not staff_id:
                return False
            return Staff.objects.filter(
                id=staff_id,
                roles__internal_code__in=ALLOWED_ROLE_CODES,
            ).exists()
        def on_open(self) -> Effect | list[Effect]:
            """Launch the worklist, or an access message for staff without a role."""
            if not self.visible():
                return LaunchModalEffect(
                    content="<p>You don't have access to Care gaps.</p>",
                    title="Care gaps",
                ).apply()
            return LaunchModalEffect(
                url="https://care-gaps.example.com/worklist",
                title="Care gaps",
            ).apply()
    ```
Role codes come from your instance's staff role setup, so use the `internal_code` values your instance's [staff roles](/sdk/data-staff/#staffrole) carry. To allow a fixed list of people instead, compare `staff_id` against a set of Staff ids.
> **Warning:** **Hiding an entry only removes it from the menu.** Canvas doesn't call `visible()` when an application opens, so a user who has a link to it can still open it. An open application's URL carries its identifier, base64-encoded, as `#application=<encoded identifier>`, and loading that URL runs `on_open()` directly. If the content itself must be restricted, run the same check in `on_open()` and return a message instead of the content when it fails. The example above does this by calling `self.visible()` from `on_open()`, which works because the open event carries the same `user` context.
###  Badges 
Override `compute_notification_badge()`, inherited from `Application` and described under [Notification Badges](/sdk/handlers-applications/#notification-badges), to show a count on the entry. Return a non-negative integer, or `None` (the default) for no badge. A count of `0` shows no badge.
Canvas computes the count when the menu loads, not on each navigation. To change the count after load, emit an [`ApplicationNotificationBadge`](/sdk/effect-application-notification-badge/) effect for the application's `identifier`, as described under [Live updates](/sdk/handlers-applications/#live-updates).
###  Manifest Configuration 
Register your provider menu application under the `handlers` section of your `CANVAS_MANIFEST.json`:
    ```json
    {
      "components": {
        "handlers": [
          {
            "class": "my_plugin.apps.care_gaps:CareGaps",
            "description": "Care-gaps worklist in the provider menu."
          }
        ]
      }
    }
    ```
##  Panel Applications 
A panel application adds an entry beside the panel buttons, both inside and outside patient charts. By default, the entry appears in the app drawer with its icon and name, alongside drawer applications. Set `SHOW_IN_DRAWER = False` to show the icon directly in the panel bar instead. The panel bar shows only the icon, with no label, so every panel application sets an `ICON_URL`.
###  Implementing a Panel Application 
Subclass `PanelApplication`, set `ICON_URL`, and implement `on_open()` to return the effect that runs when the icon is clicked:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import PanelApplication
    class Inbox(PanelApplication):
        """Panel bar entry that opens the messaging inbox."""
        NAME = "Inbox"
        IDENTIFIER = "my_plugin__inbox"
        ICON_URL = "https://assets.example.com/inbox-icon.png"
        SHOW_IN_DRAWER = False
        def on_open(self) -> Effect | list[Effect]:
            """Launch the inbox when the panel icon is clicked."""
            return LaunchModalEffect(
                url="https://inbox.example.com",
                title="Inbox",
            ).apply()
    ```
Configure the entry with these class attributes:
Attribute| Required| Description  
---|---|---  
`NAME`| Required| The entry's name, shown under the icon in the app drawer. The panel bar shows only the icon.  
`ICON_URL`| Required| The icon shown for the entry, as an `https://` URL or a `data:` URI. A path to a file in your plugin package does not work. See Panel Icons.  
`IDENTIFIER`| Optional| A unique key for the application. Recommended in the `plugin_name__app_name` format; when omitted, it defaults to one derived from the class's module and name.  
`SHOW_IN_DRAWER`| Optional| When `True` (the default), the entry appears in the app drawer. When `False`, the icon shows directly in the panel bar.  
`PRIORITY`| Optional| An integer that orders entries. Lower values appear first. Entries sort together with drawer applications, which are ordered by their `panel_priority` manifest field. Defaults to `0`.  
A `PanelApplication` subclass without an `ICON_URL` raises `ImproperlyConfigured` when the class is defined, so the plugin fails to load rather than showing an entry with nothing to click. To share behavior across several panel entries, define an intermediate base class with `abstract = True`. That class may omit `ICON_URL`, but each subclass of it must set one:
    ```python
    class InboxBase(PanelApplication):
        abstract = True
        def on_open(self) -> Effect | list[Effect]:
            return LaunchModalEffect(url="https://inbox.example.com").apply()
    class TeamInbox(InboxBase):
        NAME = "Team inbox"
        ICON_URL = "https://assets.example.com/team-inbox-icon.png"
    ```
Panel applications support `visible()` and notification badges as described under Visibility and Badges.
###  Panel Icons 
Canvas uses the `ICON_URL` string as the icon's image source, exactly as you set it. This differs from the `icon` field of a drawer application in the manifest, which is a path to a file in your plugin package that Canvas uploads and stores when the plugin is installed. A `PanelApplication` creates no application record, so nothing uploads its icon, and a package path such as `assets/inbox.png` doesn't load.
`ICON_URL` takes either of these:
  - **An`https://` URL** to an image hosted outside Canvas:
        ```python
        ICON_URL = "https://assets.example.com/inbox-icon.png"
        ```
  - **A`data:` URI** that holds the image itself, which keeps the icon inside your plugin code. An SVG can be written inline with its special characters percent-encoded (`<` as `%3C`, `>` as `%3E`, `#` as `%23`):
        ```python
        ICON_URL = (
            "data:image/svg+xml,"
            "%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E"
            "%3Ccircle cx='12' cy='12' r='10' fill='%23336699'/%3E"
            "%3C/svg%3E"
        )
        ```
A PNG works as a base64-encoded `data:image/png;base64,...` string.
Canvas has no fallback for an icon that fails to load, so a broken URL shows a broken image in the panel bar. Host the image somewhere that stays available.
###  Patient Charts and Other Pages 
A panel application has one scope for every page, so it has no equivalent of a drawer application's `patient_specific` and `global` scopes. Its entry appears in the panel bar on patient charts and on every other page unless `visible()` says otherwise. Its context includes a `patient` only on a patient chart, so check for one to choose where the entry appears:
    ```python
    def visible(self) -> bool:
        """Show the entry only on patient charts, like a patient_specific application."""
        return self.event.context.get("patient") is not None
    ```
    ```python
    def visible(self) -> bool:
        """Show the entry only outside patient charts, like a global application."""
        return self.event.context.get("patient") is None
    ```
To show the entry on every page, leave `visible()` as it is.
###  Manifest Configuration 
Register your panel application under the `handlers` section of your `CANVAS_MANIFEST.json`:
    ```json
    {
      "components": {
        "handlers": [
          {
            "class": "my_plugin.apps.inbox:Inbox",
            "description": "Messaging inbox in the panel bar."
          }
        ]
      }
    }
    ```

---

# Payment Processors

Source: https://docs.canvasmedical.com/sdk/handlers-payment-processors/

The Canvas SDK provides a way to define custom payment processors that enables Canvas to:
  - Handle payment-related workflows within the platform
  - Integrate with third-party payment providers
  - Manage payment methods for patients
Custom payment processors enable flexibility, allowing developers to replace Stripe with other payment providers. Currently, only credit card payment processors are supported.
##  Payment Processor Handler 
All payment processors are implemented as subclasses of the abstract `PaymentProcessor` handler. This defines the base contract for:
  - Selecting a processor
  - Charging payments
  - Listing, adding, and removing payment methods
You can find it in:
    ```python
    from canvas_sdk.handlers.payment_processors.base import PaymentProcessor
    ```
`PaymentProcessor` is an abstract base that wires up event handling but does not define the methods a plugin needs to implement. You should not subclass it directly — instead, extend one of its typed subclasses. Currently the only supported type is `CardPaymentProcessor`, which is where the methods you need to define are declared.
* * *
##  CardPaymentProcessor 
If your custom processor deals with card payments, extend the `CardPaymentProcessor`, which provides additional structure.
    ```python
    from canvas_sdk.handlers.payment_processors.card import CardPaymentProcessor
    ```
In the plugin, this is implemented as:
    ```python
    from canvas_sdk.handlers.payment_processors.card import (
        CardPaymentProcessor,
    )
    class PayTheoryPaymentProcessor(CardPaymentProcessor):
        ...  # Your implementation here
    ```
Register the class in the `handlers` section of your plugin's `CANVAS_MANIFEST.json`, like any other handler. The base class already declares the events it responds to, so you don't list them yourself.
    ```json
    {
      "components": {
        "handlers": [
          {
            "class": "my_plugin.handlers.payment_processor:PayTheoryPaymentProcessor",
            "description": "Charges cards and manages saved payment methods through Pay Theory."
          }
        ]
      }
    }
    ```
###  How Canvas calls your processor 
`PaymentProcessor` responds to the six [payment processor events](/sdk/events/#payment-processor-events) and calls a method on your subclass for each one:
Event| Method Canvas calls| Returns  
---|---|---  
`REVENUE__PAYMENT_PROCESSOR__LIST`| `metadata()` (implemented for you)| [`PaymentProcessorMetadata`](/sdk/payment-processor-effect/#paymentprocessormetadata)  
`REVENUE__PAYMENT_PROCESSOR__SELECTED`| `payment_form`, `add_card_form`, or both| [`PaymentProcessorForm`](/sdk/payment-processor-effect/#paymentprocessorform)  
`REVENUE__PAYMENT_PROCESSOR__CHARGE`| `charge`| [`CardTransaction`](/sdk/payment-processor-effect/#cardtransaction)  
`REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__LIST`| `payment_methods`| A list of [`PaymentMethod`](/sdk/payment-processor-effect/#paymentmethod)  
`REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__ADD`| `add_payment_method`| [`AddPaymentMethodResponse`](/sdk/payment-processor-effect/#addpaymentmethodresponse)  
`REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__REMOVE`| `remove_payment_method`| [`RemovePaymentMethodResponse`](/sdk/payment-processor-effect/#removepaymentmethodresponse)  
Every handler has an `identifier`, available as `self.identifier`, that Canvas derives from the handler's module path and class name. Every event after `REVENUE__PAYMENT_PROCESSOR__LIST` carries the `identifier` of the processor it targets, and your methods run only when it matches. Several payment processor plugins can be installed side by side without handling each other's events.
> **Warning:** Keep your handler's module path and class name stable once the processor is in use. Canvas routes every payment event by `identifier`, and renaming or moving the class changes it.
The handler loads the [`Patient`](/sdk/data-patient/) from the event context and passes it to your methods. Some workflows have no patient context, so `payment_form`, `add_card_form`, `charge`, and `payment_methods` receive `patient=None` there. `add_payment_method` and `remove_payment_method` always receive a patient: when an event arrives without one, Canvas doesn't call them.
* * *
##  Defining a `CardPaymentProcessor`
When implementing a `CardPaymentProcessor`, you must define how Canvas should display forms for adding and charging cards, how to process those payments, and how to manage saved payment methods.
In order to implement a `CardPaymentProcessor`, you should override and implement the following methods grouped into three main categories:
  - Displaying forms
  - Charging a card
  - Managing payment methods
###  Displaying Forms 
The forms you return via [`PaymentProcessorForm`](/sdk/payment-processor-effect/#paymentprocessorform) are rendered directly as **inner HTML** within the Canvas application. These forms must define a small contract of JavaScript behaviors to allow Canvas to communicate with them.
These methods define the HTML content that will be rendered inside Canvas to collect card data for payments or adding new cards. They must comply with the Form Workflow.
These forms render wherever Canvas collects a card payment or manages saved payment methods, including:
  - the **provider UI** — the Revenue module and the patient profile payment/insurance area
  - the **Patient Portal** — when a patient makes a payment or manages their saved cards
When a user selects your processor, the `REVENUE__PAYMENT_PROCESSOR__SELECTED` event carries an `intent` that says which form Canvas needs. An intent of `pay` calls `payment_form`, and `add_card` calls `add_card_form`. When the event has no intent, Canvas calls both and receives both forms.
####  Payment Form 
Triggered when a user selects the credit card payment option. This method should return the HTML form used to collect and tokenize the payment details.
    ```python
    from canvas_sdk.effects.payment_processor import PaymentProcessorForm
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Patient
    def payment_form(self, patient: Patient | None = None) -> PaymentProcessorForm:
        content = render_to_string("templates/payment_form.html")
        return PaymentProcessorForm(intent="pay", content=content)
    ```
* * *
####  Add Card Form 
Triggered when a user initiates the process of adding a new card to a patient's saved payment methods. This method should return the HTML form used to collect and tokenize the new card information.
    ```python
    from canvas_sdk.effects.payment_processor import PaymentProcessorForm
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Patient
    def add_card_form(self, patient: Patient | None = None) -> PaymentProcessorForm:
        content = render_to_string(
            "templates/add_card_form.html",
            {"payor_id": self.api.get_default_payor_id()},
        )
        return PaymentProcessorForm(intent="add_card", content=content)
    ```
* * *
###  Charging a Card 
Handles the actual payment. This method is triggered after tokenization and is responsible for charging the card. It returns a [`CardTransaction`](/sdk/payment-processor-effect/#cardtransaction) effect describing the result of the charge:
    ```python
    from decimal import Decimal
    from typing import Any
    from canvas_sdk.effects.payment_processor import CardTransaction
    from canvas_sdk.v1.data import Patient
    def charge(
        self,
        amount: Decimal,
        token: str,
        patient: Patient | None = None,
        **kwargs: Any
    ) -> CardTransaction:
        payload = {
            "token": token,
            "amount": int(amount * 100),
            "currency": "usd",
            # patient is None when the charge has no patient context
            "metadata": {"patient_id": patient.id if patient else None},
        }
        result = self.api.charge(payload)
        return CardTransaction(
            transaction_id=result["transaction_id"],
            success=True,
            api_response=result,
        )
    ```
####  Additional Context 
The `charge` method accepts `**kwargs` which can contain additional context passed from the payment form. This is useful when you need to pass extra information from the tokenization response (e.g., payment method details, transaction metadata) to the charge handler.
The additional context is passed via the second argument of `setToken` in your form's JavaScript (see Form Workflow). Canvas processes the `additional_context` as follows:
Input Type| Example| Passed to `charge` as  
---|---|---  
JSON object string| `'{"key": "value"}'`| `key="value"` (unpacked as kwargs)  
`None`| `null`| `additional_context=None`  
Plain string| `"some text"`| `additional_context="some text"`  
JSON number string| `"123"`| `additional_context=123`  
JSON boolean string| `"true"`| `additional_context=True`  
Example using additional context:
    ```python
    from decimal import Decimal
    from typing import Any
    from canvas_sdk.effects.payment_processor import (
      CardTransaction,
      PaymentProcessorForm
    )
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Patient
    def charge(
        self,
        amount: Decimal,
        token: str,
        patient: Patient | None = None,
        **kwargs: Any
    ) -> CardTransaction:
        # Access additional context from kwargs
        # If setToken was called with a JSON object like {"zip_code": "60007", "city": "Chicago"},
        # these will be available as kwargs
        zip_code = kwargs.get("zip_code")
        city = kwargs.get("city")
        # Or if a non-dict value was passed, it will be in additional_context
        raw_context = kwargs.get("additional_context")
        # ... rest of implementation
    ```
* * *
###  Managing Payment Methods 
These methods define how Canvas lists, stores, and deletes saved cards associated with a patient.
####  List 
Returns the patient's saved cards as a list of [`PaymentMethod`](/sdk/payment-processor-effect/#paymentmethod) effects, which Canvas renders when displaying stored payment methods.
    ```python
    from canvas_sdk.effects.payment_processor import PaymentMethod
    from canvas_sdk.v1.data import Patient
    def payment_methods(self, patient: Patient | None = None) -> list[PaymentMethod]:
       if patient is None:
           return []
       return [
                PaymentMethod(
                    payment_method_id="pm_1",
                    brand="Visa",
                    expiration_year=2025,
                    expiration_month=12,
                    card_holder_name="John Doe",
                    postal_code="12345",
                    card_last_four_digits="1234",
                )
            ]
    ```
####  Add 
Stores a new card for the patient using the tokenized card data and returns an [`AddPaymentMethodResponse`](/sdk/payment-processor-effect/#addpaymentmethodresponse) effect indicating whether the card was saved.
    ```python
    from typing import Any
    from canvas_sdk.effects.payment_processor import AddPaymentMethodResponse
    from canvas_sdk.v1.data import Patient
    def add_payment_method(self, token: str, patient: Patient, **kwargs: Any) -> AddPaymentMethodResponse:
        return AddPaymentMethodResponse(success=True)
    ```
#####  Additional Context 
The `add_payment_method` method accepts `**kwargs` which can contain additional context passed from the add card form. This is useful when you need to pass extra information from the tokenization response to the `add_payment_method` handler.
The additional context is passed via the second argument of `setToken` in your form's JavaScript (see Form Workflow). Canvas processes the `additional_context` as follows:
Input Type| Example| Passed to `add_payment_method` as  
---|---|---  
JSON object string| `'{"key": "value"}'`| `key="value"` (unpacked as kwargs)  
`None`| `null`| `additional_context=None`  
Plain string| `"some text"`| `additional_context="some text"`  
JSON number string| `"123"`| `additional_context=123`  
JSON boolean string| `"true"`| `additional_context=True`  
Example using additional context:
    ```python
    from typing import Any
    from canvas_sdk.effects.payment_processor import AddPaymentMethodResponse
    from canvas_sdk.v1.data import Patient
    def add_payment_method(self, token: str, patient: Patient, **kwargs: Any) -> AddPaymentMethodResponse:
        # Access additional context from kwargs
        # If setToken was called with a JSON object like {"zip_code": "60007", "city": "Chicago"},
        # these will be available as kwargs
        zip_code = kwargs.get("zip_code")
        city = kwargs.get("city")
        # Or if a non-dict value was passed, it will be in additional_context
        raw_context = kwargs.get("additional_context")
        # ... rest of implementation
        return AddPaymentMethodResponse(success=True)
    ```
####  Remove 
Deletes the patient's saved card identified by `token` and returns a [`RemovePaymentMethodResponse`](/sdk/payment-processor-effect/#removepaymentmethodresponse) effect indicating whether the card was removed.
    ```python
    from canvas_sdk.effects.payment_processor import RemovePaymentMethodResponse
    from canvas_sdk.v1.data import Patient
    def remove_payment_method(self, token: str, patient: Patient) -> RemovePaymentMethodResponse:
        return RemovePaymentMethodResponse(success=True)
    ```
* * *
##  Form Workflow 
Payment and Add Card forms are rendered as inner HTML inside Canvas. These forms must implement the following communication contract via JavaScript:
###  1\. Notify readiness 
This should be called once the form has fully loaded and is ready for user interaction. Canvas waits for this signal to show the form.
    ```js
    window.parent.setFormIsReady();
    ```
###  2\. Submit token after success 
Once the card details are validated and tokenized, this method must be called to pass the token back to Canvas. This token will then be used to charge or store the card.
    ```js
    window.parent.setToken("tok_123abc");
    ```
You can optionally pass a second argument with additional context that will be forwarded to the `charge` or `add_payment_method` methods. This is useful for passing extra data from the tokenization response:
    ```js
    // Pass additional context as a JSON-serializable object
    window.parent.setToken("tok_123abc", { zip_code: "111", city: "Chicago" });
    // Or pass the raw tokenization result
    const result = await paymentProvider.tokenize(cardDetails);
    window.parent.setToken(result.token, result);
    ```
The additional context is available in the `**kwargs` of `charge` and `add_payment_method`. See Additional Context for how Canvas passes each type of value.
###  3\. Report validation status 
Call this every time the validity of the form changes (e.g., input becomes valid or invalid). Canvas uses this to enable or disable the ability to submit the form programmatically.
    ```js
    window.parent.setFormIsValid(true); // or false
    ```
###  4\. Handle errors 
Call this to notify Canvas of any form-level errors (e.g., failed tokenization, invalid input). The message should help users understand what went wrong.
    ```js
    window.parent.setError("Invalid card details");
    ```
###  5\. Submit button 
The HTML form must include a button with `id="submit"`. This button is required, should remain hidden from the user, and will be clicked programmatically by Canvas when the form is considered valid and ready to be submitted.
    ```html
    <button type="submit" id="submit" hidden>Submit</button>
    ```
###  6\. Define teardown function 
This function will be called automatically when the form is unmounted or replaced. Use it to remove any event listeners or free up memory/resources.
    ```js
    window.teardown = () => {
      // Cleanup listeners, state, etc.
    };
    ```
* * *
##  Tokenization Flow 
Tokenization is the process where the sensitive card information is securely transformed into a token that can be safely used by Canvas to perform charges or save cards.
When implementing a payment processor, it's expected that your HTML forms integrate with your provider's frontend SDK to:
  - Collect and validate card input
  - Tokenize the card using the provider's secure API
  - Call `window.parent.setToken(token)` with the result
Canvas does not handle raw card input. Tokenization **must** be handled entirely by the payment provider's frontend tools within the form.
Before building a plugin, ensure:
  - Your provider offers secure frontend tokenization
  - You can integrate with their JavaScript SDK
  - You can submit token data from the form via `setToken`
* * *
##  Example Plugin 
For a complete, working reference, see the [PayTheory Payment Processor](/sdk/example-paytheory_payment_processor/) example plugin. It implements a custom `CardPaymentProcessor` that replaces the standard Stripe integration with [Pay Theory](https://paytheory.com), covering tokenization forms, charging, and saved payment method management.

---

# SimpleAPI Commands

Source: https://docs.canvasmedical.com/sdk/handlers-simple-api-commands/

**Any time you want to write a[command](/sdk/commands/) to a patient's chart over HTTP, this is already built for you.** `CommandAPI` is a [SimpleAPI](/sdk/handlers-simple-api-http/) that reads a request body onto a command, validates it against that command, and emits the effects. You declare the routes and who may reach them; it does the rest.
Reach for it whenever something outside Canvas needs to write to a chart — a patient-facing intake form, a device reporting readings, an internal tool your staff already work in, or a service that turns its own records into chart entries. Written by hand, each of those means parsing a body, mapping it onto a command, deciding how to report every way it can be wrong, and keeping your own record of which command you wrote. None of that is yours to write anymore.
For a walkthrough — including how to check that the caller may write to a particular note — see [Writing Commands Over HTTP](/guides/writing-commands-over-http/).
##  Quickstart 
    ```python
    from canvas_sdk.commands import HistoryOfPresentIllnessCommand
    from canvas_sdk.commands.api import CommandAPI
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Response
    from canvas_sdk.handlers.simple_api import StaffSessionAuthMixin, api
    class HistoryOfPresentIllnessAPI(StaffSessionAuthMixin, CommandAPI):
        PREFIX = "/v1"
        @api.post("/hpi")
        def insert(self) -> list[Response | Effect]:
            return self.originate(HistoryOfPresentIllnessCommand)
    ```
That class is five lines, and both of its base classes are load-bearing.
###  What it inherits from SimpleAPI 
`CommandAPI` is a full [SimpleAPI](/sdk/handlers-simple-api-http/). The Quickstart shows one shape — a single `POST` under a `PREFIX` — but that is just this example. Anything you can build with a SimpleAPI you can build here:
  - **As many routes as you like** , declared with `@api.get`, `@api.post`, `@api.put`, `@api.patch` and `@api.delete`. `PREFIX` is optional and prefixes them all.
  - **Path parameters.** A segment written `<name>` in a route path is a placeholder — `@api.put("/hpi/<command_id>")` matches a request to `/hpi/2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10`, and what it matched is available as `self.request.path_params["command_id"]`. That is how the routes below say _which_ command to edit or act on: the id comes from the URL rather than the body. A value is always a string, is never empty, and covers one path segment only — it cannot contain a `/`.
  - **The whole request.** `self.request` carries the method, path, headers, query parameters, the raw body, parsed JSON, text, and `multipart/form-data` parts including file uploads.
  - **Any response you want to send.** A handler always returns the ordinary SimpleAPI list of responses and effects. `originate`, `edit` and `action` each return that list already built — which is why the handlers here read `return self.originate(...)` with no brackets of their own. When you want your own response, you build the list yourself, as the `act` route does below with `[JSONResponse(...)]`, or splice onto theirs: `return [*self.originate(...), my_effect]`.
  - **Authentication.** You decide which method to use — see [Authentication](/sdk/handlers-simple-api-http/#authentication) for the schemes available.
One difference worth knowing: `CommandAPI` extends `SimpleAPI`, not [`SimpleAPIRoute`](/sdk/handlers-simple-api-http/#simpleapiroute). A class declares `PREFIX` and decorated route handlers rather than a single `PATH` with `get` and `post` methods.
What `CommandAPI` adds on top is the three methods below — `originate`, `edit` and `action` — and nothing else. Those three names are reserved: a route handler may not reuse one, and SimpleAPI raises at class-definition time if you try.
###  Where authentication comes from 
`CommandAPI` does not **choose** your authentication — which callers may write commands is your plugin's decision, not the base's. The schemes themselves are provided: declare one by listing it _before_ `CommandAPI` in the bases, from `StaffSessionAuthMixin`, `PatientSessionAuthMixin`, `APIKeyAuthMixin` and `BasicAuthMixin`. See [Authentication mixins](/sdk/handlers-simple-api-http/#authentication-mixins) for what each one needs, or write `authenticate` yourself.
Nothing is left open in the meantime. SimpleAPI's own `authenticate` returns `False`, so an endpoint that declares no scheme refuses every request rather than admitting anyone.
**That default is also why the order of the base classes matters, and why getting it wrong fails quietly** — whichever class Python reaches first decides:
Base classes| Result  
---|---  
`(StaffSessionAuthMixin, CommandAPI)`| The mixin answers first. Authentication works as you expect.  
`(CommandAPI, StaffSessionAuthMixin)`| SimpleAPI answers first, and it refuses everything. **Every request is rejected** , with no error to tell you why.  
> **Warning:** An authentication mixin establishes _who_ the caller is, not _what_ they may write. `StaffSessionAuthMixin` only checks that the session belongs to a staff member — it does not consider roles, and it says nothing about whether that person may write to the note in the request body. For that check, see [Writing Commands Over HTTP](/guides/writing-commands-over-http/).
##  A complete endpoint 
The Quickstart creates a command. Most endpoints also need to change one afterwards, which means three routes — create, update, and apply an action such as committing it. All three live on one class, and each is a single call:
    ```python
    from http import HTTPStatus
    from canvas_sdk.commands import HistoryOfPresentIllnessCommand
    from canvas_sdk.commands.api import CommandAPI
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import StaffSessionAuthMixin, api
    # The actions this endpoint will pass on. Checked against the request so a caller
    # cannot name an arbitrary attribute of the command class.
    ALLOWED_ACTIONS = {"commit", "delete", "enter_in_error"}
    class HistoryOfPresentIllnessAPI(StaffSessionAuthMixin, CommandAPI):
        PREFIX = "/v1"
        @api.post("/hpi")
        def create(self) -> list[Response | Effect]:
            return self.originate(HistoryOfPresentIllnessCommand)
        @api.put("/hpi/<command_id>")
        def update(self) -> list[Response | Effect]:
            return self.edit(HistoryOfPresentIllnessCommand, self.request.path_params["command_id"])
        @api.post("/hpi/<command_id>/<action>")
        def act(self) -> list[Response | Effect]:
            action = self.request.path_params["action"]
            if action not in ALLOWED_ACTIONS:
                return [
                    JSONResponse(
                        {"error": "unsupported action", "allowed": sorted(ALLOWED_ACTIONS)},
                        status_code=HTTPStatus.BAD_REQUEST,
                    )
                ]
            return self.action(
                HistoryOfPresentIllnessCommand,
                self.request.path_params["command_id"],
                action,
            )
    ```
Staging a note entry, committing it, and retracting it, against that endpoint:
    ```shell
    # Create it, staged for a human to finish.
    curl -X POST https://example.canvasmedical.com/plugin-io/api/my_plugin/v1/hpi \
      -H 'Content-Type: application/json' \
      -d '{
            "note_id": "d2194110-5c9a-4842-8733-ef09ea5ead11",
            "values": {"narrative": "Patient reports a cough for three days."}
          }'
    # 201 {"command_uuid": "2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10", "committed": false}
    # Revise it.
    curl -X PUT https://example.canvasmedical.com/plugin-io/api/my_plugin/v1/hpi/2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10 \
      -H 'Content-Type: application/json' \
      -d '{"values": {"narrative": "Patient reports a dry cough for three days."}}'
    # 200 {"command_uuid": "2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10", "mode": "edit"}
    # Commit it.
    curl -X POST https://example.canvasmedical.com/plugin-io/api/my_plugin/v1/hpi/2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10/commit
    # 200 {"command_uuid": "2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10", "mode": "commit"}
    # Retract it. A committed command cannot be edited, so entering it in error is
    # how you take it back - then originate its replacement.
    curl -X POST https://example.canvasmedical.com/plugin-io/api/my_plugin/v1/hpi/2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10/enter_in_error
    # 200 {"command_uuid": "2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10", "mode": "enter_in_error"}
    ```
The order matters: `enter_in_error` needs a **committed** command, so it only works after the commit above. Sent against the staged command it would have been refused — see State.
To serve every command from one endpoint instead of one class per command, see [Serving every command from one endpoint](/guides/writing-commands-over-http/#serving-every-command-from-one-endpoint) in the guide — the command is an argument, so a dict of them and a path parameter is all it takes.
##  Methods 
Each returns the effects and the response for you to return from the route handler. You return the list as-is; nothing else is required of the handler.
###  originate 
`originate(model)` creates a command from the request body.
Body field| Type| Required| Description  
---|---|---|---  
`note_id`|  _string_| `true`| The id of the [Note](/sdk/data-note/#note) to write the command into.  
`values`|  _object_| `false`| The command's own fields, named as the command declares them. See [Commands](/sdk/commands/) for the fields each command takes.  
`command_id`|  _string_| `false`| An id of your choosing for the new command, instead of the one the response returns.  
`commit`|  _boolean_| `false`| Commit the command as well as creating it. Defaults to `false`, leaving it staged for a human to finish.  
`metadata`|  _object_| `false`| A flat `{"key": "value"}` map attached to the command. See [Command metadata](/sdk/effect-command-metadata/).  
Responds `201` with the id of the command it wrote and whether it was committed:
    ```json
    { "command_uuid": "2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10", "committed": false }
    ```
A body using every field:
    ```json
    {
      "note_id": "d2194110-5c9a-4842-8733-ef09ea5ead11",
      "command_id": "2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10",
      "commit": true,
      "values": { "narrative": "Patient reports a dry cough for three days." },
      "metadata": { "source": "intake-form", "submission": "8871" }
    }
    ```
If anything is wrong with the request, nothing is written and you get a `400` instead. A value that the command refuses is reported against the field it came from:
    ```json
    {
      "error": "Validation failed",
      "validation_errors": [
        { "field": "values.narrative", "message": "String should have at most 512 characters" }
      ]
    }
    ```
A problem with the envelope rather than the values reads the same way, without the `values.` prefix — here a body that left `note_id` out:
    ```json
    {
      "error": "Validation failed",
      "validation_errors": [
        { "field": "note_id", "message": "Field required" }
      ]
    }
    ```
Every field at fault is reported at once, so a caller sees the whole list rather than fixing one problem per round trip. The other statuses this route can answer with are in Responses.
###  edit 
`edit(model, command_id)` updates a **staged** command. The command is addressed by id in your route, and the body carries `values` and `metadata`:
    ```json
    { "values": { "narrative": "Patient reports a dry cough for three days." } }
    ```
> **Warning:** `values` replaces the command's fields as a whole and is re-validated in full — it is not a patch. A field you leave out is not left alone; send the complete set of values you want the command to end up with.
Responds `200`:
    ```json
    { "command_uuid": "2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10", "mode": "edit" }
    ```
Three things can go wrong, and each is checked before anything is written.
**The id matches no command of this type** — a `404`:
    ```json
    { "error": "No hpi command with that id" }
    ```
**The command is not staged** — a `400` naming the state it is in and the one the operation needed. A committed command cannot be edited; enter it in error and originate its replacement instead:
    ```json
    {
      "error": "a committed command cannot be edited",
      "state": "committed",
      "required_state": "staged",
      "validation_errors": []
    }
    ```
**A value is wrong for its field** — a `400` in the same shape `originate` returns, reported against `values.<field>`. A body that is not a JSON object at all is a `400` too, carrying `"Request body must be a JSON object"`.
See State for which operations each state allows, and Responses for the full list of statuses.
###  action 
`action(model, command_id, action)` runs one of the command's own methods. It takes no request body, and responds `200` naming what it did:
    ```json
    { "command_uuid": "2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10", "mode": "commit" }
    ```
`action` names a method on the command class, and each one builds the corresponding [command effect](/sdk/effects/#commands):
Action| What it does| Required state  
---|---|---  
`commit`| Signs the staged command into the note.| staged  
`delete`| Removes the staged command from the note.| staged  
`enter_in_error`| Marks a committed command as entered in error.| committed  
`review`| Places the command into review status.| set by the command — see State  
`send`| Transmits the command to an external system.| set by the command — see State  
`delegate`| Delegates the order to someone else to complete.| set by the command — see State  
`sign`| Signs the order.| set by the command — see State  
**No command supports all of them, and not even`commit` is universal.** Which actions a command accepts is listed per command in [Commands](/sdk/effects/#commands) — check there before wiring a route, because an action the command does not support is a `400`. The ones worth knowing up front:
  - `review` and `send` belong to [Prescribe](/sdk/commands/#prescribe), [Refill](/sdk/commands/#refill) and [Adjust Prescription](/sdk/commands/#adjustprescription), and `send` also to [Lab Order](/sdk/commands/#laborder). Those four are **not** committed — sending is how they are finished.
  - `delegate` and `sign` belong to [Imaging Order](/sdk/commands/#imagingorder) and [Refer](/sdk/commands/#refer), which are not committed either.
  - [Reason for Visit](/sdk/commands/#reasonforvisit) supports `originate`, `edit` and `delete` only.
  - [Chart Section Review](/sdk/commands/#chartsectionreview) is committed as it is originated, so it takes `originate` and nothing else.
  - [Custom commands](/sdk/commands-custom-command/) render read-only content, so they are neither edited nor committed.
An action the command class does not have is a `400`:
    ```json
    { "error": "HistoryOfPresentIllnessCommand does not support the 'review' action", "validation_errors": [] }
    ```
> **Danger:** The action usually arrives from the request, and it is passed to `getattr` on the command. Check it against a set you control first — as `ALLOWED_ACTIONS` does above — or a caller can name any attribute of the command class.
##  Field values 
`values` carries the command's own fields, named exactly as the command declares them. Each command's fields are listed under [Commands](/sdk/commands/) — `values` accepts the same set, so that page is the reference for what may go in here.
Commands parse leniently, so JSON's own types are enough. Posting to an [Allergy](/sdk/commands/#allergy) endpoint:
    ```json
    {
      "note_id": "d2194110-5c9a-4842-8733-ef09ea5ead11",
      "values": {
        "narrative": "Hives within an hour of eating shellfish.",
        "severity": "mild",
        "approximate_date": "2026-08-04"
      }
    }
    ```
  - `narrative` is a plain string, capped at 512 characters by the command.
  - `severity` is an enum, given as its value — `"mild"`, not `AllergyCommand.Severity.MILD`.
  - `approximate_date` is a date, given as an ISO string.
  - A number may arrive as a number or as a string: `12` and `"12"` are both read as `12`.
A key that is not a field on the command is **refused** , not dropped — silently ignoring a typo would write a blank command over it. Every unknown key is reported at once, against `values.<field>`:
    ```json
    {
      "error": "Validation failed",
      "validation_errors": [
        { "field": "values.narative", "message": "Unexpected field" }
      ]
    }
    ```
`note_id`, `command_id`, `commit` and `metadata` are the envelope, not fields — they sit alongside `values`, not inside it, and they are kept out of what the command writes.
###  Structured fields 
Not every field is a scalar. A number of commands take a structured value — an object, or a list of them — and each arrives as ordinary nested JSON. You do not construct the SDK type; you send its shape:
Type| Example value  
---|---  
[`Allergen`](/sdk/commands/#allergy-allergen)| `{"concept_id": 91, "concept_type": 2}`  
[`Coding`](/sdk/commands/#coding)| `{"system": "http://snomed.info/sct", "code": "44054006", "display": "Diabetes mellitus type 2"}`  
[`ClinicalQuantity`](/sdk/commands/#clinicalquantity)| `{"representative_ndc": "0093-1023", "ncpdp_quantity_qualifier_code": "C48542"}`  
[`ServiceProvider`](/sdk/commands/#serviceprovider)| `{"first_name": "Ada", "last_name": "Lovelace", "specialty": "Cardiology", "practice_name": "Mercy"}`  
[`TaskAssigner`](/sdk/commands/#taskassigner)| `{"to": "staff", "id": 5}`  
[`TestValue`](/sdk/commands/#poclabtest-testvalue)| `[{"label": "Glucose", "value": "98"}]`  
[`CompoundMedicationData`](/sdk/commands/#prescribe-compoundmedicationdata)| `{"formulation": "cream", "potency_unit_code": "C28253", "controlled_substance": "0"}`  
[`Answer` and `Selection`](/sdk/commands/#questionnaire-answer)| `[{"question_id": 15, "response": [{"option_id": 201, "comment": "left side"}]}]`  
Each type's own fields are documented with the command that uses it — follow the link for what is required and what each field means.
> **Warning:** An enum nested inside one of these is given by its **value** , not its name. `Allergen.concept_type` takes `2`, not `"MEDICATION"`; `TaskAssigner.to` takes `"staff"`, not `"STAFF"`. A name is refused with an `enum` validation error naming the values it will accept.
Answering a questionnaire is the largest of these, and the whole [`answers`](/sdk/commands/#questionnaire) list goes in `values` like any other field:
    ```json
    {
      "note_id": "d2194110-5c9a-4842-8733-ef09ea5ead11",
      "values": {
        "questionnaire_id": "c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "answers": [
          { "question_id": 12, "response": "Three times a week." },
          { "question_id": 13, "response": 42 },
          { "question_id": 14, "response": 101 },
          { "question_id": 15, "response": [{ "option_id": 201 }, { "option_id": 202, "comment": "left side" }] }
        ]
      }
    }
    ```
The same route serves [Review of Systems](/sdk/commands/#review-of-systems), [Structured Assessment](/sdk/commands/#structuredassessment) and [Physical Exam](/sdk/commands/#physicalexam), which take `answers` too.
##  Metadata 
`metadata` attaches a flat `{"key": "value"}` map to the command. It is stored as sent and nothing in Canvas interprets it, which makes it the place to record what the entry meant on your side:
    ```json
    {
      "note_id": "d2194110-5c9a-4842-8733-ef09ea5ead11",
      "values": { "narrative": "Patient reports a dry cough for three days." },
      "metadata": { "source": "intake-form", "submission": "8871", "version": "2" }
    }
    ```
Both `originate` and `edit` accept it. Values must be strings — send `"8871"`, not `8871`.
Each pair becomes an `upsert_metadata` effect applied after the effect that writes the command, so a key sent twice ends up holding the last value. See the [Command Metadata effect](/sdk/effect-command-metadata/) for how the same storage is written from a plugin, the [Command Metadata Create form effect](/sdk/command-metadata-create-form-effect/) for collecting it from a user in the chart, and [CommandMetadata](/sdk/data-command/#commandmetadata) for reading it back.
##  Responses 
Status| When  
---|---  
`201`| The command was created.  
`200`| An edit or an action was applied.  
`400`| The body is not a JSON object, a value is wrong for its field, or the command's state does not allow the operation.  
`404`| No command **of this type** has that id. The lookup is scoped by command type, so an id belonging to a different command is a miss rather than a cross-type edit.  
`409`| The `command_id` you chose already belongs to a command.  
**Every rejection has the same shape** — an `error` summarising it and a `validation_errors` list, empty when nothing field-specific was at fault. A caller can render all of them the same way.
A value that is wrong for its field:
    ```json
    {
      "error": "Validation failed",
      "validation_errors": [
        { "field": "values.narrative", "message": "Input should be a valid string" }
      ]
    }
    ```
A body that is not a JSON object at all:
    ```json
    { "error": "Request body must be a JSON object", "validation_errors": [] }
    ```
An id matching no command of this endpoint's type:
    ```json
    { "error": "No hpi command with that id" }
    ```
That `404` covers three cases at once, deliberately: no command has the id, a command has it but is of a different type, or the id is not a well-formed UUID. The lookup is scoped to the command type this endpoint serves, so an id belonging to a Plan command reaching a History of Present Illness endpoint is a miss rather than a cross-type edit.
###  Choosing the command's id 
Passing `command_id` is worth doing when the thing you are writing already has an identity on your side: you can then ask whether it reached the chart by that id rather than storing a mapping.
**It has to be a real UUID.** It is not a free-text key of your own, so generate one rather than composing it:
    ```shell
    uuidgen                        # 2588AA22-9D0E-4F1F-9B28-6F0E6A1C9A10
    python -c 'import uuid; print(uuid.uuid4())'
    node  -e 'console.log(crypto.randomUUID())'
    ```
Anything that will not parse as a UUID is a `400` before the command is looked at — `"order-8871"` gives `Input should be a valid UUID, invalid character: found 'o' at 1`, and `"8871"` gives `Input should be a valid UUID, invalid length`. The 32-character form without dashes is accepted, so either `2588aa22-9d0e-4f1f-9b28-6f0e6a1c9a10` or `2588aa229d0e4f1f9b286f0e6a1c9a10` will do.
If your own identifier is not a UUID, derive one from it deterministically — `uuid.uuid5()` over a namespace and your key — so the same record always produces the same command id.
Posting the same id twice answers `409` rather than writing a second command, which makes a retry safe:
    ```json
    { "error": "a command already has that id", "command_uuid": "2588aa22-…", "validation_errors": [] }
    ```
###  State 
Some operations only apply to a command in a particular state. Which operations a command accepts at all is a separate question, answered per command by the [command type table](/sdk/effects/#commands).
Operation| Required state  
---|---  
`edit`| staged  
`delete`| staged  
`commit`| staged  
`enter_in_error`| committed  
`review`, `send`, `delegate`, `sign`| Whatever the command requires. `CommandAPI` sets no state for these; the command enforces its own rules as it builds the effect.  
A refusal is a `400`, naming the state the command is in and the one it needed:
    ```json
    {
      "error": "a committed command cannot be edited",
      "state": "committed",
      "required_state": "staged",
      "validation_errors": []
    }
    ```
##  Naming route handlers 
A route handler cannot be called `originate`, `edit` or `action` — those are the methods you are calling. Name handlers for the HTTP verb they serve.

---

# SimpleAPI HTTP

Source: https://docs.canvasmedical.com/sdk/handlers-simple-api-http/

The Canvas SDK provides a way to define an HTTP API with any number of endpoints in your instance. Developers can define the routes and implement the code that will handle incoming HTTP requests.
This feature allows developers to create endpoints that can receive webhook events from other services. An endpoint receiving a request can invoke Effects in a Canvas instance, send another request to a different service, or simply return a response back to the requester.
##  Quickstart 
Follow the instructions in [Your First Plugin (with Claude Code)](https://docs.canvasmedical.com/guides/your-first-plugin-with-claude-code/) to create a plugins project. For this exercise, use `my_api` as your project (i.e. plugin) name.
Open [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/) in your editor. You can modify filenames, directory structures, and class names as you see fit in your project, but for this exercise, we are just going to set the value at `components -> handlers -> 0 -> class` to be `my_api.handlers.my_handler:MyAPI`.
We're going to need a secret value for authentication. The instructions for declaring secrets are outlined on the [Your First Plugin (Manual)](https://docs.canvasmedical.com/guides/your-first-plugin/) page. Declare a secret in `CANVAS_MANIFEST.json` named `my-api-key`.
Open `my_api/handlers/my_handler.py` and replace the contents of the file with this code:
    ```python
    from hmac import compare_digest
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            provided_api_key = credentials.key
            api_key = self.secrets["my-api-key"]
            # compare_digest requires bytes, so we must encode the strings
            return compare_digest(provided_api_key.encode(), api_key.encode())
        def get(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Hello world!"})
            ]
    ```
The next step is to deploy your plugin; the instructions for doing so are on the [Your First Plugin (Manual)](https://docs.canvasmedical.com/guides/your-first-plugin/) page.
You can see in the code above that the `authenticate` method is going to authenticate using API key authentication. We've already declared the secret, so now we need to generate a value and set it on your instance. You can generate an API key like this:
    ```shell
    python -c "import secrets; print(secrets.token_hex(16))"
    ```
Copy the value that it prints out and set the value for `my-api-key` in your plugin secrets on your instance.
Now that your plugin is deployed and your secret is set, you can send requests to your endpoint with `curl`. The `curl` command would look like the following (note that you will need to supply your instance name and API key):
    ```shell
    curl --location 'https://<instance-name>.canvasmedical.com/plugin-io/api/my_api/routes/hello-world' \
         --header 'Authorization: <api-key>'
    ```
##  Defining APIs 
The Canvas SDK offers two styles for defining API endpoints. To implement an API endpoint or set of endpoints using one of the two styles, your handler will simply inherit from a specific base class. The following HTTP verbs are supported:
  - GET
  - POST
  - PUT
  - DELETE
  - PATCH
###  SimpleAPIRoute 
For handlers that inherit from **SimpleAPIRoute** , you set a class variable in your handler called `PATH` as in the example above, and then implementations of the HTTP verbs you wish to support on that path. The method names will match the names of the HTTP verbs, but lowercased.
The plugin name and the `PATH` value together will form the unique part of the full URL for your endpoint. The format of the full URL will be:
`https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/<PATH>`
We can adapt the previous example to add a POST endpoint for the same route on the same handler:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            ...
        def get(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Hello world from my GET endpoint!"})
            ]
        def post(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Hello world from my POST endpoint!"})
            ]
    ```
The handler can now respond to both GET and POST requests at `/routes/hello-world`.
###  SimpleAPI 
For handlers that inherit from **SimpleAPI** , the syntax is a little different. You can include any number of endpoints in your handler class, and you can name your route handling methods anything you wish. Here is an example:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPI, api
    class MyAPI(SimpleAPI):
        PREFIX = "/routes"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            ...
        @api.get("/hello-world")
        def hello_world_get(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Hello world from my GET endpoint!"})
            ]
        @api.post("/hello-world")
        def hello_world_post(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Hello world from my POST endpoint!"})
            ]
        @api.get("/goodbye")
        def goodbye_get(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Goodbye from my GET endpoint!"})
            ]
    ```
This syntax will be familiar if you have used Python API frameworks like `Flask` or `FastAPI`. The decorator functions are named for the HTTP verb you wish to implement on the route, and the URL path is passed into the decorator function. If you have many endpoints that you wish to share the same authentication, this syntax may be more convenient.
You can also specify a path `PREFIX` value for endpoint grouping purposes, as shown in the example above. If you have multiple endpoints that will all have the same path prefix, you can specify it by setting a value for `PREFIX`. With `PREFIX` set, each endpoint does not have to individually specify the `/routes` portion of the URL path.
###  Path patterns 
If you want to set up an endpoint that will respond to requests where the path matches a pattern rather than an exact string, you can use a path pattern. This is common in cases where the path of an endpoint contains a resource identifier.
You can specify a path pattern by by denoting any number of the path parameters in the path using `<>` syntax, with the name of the path parameters in between the angle brackets. Path parameter names must be be unique within the path. They can also be specified in the path prefix (for **SimpleAPI** handlers).
Path parameters will be extracted from the path and will be available on the request object in the `path_params` attribute.
In the example below, the value `id` is specified as part of the path, and can be accessed by the handler:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world/<id>"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            ...
        def get(self) -> list[Response | Effect]:
            id_ = self.request.path_params["id"]
            return [
                JSONResponse(
                    {
                        "message": "Hello world from my GET endpoint!",
                        "id": id_
                    }
                )
            ]
    ```
####  Path matching 
When you specify routes using path patterns, it is possible that multiple endpoints may match with a request. This has a few implications that need to be considered, because only one endpoint can provide a response.
If the endpoints that match are all part of the same handler class, then the request will be handled by the endpoint that appears highest up in the class definition, i.e. the one that is defined first. Consider two endpoints specified to match the following patterns:
    /routes/hello-world/current-user
    /routes/hello-world/<id>
The first uses an exact match, and the second uses a pattern. The path `/routes/hello-world/current-user` matches both of those patterns. However, if you register the second endpoint first it would never be possible for a request with the path of `/routes/hello-world/current-user` to match with the endpoint for `/routes/hello-world/current-user`. If you need to define endpoints that use exact matching that may overlap with endpoints defined with path patterns, order must be carefully considered.
If, however, you have defined multiple **SimpleAPIRoute** or **SimpleAPI** handlers, and a request matches with multiple endpoints across these handlers, an error condition will result. There is not a way to specify priority across handlers, so if you need fine-grained control over request routing for endpoints that use path patterns, make sure they are contained within the same handler class.
###  Request objects 
When a handler is invoked to handle an incoming HTTP request, the request object is available as an attribute on the handler. The request method, path, query parameters, content type, and body are all available as attributes on the request object:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    from logger import log
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            ...
        def get(self) -> list[Response | Effect]:
            request = self.request
            # HTTP method
            method = request.method
            # URL path component
            path = request.path
            # Raw query string
            query_string = request.query_string
            # Query parameters as a key-value mapping
            query_params = request.query_params
            # Request headers
            headers = request.headers
            # Request body content type
            content_type = request.content_type
            # Raw body
            body = request.body
            # JSON body as a Python dictionary (for requests with application/json content types)
            json_body = request.json()
            # Body as plain text
            text_body = request.text()
            # Body parsed as form data
            form_data = request.form_data()
            return [
                JSONResponse({"message": "Hello world!"})
            ]
    ```
####  Key-value mappings 
Attributes on the request object like headers, query parameters, and form data can in most cases be represented by mappings containing key-value pairs (e.g. Python dictionaries) with a small caveat: keys are not required to be unique. Because of this, there can be more than one value per key.
These attributes are represented by a data structure that most of the time will behave like a Python dictionary, unless you want to access the additional values for a key. If you do request the value for a key using standard dictionary syntax, you will get the first value that was encountered for that key. If you want the other values, you will need to use different methods to access them.
Here is an example showing how to access the additional values:
    ```python
    # Request sent to /route?value1=a&value1=b&value2=c
    query_params = request.query_params
    # Get the first value for value1
    value1: str = query_params["value1"]
    # Get all values for value1 with get_list
    value1_all: list[str] = query_params.get_list("value1")
    # Iterate over all query parameters (repeating keys if necessary) with multi_items
    for key, value in query_params.multi_items():
        log.info(f"key:   {key}")
        log.info(f"value: {value}")
    ```
####  Forms 
If your endpoint is set up to accept `application/x-www-form-urlencoded` or `multipart/form-data` data, there is method named `form_data` on the request object that will parse the request body. This method will return a key-value mapping containing `FormPart` objects, each of which represents a subpart of the form.
Every subpart in a form has a name, and these names are the keys in the mapping that is returned by the method. A `FormPart` can represent either a simple string value or a file. A `FormPart` that represents a string will have attributes for `name` and `value`. A `FormPart` that represents a file will have attributes for `name`, `filename`, `content`, `content_type`.
If the content type of a request is `application/x-www-form-urlencoded`, then all `FormPart` objects will represent simple string values. If the content type of a request is `multipart/form-data`, then each `FormPart` object may represent either a simple string value or a file.
Here is an example of how to use the `form_data` method to iterate over the subparts of a request body with form data:
    ```python
    form_data = request.form_data()
    # To iterate over all parts, we have to use the multi_items method because there may be more than
    # one part with the same name
    for name, part in form_data.multi_items():
        log.info(f"part name:    {name}")
        if part.is_file():
            # It's a file
            log.info(f"content:      {part.content}")
            log.info(f"filename:     {part.filename}")
            log.info(f"content type: {part.content_type}")
        else:
            # It's a simple string
            log.info(f"value:        {part.value}")
    ```
If you know the name of the subparts you are looking for, you can also access the subparts directly by looking up the name in the mapping returned by `form_data`:
    ```python
    form_data = request.form_data()
    # Get the first part named "my-part-name"
    part = form_data["my-part-name"]
    # Get all parts named "my-part-name"
    parts_all = form_data.get_list("my-part-name")
    ```
####  Storing uploaded files 
To save an uploaded file on a Canvas record, declare the route with `file_uploads="stored"`. Examples include an insurance card image on a coverage or an attachment on a message. Canvas then stores each file in a `multipart/form-data` request before your handler runs, and `form_data()` returns a `StoredFilePart` for each file field instead of the file's bytes. Pass the part's `key` to an effect that accepts upload keys:
  - [`Coverage`](/sdk/effect-coverage/): `card_image_front_upload_key` and `card_image_back_upload_key`
  - [`PatientIdentificationCard`](/sdk/effect-patient-identification-card/): `image_upload_key`
  - [`Message`](/sdk/effect-messages/#attaching-files): `attachment_upload_keys`
  - [`VisualExamFindingCommand`](/sdk/commands/#visualexamfinding): `image_upload_key`
The file never passes through your plugin or the effect payload.
`file_uploads="stored"` works on POST and PUT routes only. On a `SimpleAPI` class, pass it to the decorator. On a `SimpleAPIRoute`, set the class attribute `FILE_UPLOADS = "stored"`, which applies to its `post` and `put` methods. Setting `FILE_UPLOADS` on a `SimpleAPIRoute` that has no `post` or `put` method raises a `PluginError` when the class is defined. The default is `"passthrough"`, which passes file bytes to your handler.
A route declared with `file_uploads="stored"` takes `multipart/form-data` requests only. Canvas answers a request with any other content type with **400 Bad Request** without calling your handler.
A `StoredFilePart` has these attributes:
Attribute| Type| Description  
---|---|---  
`name`| `str`| The name of the form field.  
`filename`| `str`| The filename the client sent.  
`content_type`| `str` or `None`| The content type the client declared for the file.  
`content_length`| `int`| The size of the file in bytes.  
`key`| `str` or `None`| The key of the stored file. `None` when the upload failed.  
`error`| `str` or `None`| A code such as `"s3_upload_failed"` when the upload failed; otherwise `None`.  
Canvas stores each file separately, so one failed file doesn't stop the others in the request. When every file in the request fails, Canvas answers with **502 Bad Gateway** without calling your handler. Otherwise, failed uploads come back alongside successful ones, so check `error` before you read `key`:
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import SimpleAPI, StaffSessionAuthMixin, api
    class UploadAPI(StaffSessionAuthMixin, SimpleAPI):
        @api.post("/upload", file_uploads="stored")
        def upload(self) -> list[Response | Effect]:
            part = self.request.form_data()["file"]
            if part.error:
                return [JSONResponse({"error": part.error}, status_code=HTTPStatus.BAD_GATEWAY)]
            # Pass part.key to an effect that accepts upload keys
            return [JSONResponse({"key": part.key})]
    ```
Pass each key to an effect from the plugin that uploaded the file, and upload a file of a type the effect accepts. When the effect is applied, Canvas copies the file to the record under a new name, so the uploader's filename isn't kept, and then deletes the upload. Use each key in one effect only.
The image keys on `Coverage` and `VisualExamFindingCommand` are optional, as is `image_upload_key` on a `PatientIdentificationCard` update. Setting one of these to `None` attaches no file and leaves any existing file in place. You can pass the key of a file input the user left empty without checking it first.
When you switch an existing route to `file_uploads="stored"`, check for files with `part.is_file()` rather than `isinstance(part, FileFormPart)`. A `StoredFilePart` is not a `FileFormPart`, so an `isinstance` check skips every file.
###  Responses 
Endpoint handlers may return zero or one response objects and any number of Effects. Handlers that return multiple response objects will return a **500 Internal Server Error** response back to the requester. If your endpoint does not provide a response object, then the requester will receive a **204 No Content** response.
####  Response types 
Several response types are provided for convenience:
  - HTMLResponse
  - JSONResponse
  - PlainTextResponse
  - Response (for returning raw content)
In addition to the response body, you can also specify the response status code and the response headers.
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import HTMLResponse, JSONResponse, PlainTextResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            ...
        def get(self) -> list[Response | Effect]:
            return [
                HTMLResponse(
                    "<p>Hello world from my GET endpoint!</p>",
                    status_code=HTTPStatus.OK,
                    headers={"My-Header", "my header value"}
                )
            ]
        def post(self) -> list[Response | Effect]:
            return [
                JSONResponse(
                    {"message": "Hello world from my POST endpoint!"},
                    status_code=HTTPStatus.CREATED,
                    headers={"My-Header", "my header value"}
                )
            ]
        def put(self) -> list[Response | Effect]:
            return [
                PlainTextResponse(
                    "Hello world from my PUT endpoint!",
                    status_code=HTTPStatus.ACCEPTED,
                    headers={"My-Header", "my header value"}
                )
            ]
        def patch(self) -> list[Response | Effect]:
            return [
                Response(
                    b'{"message": "Hello world from my PATCH endpoint!"}',
                    status_code=HTTPStatus.NOT_MODIFIED,
                    headers={"My-Header", "my header value"},
                    content_type="application/json"
                )
            ]
    ```
When an `HTMLResponse` includes data from patients, integrations, or other external sources, build it with `render_to_string` and follow [Rendering untrusted data safely](/sdk/layout-effect/#rendering-untrusted-data-safely). Never include secrets in an HTML response.
####  Returning Effects 
**SimpleAPI** endpoints can return any number of Effects just like any Canvas plugin; this is why **SimpleAPI** endpoints return a list of items rather than just a single response object.
Any effects present in the list returned by an endpoint will be processed by your Canvas instance, and the response object, if provided, will be sent back to the original requester.
###  Asynchronous requests 
By default, **SimpleAPI** requests are processed synchronously—the caller waits for the plugin to finish executing before receiving a response. If you prefer an immediate acknowledgement instead, include the `Prefer: respond-async` header in your request:
    ```bash
    curl --location 'https://<instance-name>.canvasmedical.com/plugin-io/api/<plugin-name>/<route>' \
         --header 'Authorization: <api-key>' \
         --header 'Prefer: respond-async'
    ```
When this header is present, Canvas will return a **202 Accepted** response right away and continue executing the plugin in the background. Any effects returned by the handler will still be processed by your Canvas instance; however, no response body from the handler will be delivered to the caller.
Note that authentication failures and plugin-not-found errors are always returned synchronously, regardless of this header.
###  Authentication 
Defining an `authenticate` method on your handler is required. By default, **SimpleAPI** handlers will return a **401 Unauthorized** response if no `authenticate` method is defined. The `authenticate` method should return `True` or `False` depending on whether the requester is authenticated.
Please keep in mind that while setting plugins secrets on your instance is out of scope for this guide, best practices would dictate that most `authenticate` methods would use these secrets to authenticate credentials in a request (OAuth being a notable exception). Your secrets can be accessed through the `secrets` attribute on the handler.
Additionally, to assist with adhering to security and cryptography best practices, the Python `hashlib`, `hmac`, and `secrets` modules are available for use.
Examples of how to define `authenticate` methods for various authentication schemes are shown in the next section, but if you are interested in something that is more "batteries included", please skip ahead to the Authentication mixins section below. The API key authentication mixin is a good choice that offers simplicity and good security if you need something to get started.
####  Authentication schemes 
The Canvas SDK can parse and validate the format of the Authentication header automatically for several authentication schemes, but you must authenticate the credentials in your `authenticate` method. You can specify which authentication scheme you want to use for your route or API in the method signature of your `authenticate` method.
#####  Basic 
For Basic authentication, use `BasicCredentials`:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Response
    from canvas_sdk.handlers.simple_api import BasicCredentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: BasicCredentials) -> bool:
            provided_username = credentials.username
            provided_password = credentials.password
            # Validate provided username and password against a username and password in self.secrets
            ...
        def get(self) -> list[Response | Effect]:
            ...
    ```
#####  Bearer 
For Bearer authentication, use `BearerCredentials`:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Response
    from canvas_sdk.handlers.simple_api import BearerCredentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: BearerCredentials) -> bool:
            provided_token = credentials.token
            # Validate provided access token via OAuth
            ...
        def get(self) -> list[Response | Effect]:
            ...
    ```
#####  API key 
For API key authentication, use `APIKeyCredentials`:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Response
    from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: APIKeyCredentials) -> bool:
            provided_api_key = credentials.key
            # Validate provided key against an API key in self.secrets
            ...
        def get(self) -> list[Response | Effect]:
            ...
    ```
#####  Session 
To authenticate using a logged-in user's session, use `SessionCredentials`:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Response
    from canvas_sdk.handlers.simple_api import SessionCredentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: SessionCredentials) -> bool:
            logged_in_user = credentials.logged_in_user
            # Structure looks like:
            # {
            #     "id": "abc123",
            #     "type": "Staff"
            # }
            # Where "type" is "Staff" or "Patient"
            # You could authenticate based on type or check to see if the
            # individual is in a particular group or team.
            ...
        def get(self) -> list[Response | Effect]:
            ...
    ```
#####  Custom 
It's also possible to create custom authentication schemes. There are two ways to do this.
The first way is to access authentication headers on the request object directly. If you wish to do this, then you would define your authenticate method to take a `Credentials` object, and pull the authentication values from the request headers:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Response
    from canvas_sdk.handlers.simple_api import Credentials, SimpleAPIRoute
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: Credentials) -> bool:
            provided_api_key = self.request.headers["My-API-Key"]
            provided_app_key = self.request.headers["My-App-Key"]
            # Validate provided credentials against the credentials in self.secrets
            ...
        def get(self) -> list[Response | Effect]:
            ...
    ```
Another way to do this is by defining your own `Credentials` subclass which obtains the authentication values out of the request headers:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Response
    from canvas_sdk.handlers.simple_api import Credentials, SimpleAPIRoute
    from canvas_sdk.handlers.simple_api.api import Request
    class MyCredentials(Credentials):
        def __init__(self, request: Request) -> None:
            self.api_key = self.request.headers['My-API-Key']
            self.app_key = self.request.headers['My-App-Key']
    class MyAPI(SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def authenticate(self, credentials: MyCredentials) -> bool:
            provided_api_key = credentials.api_key
            provided_app_key = credentials.app_key
            # Validate provided credentials against the credentials in self.secrets
            ...
        def get(self) -> list[Response | Effect]:
            ...
    ```
####  Authentication mixins 
The Canvas SDK offers several "batteries included" authentication mixins that you can use to implement your authentication method. If you choose to use these, then the only action you must take is to ensure that you set the appropriate secrets for your plugin on your instance.
Make sure you always list the mixin class to the left of the base class, which is **SimpleAPIRoute** in the examples below.
#####  Basic 
If you want an implementation of Basic authentication, you can use the `BasicAuthMixin`. You will need to declare the `simpleapi-basic-username` and `simpleapi-basic-password` secrets in your manifest file, and then set the secrets on your instance after you deploy your plugin.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import BasicAuthMixin, SimpleAPIRoute
    class MyAPI(BasicAuthMixin, SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def get(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Hello world!"})
            ]
    ```
#####  API key 
If you want an implementation of API key authentication, you can use the `APIKeyAuthMixin`. You will need to declare the `simpleapi-api-key` secret in your manifest file, and then set the secret on your instance after you deploy your plugin.
You can generate a secure, random API key like this:
    ```shell
    python -c "import secrets; print(secrets.token_hex(16))"
    ```
Copy the output from that command, and set the `simpleapi-api-key` secret on your instance.
After you set your secret, you can use the `APIKeyAuthMixin`:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import APIKeyAuthMixin, SimpleAPIRoute
    class MyAPI(APIKeyAuthMixin, SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def get(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Hello world!"})
            ]
    ```
#####  Staff Session 
If you want to ensure the visiting user is a logged in staff user, you can use the `StaffSessionAuthMixin`. This makes no assertions about the particular staff member, just that they are staff, and that they are logged in.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import StaffSessionAuthMixin, SimpleAPIRoute
    class MyAPI(StaffSessionAuthMixin, SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def get(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Hello world!"})
            ]
    ```
#####  Patient Session 
If you want to ensure the visiting user is a logged in patient user, you can use the `PatientSessionAuthMixin`. This makes no assertions about the particular patient, just that they are a patient, and that they are logged in.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import PatientSessionAuthMixin, SimpleAPIRoute
    class MyAPI(PatientSessionAuthMixin, SimpleAPIRoute):
        PATH = "/routes/hello-world"
        def get(self) -> list[Response | Effect]:
            return [
                JSONResponse({"message": "Hello world!"})
            ]
    ```
##  Acting as a Canvas user 
By default, a SimpleAPI request isn't tied to a specific person, so any effects it returns — such as creating, locking, or signing a note — are recorded as Canvas Bot rather than a clinician.
To have a request run **as a specific Canvas staff member** — for example, so a note is signed under the treating provider's name — call the endpoint with an access token obtained through the [Authorization Code flow](/api/customer-authentication#authorization-code). That flow issues a token that represents the staff member who signed in and approved it. Send it as a Bearer token in the `Authorization` header, and Canvas identifies the user from the token and treats the request as coming from them, so any effects the handler returns are attributed to that staff member.
    ```bash
    curl --request POST \
      --url 'https://example.canvasmedical.com/plugin-io/api/my_plugin/note/<note-id>/sign' \
      --header 'Authorization: Bearer <access-token>'
    ```
In this example the note is signed and recorded in Canvas as signed by the staff member who authorized the access token, not by Canvas Bot.
##  Common use cases 
SimpleAPI is the supported way to react to external (non-Canvas) events and to expose functionality that the FHIR API does not cover. A few recurring patterns:
###  Reacting to external events 
Effects such as Protocol Cards can normally only be created in response to internal Canvas events. To create one from an outside trigger, expose a SimpleAPI endpoint that accepts the external request and returns the corresponding effect. This makes SimpleAPI the supported entry point for any workflow that needs to be initiated from outside of Canvas.
###  Originating commands that have no FHIR resource 
Many commands, such as HPI, Assessment, and Plan, have no FHIR resource, because the standard has nothing at that level of detail. To write them from outside Canvas, expose a SimpleAPI endpoint that originates the commands with the classes in the [command module](/sdk/commands/). [`CommandAPI`](/sdk/handlers-simple-api-commands/) builds such an endpoint for you: it reads the request body onto a command, validates it, and writes the command to the note. Use `Command.objects` from the data module to check for an existing command or to find one to edit.
###  Calling SimpleAPI from an external application 
External applications, such as a Node.js service, integrate with Canvas by calling the SimpleAPI endpoints you define in your plugin. Each endpoint returns [effects](/sdk/effects/) that make the change in Canvas.
###  Creating or updating patients from a third-party webhook 
To process a third-party webhook, such as a form submission, point it at a SimpleAPI `POST` endpoint. Your handler controls how the incoming data maps onto the patient, so it can transform fields, check them, and save values the FHIR API can't, such as custom patient metadata. Build a [Patient effect](/sdk/effect-patient/) from the request body, including any custom values in its `metadata`, and return its `create()` or `update()`. The patient and their metadata are saved together.
###  Serving plugin frontends without leaking secrets 
If your plugin serves an HTML/JS UI (for example a vitals chart), do **not** embed secrets or credentials in client-side JavaScript to call third-party APIs directly. Instead, have your JavaScript call a SimpleAPI endpoint provided by the same plugin and protected with the staff session authentication mixin. The plugin's Python code holds the secrets and makes the authenticated outbound request. This works as long as the HTML/JS is served from the plugin. See the [vitals visualizer example plugin](/sdk/example-vitals_visualizer_plugin/#vitals_visualizationhtml) for a working implementation.
##  Troubleshooting 
###  A SimpleAPI endpoint returns 404 
A 404 from an endpoint you believe is deployed usually means the plugin failed to load at reload time even though the deploy appeared to succeed — a runtime error when the plugins reload on the server. Keep two shells open: deploy in one and run `canvas logs` in the other to catch the load failure (and the line number) as it happens. Note also that the **plugin name cannot contain a hyphen** (`-`); use underscores in both the plugin name and the class path, or routing will 404.
###  503 responses when originating many commands 
If you receive intermittent **503 No server is available** responses while issuing many command requests, have your client retry with [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff#Rate_limiting). To reduce the number of round trips, expose a SimpleAPI endpoint that originates and commits each command in one effect with `originate(commit=True)`:
    ```python
    from canvas_sdk.commands import PlanCommand
    # inside a SimpleAPI route; note_uuid identifies the target note
    command = PlanCommand(note_uuid=note_uuid)
    return [command.originate(commit=True)]
    ```

---

# SimpleAPI WebSocket

Source: https://docs.canvasmedical.com/sdk/handlers-simple-api-websocket/

WebSocket APIs in Canvas let you define **channels** that clients can connect to. These APIs support one-way, server-to-client communication, and are designed for use cases such as real-time notifications.
To use websockets in a Canvas plugin, you must define the WebSocketAPI auth handler to manage access to your channel, use the `Broadcast` effect to publish messages to that channel, and create client code to manage the connection, handle new messages, and gracefully reconnect.
###  Defining a WebSocket API 
To define a WebSocket handler, subclass `WebSocketAPI`. You must implement an `authenticate` method that determines whether the connection should be accepted.
    ```python
    from canvas_sdk.handlers.simple_api.websocket import WebSocketAPI
    class MyWebSocketAPI(WebSocketAPI):
        def authenticate(self) -> bool:
            ...
    ```
If `authenticate()` returns `True`, the connection is accepted. Otherwise, it is denied.
Clients should connect using a URL that maps to your plugin and channel name:
    wss://<instance>.canvasmedical.com/plugin-io/ws/<plugin_name>/<channel_name>/
###  WebSocket Object 
When a handler is invoked, the `websocket` object is available as an attribute on the handler. This object provides details about the connection, including:
  - `channel`: The channel name from the connection URL
  - `headers`: A dictionary of headers associated with the connection
  - `api_key`: The api key, if present
  - `logged_in_user`: A dictionary like `{ "id": ..., "type": ... }` if a logged-in user is present
You can access this object within your handler methods using `self.websocket`.
> **Info:** Channel names may only contain alphanumeric, hyphen, and underscore characters.
###  Authentication 
You must implement the `authenticate()` method in your handler class. Two authentication methods are supported:
####  Session-Based (Internal Clients) 
For connections initiated from within the Canvas browser UI by a logged-in user:
    ```python
    def authenticate(self) -> bool:
        logged_in_user = self.websocket.logged_in_user
        # Structure looks like:
        # {
        #     "id": "abc123",
        #     "type": "Staff"
        # }
        # Where "type" is "Staff" or "Patient"
        # You could authenticate based on type or check to see if the
        # individual is in a particular group or team.
        ...
    ```
####  APIKey-Based (External Clients) 
For external tools or scripts, pass an auth key as a query parameter:
    wss://<instance>.canvasmedical.com/plugin-io/ws/<plugin>/<channel>?api_key=<key>
The key is made available in your handler via `self.websocket.api_key`. You can store this key as a secret.
    ```python
    def authenticate(self) -> bool:
      provided_token = self.websocket.api_key
      # Validate provided key against an API key in self.secrets
      ...
    ```
###  Broadcasting Messages 
To send a message to all connected clients on a WebSocket channel, use the `Broadcast` effect. This effect can be returned from any handler.
The `Broadcast` effect takes the following parameters:
  - `message`: A JSON-serializable Python dictionary or value.
  - `channel`: The target channel name as a string.
Here's an example using a SimpleAPI HTTP POST route to trigger a broadcast:
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Broadcast, JSONResponse, Response
    from canvas_sdk.handlers.simple_api import Credentials, SimpleAPI, api
    class WebhookAPI(SimpleAPI):
        @api.post("/callback")
        def broadcast_message(self) -> list[Response | Effect]:
            body = self.request.json()
            return [
                Broadcast(message=body, channel="notifications").apply(),
                JSONResponse({"status": "ok"}, status_code=HTTPStatus.ACCEPTED),
            ]
    ```
In this example, when the `/callback` endpoint receives a POST request, it broadcasts the request body as a message to all clients subscribed to the `notifications` channel.

---

# SimpleAPI

Source: https://docs.canvasmedical.com/sdk/handlers-simple-api/

The Canvas SDK allows developers to define both HTTP and WebSocket APIs to integrate custom plugin logic into a Canvas instance.
[ HTTP APIDefine endpoints to handle incoming HTTP requests using custom logic and authentication. ](/sdk/handlers-simple-api-http) [ WebSocket APIEstablish real-time communication channels for interactive plugin behavior and updates. ](/sdk/handlers-simple-api-websocket) [ Commands APIExpose commands as HTTP endpoints, validated against the command itself. ](/sdk/handlers-simple-api-commands)

---

# Handlers

Source: https://docs.canvasmedical.com/sdk/handlers/

The handlers module lets you define reactions to events.
Handlers respond to [Events](/sdk/events/) and return zero, one, or many [Effects](/sdk/effects/).
> **Danger:** **With great power comes great responsibility.** Your handler runs **synchronously** inside a worker. Slow handler code — especially code that makes a blocking network call to an external service (an LLM API, a third-party HTTP endpoint) — holds that worker for its entire duration. If the external service slows down or goes offline, every invocation piles up until the worker pool is exhausted, and your **entire Canvas instance can be negatively impacted or even temporarily stop responding to requests**. Long timeouts and retries multiply the damage: a 300 second timeout retried three times pins a single worker for over ten minutes. Keep your handler fast, and move long-running or failure-prone work off the synchronous path — see [Keep your handler fast](/sdk/handlers-basehandler/#keep-your-handler-fast).
There are some special types of handlers, like [Protocols](/sdk/protocols/) and [CronTasks](/sdk/handlers-crontask/). These offer a differentiated interface for their particular use-cases. For example, CronTasks only ever respond to the `CRON` event, require a schedule to be specified, and expect the `execute` method to be implemented rather than `compute`.
All handlers inherit from [BaseHandler](/sdk/handlers-basehandler/), which means you always have access to event and configuration data with the following accessors:
  - `self.event`
    - Information about the event including the event type
  - `self.context`
    - Data included as the event payload
  - `self.target`
    - Identifying information to help you reference the subject of the event
  - `self.secrets`
    - Configuration key-value store for your plugin
    - Secrets have their keys defined in the [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#variables) and their values are set by the Canvas instance administrator after installing your plugin via the Canvas UI on your plugin's configuration page
  - `self.environment`
    - Information about the Canvas instance your plugin is being executed on.
    - Available keys:
      - `CUSTOMER_IDENTIFIER` — the instance's subdomain (e.g. `acme` for `acme.canvasmedical.com`).
      - `INSTALLATION_TIME_ZONE` — the instance's configured time zone as an IANA name (e.g. `America/Los_Angeles`). Useful for rendering times to the customer's clinicians, scheduling work in their local day, or formatting dates in user-facing output.
    - Example: `self.environment['CUSTOMER_IDENTIFIER']`
## [ Action Button Add a button that executes your custom code when clicked. ![Abridged source code of an action button implementation.](/assets/images/sdk/handlers/ActionButton.png) ![Image of an action button in a note header.](/assets/images/sdk/handlers/action-button-in-action.png) ](/sdk/handlers-action-buttons/) ## [ Application Launch an iframe when your icon is clicked in the app drawer. ![Abridged source code of an application implementation.](/assets/images/sdk/handlers/Application-cropped.png) ![Image of application icons in the app drawer.](/assets/images/sdk/handlers/application-applied.png) ](/sdk/handlers-applications/) ## [ Cron Task Execute your code on a cron-like schedule. ![Abridged source code of an action button implementation.](/assets/images/sdk/handlers/CronTask-cropped.png) ![Picture of Mr. Cron, the little time monster that remembers which tasks should be executed at any given time.](/assets/images/sdk/handlers/mr-cron.png) ](/sdk/handlers-crontask/) ## [ Base Handler Respond to events with your custom code. ![Abridged source code of a base handler implementation.](/assets/images/sdk/handlers/BaseHandler-cropped.png) ![Stylized text that reads 'When X occurs, under Y conditions, I want Z to happen'.](/assets/images/sdk/handlers/base-handler-can-lend-a-hand.png) ](/sdk/handlers-basehandler/) ## [ Payment Processor Integrate a third-party payment provider to charge cards and manage saved payment methods. ![Abridged source code of a payment processor implementation.](/assets/images/sdk/handlers/PaymentProcessor-cropped.png) ![Illustration of a credit card payment being approved.](/assets/images/sdk/handlers/payment-processor-in-action.png) ](/sdk/handlers-payment-processors/) ## [ Embedded Application Render a tab inside a note, or replace the built-in scheduling modal. ![Abridged source code of a NoteApplication and SchedulingApplication implementation.](/assets/images/sdk/handlers/EmbeddedApplication-cropped.png) ![An embedded application rendered inside the Canvas UI.](/assets/images/sdk/handlers/embedded-application-in-action.png) ](/sdk/handlers-embedded-applications/) ## [ Patient Chart Summary Custom Section Serve content into a custom section of the patient chart summary. ![Abridged source code of a patient chart summary custom section handler implementation.](/assets/images/sdk/handlers/PatientChartSummaryCustomSection-cropped.png) ![A custom section rendered in the patient chart summary.](/assets/images/sdk/handlers/patient-chart-summary-custom-section-handler-in-action.png) ](/sdk/patient-chart-summary-custom-section-handler/) ## [ SimpleAPI Define HTTP and WebSocket API endpoints in your plugin. ![Abridged source code of a SimpleAPI route implementation.](/assets/images/sdk/handlers/SimpleAPI-cropped.png) ![A curl request to a SimpleAPI route and its JSON response.](/assets/images/sdk/handlers/simple-api-response.png) ](/sdk/handlers-simple-api/)

---

# Layout Effects

Source: https://docs.canvasmedical.com/sdk/layout-effect/

##  Patient Summary 
There are many summary sections in a patient's chart, organized by data type. While there is a default ordering, you can use an Effect to reorder them or hide some of them entirely. The `PatientChartSummaryConfiguration` class helps you craft the effect to do so.
![Before and after](/assets/images/sdk/summary-section-modified.png)
The example below shows reordering and hiding or omitting some of the sections:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.effects.patient_chart_summary_configuration import PatientChartSummaryConfiguration
    class SummarySectionLayout(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION)
        def compute(self):
            layout = PatientChartSummaryConfiguration(sections=[
              PatientChartSummaryConfiguration.Section.CARE_TEAMS,
              PatientChartSummaryConfiguration.Section.SOCIAL_DETERMINANTS,
              PatientChartSummaryConfiguration.Section.ALLERGIES,
              PatientChartSummaryConfiguration.Section.CONDITIONS,
              PatientChartSummaryConfiguration.Section.MEDICATIONS,
              PatientChartSummaryConfiguration.Section.VITALS,
            ])
            return [layout.apply()]
    ```
###  Methods 
####  apply() → Effect 
Sets the order and visibility of the chart summary sections. It is only used in response to the `PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION` event, and does nothing in any other context.
  - `sections` is required, with at least one section.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`sections`| `list[Section \| CustomSection]`| The sections to show, in order. Each is a `PatientChartSummaryConfiguration.Section` or a `PatientChartSummaryConfiguration.CustomSection(name=...)` for a custom section. Sections you leave out are hidden.| Yes  
Values in the `PatientChartSummaryConfiguration.Section` enum are:
Constant| Description  
---|---  
SOCIAL_DETERMINANTS| social_determinants  
GOALS| goals  
CONDITIONS| conditions  
MEDICATIONS| medications  
ALLERGIES| allergies  
CARE_TEAMS| care_teams  
VITALS| vitals  
IMMUNIZATIONS| immunizations  
SURGICAL_HISTORY| surgical_history  
FAMILY_HISTORY| family_history  
CODING_GAPS| coding_gaps  
###  Custom Sections 
In addition to the built-in sections above, you can add fully custom sections to the chart summary. Custom sections render plugin-provided content in an iframe and are identified by a unique key. See [Patient Chart Summary Custom Section Handler](/sdk/patient-chart-summary-custom-section-handler/) for details on how to implement one.
###  Action Buttons 
Each section of the patient chart can also be customized with action buttons. Please refer to the [Action Buttons](/sdk/handlers-action-buttons/) documentation for more information.
##  Patient Profile 
The `PatientProfileConfiguration` class allows you to reorder, hide, and/or specificy whether sections load expanded or collapsed.
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.effects.patient_profile_configuration import PatientProfileConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    class MyHandler(BaseHandler):
        """This protocol is used to configure which sections appear in the Patient Profile section.
        The SHOW_PATIENT_PROFILE_SECTIONS payload expects a list of sections where each section is a dict like { "type": str, "start_expanded": bool }
        The accepted values for the "type" are:
        "demographics", "preferences", "preferred_pharmacies", "patient_consents",
        "care_team", "parent_guardian", "addresses", "phone_numbers", "emails", "contacts"
        """
        # Name the event type you wish to run in response to
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PROFILE__SECTION_CONFIGURATION)
        def compute(self) -> list[Effect]:
            """This method gets called when an event of the type RESPONDS_TO is fired."""
            sections = [
                PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.PREFERENCES,
                                                                 start_expanded=False),
                PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.DEMOGRAPHICS,
                                                                 start_expanded=False),
                PatientProfileConfiguration.Payload(
                    type=PatientProfileConfiguration.Section.PREFERRED_PHARMACIES, start_expanded=True),
                PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.PARENT_GUARDIAN,
                                                                 start_expanded=False),
                PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.CONTACTS,
                                                    start_expanded=True),
                PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.CARE_TEAM,
                                                                 start_expanded=False),
                PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.TELECOM,
                                                                 start_expanded=False),
                PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.ADDRESSES,
                                                                 start_expanded=False),
                PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.PATIENT_CONSENTS,
                                                    start_expanded=False),
            ]
            effect = PatientProfileConfiguration(sections=sections).apply()
            return [effect]
    ```
###  Methods 
####  apply() → Effect 
Sets the order, visibility, and expansion of the patient profile sections. It is only used in response to the `PATIENT_PROFILE__SECTION_CONFIGURATION` event, and does nothing in any other context.
  - `sections` is required, with at least one section.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`sections`| `list[Payload]`| The sections to show, in order. Each `PatientProfileConfiguration.Payload` is a typed dictionary with a `type` (a `PatientProfileConfiguration.Section`) and a `start_expanded` boolean, which determines if the fields in that section are exposed by default.| Yes  
Values in the `PatientProfileConfiguration.Section` enum are:
Constant| Description  
---|---  
DEMOGRAPHICS| demographics  
PREFERENCES| preferences  
PREFERRED_PHARMACIES| preferred_pharmacies  
PATIENT_CONSENTS| patient_consents  
CARE_TEAM| care_team  
PARENT_GUARDIAN| parent_guardian  
ADDRESSES| addresses  
TELECOM| telecom  
CONTACTS| contacts  
##  Panel Configuration 
This effect allows you to define which panel buttons should be displayed on the main page or the patient page.
The order of the buttons in the array will determine their order on the panel.
![Before and after](/assets/images/sdk/panel-configuration-before-after.png)(width:70%)
    ```python
    from canvas_sdk.effects.panel_configuration import PanelConfiguration
    PanelConfiguration(
      sections=[
        PanelConfiguration.PanelPatientSection.REFILL_REQUEST,
        PanelConfiguration.PanelPatientSection.LAB_REPORT,
        PanelConfiguration.PanelPatientSection.CHANGE_REQUEST,
        PanelConfiguration.PanelPatientSection.TASK,
    ], page=PanelConfiguration.Page.PATIENT).apply()
    ```
###  Methods 
####  apply() → Effect 
Sets the panel buttons for the page.
  - `sections` and `page` are required.
  - Every section must match the page: `PanelGlobalSection` values for `GLOBAL`, `PanelPatientSection` values for `PATIENT`.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`sections`| `list[PanelPatientSection] or list[PanelGlobalSection]`| List of section items, in order.| Yes  
`page`| `Page`| `PATIENT` or `GLOBAL`.| Yes  
Values in the `PanelGlobalSection` enum are:
Constant| Description  
---|---  
APPOINTMENT| appointment  
CHANGE_REQUEST| changeRequest  
IMAGING_REPORT| imagingReport  
INPATIENT_STAY| inpatientStay  
LAB_REPORT| labReport  
MESSAGE| message  
OUTSTANDING_REFERRAL| outstandingReferral  
PRESCRIPTION_ALERT| prescriptionAlert  
RECALL_APPOINTMENT| recallAppointment  
REFERRAL_REPORT| referralReport  
REFILL_REQUEST| refillRequest  
TASK| task  
UNCATEGORIZED_DOCUMENT| uncategorizedDocument  
Values in the `PanelPatientSection` enum are:
Constant| Description  
---|---  
CHANGE_REQUEST| changeRequest  
COMMAND| command  
IMAGING_REPORT| imagingReport  
INPATIENT_STAY| inpatientStay  
LAB_REPORT| labReport  
PRESCRIPTION_ALERT| prescriptionAlert  
REFERRAL_REPORT| referralReport  
REFILL_REQUEST| refillRequest  
TASK| task  
UNCATEGORIZED_DOCUMENT| uncategorizedDocument  
##  Patient Note Header Dropdown Configuration 
The `PatientNoteHeaderDropdownConfiguration` effect allows you to define which items appear in the dropdown menu on a patient's note header (the triple dots at the top right of each note).
The order in the dropdown is preserved and grouped into specific sections, rather than being based on the plugin item order.
![Before and after](/assets/images/sdk/note-header-configuration.png)(width:60%)
    ```python
    from canvas_sdk.effects.patient_note_header_dropdown_configuration import PatientNoteHeaderDropdownConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects import Effect
    class NoteHeaderDropdownHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_NOTE_HEADER_DROPDOWN__SECTION_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [PatientNoteHeaderDropdownConfiguration(items=[
                PatientNoteHeaderDropdownConfiguration.Items.PRINT_NOTE,
                PatientNoteHeaderDropdownConfiguration.Items.PRINT_SUPERBILL,
                PatientNoteHeaderDropdownConfiguration.Items.LINK_TO_PHONE,
            ]).apply()]
    ```
###  Methods 
####  apply() → Effect 
Sets the items in the note header dropdown.
  - `items` is required, with at least one item.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`items`| `list[Items]`| List of dropdown items to display.| Yes  
Values in the `PatientNoteHeaderDropdownConfiguration.Items` enum are:
Constant| Description  
---|---  
LINK_TO_PHONE| Show QR code to link mobile device to note  
SOAP| Sort note sections in SOAP order (Subjective, Objective, Assessment, Plan)  
APSO| Sort note sections in APSO order (Assessment, Plan, Subjective, Objective)  
CHANGE_LOCATION| Change the note's practice location  
CHANGE_PROVIDER| Change the note's provider  
CHANGE_DATE_OF_SERVICE| Change the note's date of service  
PRINT_SUPERBILL| Print the superbill for billing  
PRINT_ROOMING_SHEET| Print the rooming sheet for care team  
PRINT_AFTER_VISIT_SUMMARY| Print the patient after visit summary  
COPY_LINK| Copy the note's permalink to clipboard  
PRINT_NOTE| Print the note for care team  
FAX_NOTE| Fax the note to an external recipient  
FAX_EVENT_HISTORY| View fax event history for the note  
MOVE_COMMANDS| Move commands from this note to another note  
##  Provider Menu Configuration 
The `ProviderMenuConfiguration` effect allows you to define which items appear in the provider menu (the hamburger menu at the top left of Canvas).
The effect replaces the default set of items, so every item that should stay visible has to be listed. Anything you omit is not rendered. If no installed plugin emits the effect, the menu renders unchanged.
Passing an empty list is allowed and hides every native item — useful if your plugin replaces the menu entirely with its own items.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.provider_menu_configuration import ProviderMenuConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class ProviderMenuHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.GET_PROVIDER_MENU_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [ProviderMenuConfiguration(items=[
                ProviderMenuConfiguration.Items.PATIENTS,
                ProviderMenuConfiguration.Items.CAMPAIGNS,
                ProviderMenuConfiguration.Items.SETTINGS,
            ]).apply()]
    ```
Three things the effect does not do:
  - **It does not reorder the menu.** Items render in Canvas's native order and grouping, regardless of the order you list them in.
  - **It does not grant access.** Permissions still apply on top, so an item you list will still render disabled for a user who lacks the permission for it.
  - **It does not affect plugin-provided menu items.** Applications with the `provider_menu_item` scope are independent of the allow-list.
The user's avatar and name, and the **Sign out** button, are always rendered and cannot be hidden.
Because this is an allow-list rather than a block-list, it does not pick up native items added in future Canvas releases. If a new item ships and you want it visible, add it to your list — otherwise it stays hidden on your instance.
####  When the allow-list is not applied 
Canvas falls back to rendering every native item, rather than a partial or empty menu, in each of these cases:
  - No installed plugin responds to the event.
  - The plugin raises while resolving the configuration.
  - The allow-list reaches Canvas containing an item it does not recognize — the whole list is discarded, not just the unrecognized entry.
Passing something that is not an `Items` member raises a validation error when you construct `ProviderMenuConfiguration`, so most mistakes surface in your plugin before they ever reach Canvas.
If more than one installed plugin responds with a `ProviderMenuConfiguration`, the last effect Canvas receives wins — its allow-list replaces the earlier ones rather than merging with them.
###  Methods 
####  apply() → Effect 
Sets the native items shown in the provider menu.
  - `items` is required; an empty list hides every native item.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`items`| `list[Items]`| List of menu items to display.| Yes  
Values in the `ProviderMenuConfiguration.Items` enum are:
Constant| Description  
---|---  
SCHEDULE| Go to the schedule page  
PATIENTS| Go to the patient directory  
REVENUE| Go to the revenue page  
POPULATIONS| Go to the populations page  
CAMPAIGNS| Go to the campaigns page  
DATA_INTEGRATION| Go to the data integration queue  
QUESTIONNAIRE_BUILDER| Go to the questionnaire builder  
SETTINGS| Open the Canvas admin site in a new tab  
MULTI_FACTOR_AUTHENTICATION| Open multi-factor authentication setup in a new tab  
CHANGELOG| Open the Canvas release notes in a new tab  
HELP_CENTER| Open the Canvas help center in a new tab  
GOOGLE_CALENDAR| Open the Google Calendar sync page in a new tab  
[Google Calendar sync](/product-updates/google-calendar-sync/) is a **beta** feature, so `GOOGLE_CALENDAR` renders only on instances where it is turned on.
###  Hiding the Schedule item 
Hiding `SCHEDULE` does not change where providers land after logging in — that still defaults to the schedule page. Pair the effect with a [`DefaultHomepageEffect`](/sdk/default-homepage-effect/) so providers do not arrive on a page they can no longer navigate back to.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.default_homepage import DefaultHomepageEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class ScheduleFreeHomepage(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.GET_HOMEPAGE_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [DefaultHomepageEffect(page=DefaultHomepageEffect.Pages.PATIENTS).apply()]
    ```
Hiding `SCHEDULE` also leaves the Appointments filter in the side panel in place. Removing the scheduling experience end to end means coordinating three independent controls: this effect for the menu item, `PanelConfiguration` for the Appointments filter, and [`DefaultHomepageEffect`](/sdk/default-homepage-effect/) for the landing page.
Omitting `SETTINGS` or `MULTI_FACTOR_AUTHENTICATION` hides the links to the admin site and to multi-factor authentication setup, so make sure your users have another route to them if they need one.
##  Modals 
The `LaunchModalEffect` class allows you to launch modals in Canvas, providing a flexible way to display content or navigate to external resources.
###  Methods 
####  apply() → Effect 
Launches the modal for the user whose action triggered the handler. See Where Modals Open.
  - Set at most one of `url` or `content`; setting both raises an error.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`url`| `str`| The URL to load within the modal.| No  
`content`| `str`| Content to display directly within the modal.| No  
`target`| `TargetType`| Where the modal is launched; see targets. Defaults to `DEFAULT_MODAL`.| No  
`dismissible`| `bool`| Whether the user can close a `DEFAULT_MODAL` themselves. Defaults to `True`. Set it to `False` for a blocking modal that only your application can close.| No  
`title`| `str`| The title of the modal, displayed when minimized. Defaults to `Untitled`.| No  
####  Targets 
`LaunchModalEffect.TargetType` values:
  - `DEFAULT_MODAL`: Opens the URL in a modal centered on the screen.
  - `NEW_WINDOW`: Opens the content in a new browser window.
  - `RIGHT_CHART_PANE`: Opens the URL in the right-hand pane of the patient chart.
  - `RIGHT_CHART_PANE_LARGE`: Like above, but a bit wider. A right chart pane opened in a patient's chart stays open while the user moves around that chart. This includes the chart, Profile, Documents, application tabs, and diagnostics. The content inside the pane isn't reloaded, so it keeps its state. The pane closes when the user opens a different patient or leaves the chart.
  - `PAGE`: Opens the content as a full page.
  - `NOTE`: Opens the content within a note tab (used with Note Applications).
  - `DOCKED_PANE`: Opens the content in a persistent pane pinned to an edge of the window. This target is returned by a [Docked Application](/sdk/handlers-embedded-applications/#docked-applications), which sets `DOCK_EDGE` and `DOCK_SIZE`.
###  Example 
    ```python
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    class ModalEffectHandler:
        def compute(self):
            modal_effect = LaunchModalEffect(
                url="https://example.com/info",
                content=None,
                target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
                title="Example Info"
            )
            return [modal_effect.apply()]
    ```
###  Where Modals Open 
A modal opens for the user whose action triggered the handler, in the app they're using: Canvas or the patient portal.
An application's `on_open`, an action button click, and the [`PATIENT_PORTAL__POST_LOGIN`](/sdk/patient-portal/#show-a-modal-after-login) event return the modal in their own response, so it opens right away. Canvas pushes a modal from any other handler, such as a [SimpleAPI](/sdk/handlers-simple-api-http/) route, to that user's browser. The modal opens only if the user has Canvas or the portal open at that moment. If the event has no acting user, the modal doesn't open.
In the patient portal, use the `DEFAULT_MODAL` target. The exception is a portal application's `on_open`. It can return the `PAGE` target to show content as the application's page, as in the [patient portal application example](/sdk/example-portal-customization-launch_application/). The portal ignores a pushed modal with the `PAGE` target.
###  Closing Modals from Applications 
When building applications with the Canvas SDK, you may encounter scenarios where you need to programmatically dismiss modals. This can be particularly useful in automated testing or when creating user flows that require closing modals based on certain conditions.
Here's a simple example of how to dismiss modals from your applications using JavaScript.
    ```html
    <script>
        let messagePort = null;
        // Listen for the port transfer from the Canvas Application
        window.addEventListener('message', (event) => {
          // Check if this is the INIT_CHANNEL message with a port
          if (event.data?.type === 'INIT_CHANNEL' && event.ports[0]) {
            // Store the port for later use
            messagePort = event.ports[0];
            messagePort.start();
            messagePort.postMessage({ type: 'CLOSE_MODAL' });
          }
        });
    </script>
    ```
And that's it! This script establishes a communication channel with the Canvas Application by listening for the `INIT_CHANNEL` event, capturing the message port, and then sending a `CLOSE_MODAL` message through that port to close any open modals when the application loads. You can customize the event listener to trigger the modal dismissal based on your specific requirements.
While developers might find odd to be sending a message to themselves, this is the current method supported by the Canvas SDK for dismissing modals, in order to avoid potential security issues with cross-origin messaging and flooding the main application with messages.
This twist on the _Holywood Principle_ ensures that your application remains secure while still providing the functionality needed to manage modals effectively.
###  Blocking Modals 
Use a blocking modal when the user has to finish a step before moving on, such as signing a consent form. Set `dismissible=False`:
    ```python
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    modal_effect = LaunchModalEffect(
        url="https://example.com/consent",
        target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
        title="Consent",
        dismissible=False,
    )
    ```
A blocking modal stays open when the user:
  - Presses Escape or selects the backdrop.
  - Navigates to another page or selects the browser's Back button.
On small screens, a blocking modal doesn't show the back arrow. Signing out of Canvas or the patient portal closes it.
> **Warning:** Only the modal's own frame can close a blocking modal. It closes when the frame posts `CLOSE_MODAL`, as shown in Closing Modals from Applications. If your application never posts `CLOSE_MODAL`, the user can't close the modal.
##  Resizing Modals 
Modal overlays can now be dynamically resized by embedded applications using the MessageChannel API. Applications launching with a `DEFAULT_MODAL` target can send a `RESIZE` message to adjust the modal's width and/or height:
    ```html
    <script>
        let messagePort = null;
        // Listen for the port transfer from the Canvas Application
        window.addEventListener('message', (event) => {
          // Check if this is the INIT_CHANNEL message with a port
          if (event.data?.type === 'INIT_CHANNEL' && event.ports?.[0]) {
            // Store the port for later use
            messagePort = event.ports[0];
            messagePort.start();
            // Example: Resize modal to specific dimensions
            messagePort.postMessage({
              type: 'RESIZE',
              width: 800,  // pixels
              height: 600  // pixels
            });
          }
        });
    </script>
    ```
This enables embedded applications to optimize their display area based on content requirements, improving the user experience for dynamic or responsive plugin interfaces.
##  Custom HTML and Django Templates 
Every `LaunchModalEffect` target, from a modal or side pane to a full page, and every application that opens one, renders its content in one of two ways: load a page in an iframe by setting the effect's `url` (see [Implementing an Application](/sdk/handlers-applications/#implementing-an-application)), or pass HTML in `content`, for example rendered from a Django template with `render_to_string`. Either can be a single-page application such as React: serve the page from your plugin and point `url` at it, or include the app's scripts in the HTML you pass as `content`.
To facilitate the use of custom HTML, you can utilize the `render_to_string` utility from `canvas_sdk.templates` to render Django templates with a specified context. This allows for dynamic rendering of HTML that can be passed to a `LaunchModalEffect` or `PortalWidget`.
    ```python
    from typing import Any
    def render_to_string(template_name: str, context: dict[str, Any] | None = None) -> str | None:
        """Load a template and render it with the given context.
        Args:
            template_name (str): The path to the template file, relative to the plugin package.
                If the path starts with a forward slash ("/"), it will be stripped during resolution.
            context (dict[str, Any] | None): A dictionary of variables to pass to the template
                for rendering. Defaults to None, which uses an empty context.
        Returns:
            str: The rendered template as a string.
        Raises:
            FileNotFoundError: If the template file does not exist within the plugin's directory
                or if the resolved path is invalid.
        """
    ```
####  Example Template 
Consider a simple HTML file named `templates/custom_content.html`:
    ```html
    <!DOCTYPE html>
    <html>
      <head>
        <title>{{ title }}</title>
      </head>
      <body>
        <h1>{{ heading }}</h1>
        <p>{{ message }}</p>
      </body>
    </html>
    ```
This template uses Django template placeholders like `{{ title }}`, `{{ heading }}`, and `{{ message }}` to dynamically render content based on the provided context.
Django escapes context values by default, so HTML in a value renders as literal text. If a value holds HTML from a patient or an integration, such as message content, use the builtin `|sanitize_html` filter instead of `|safe`. The filter keeps basic formatting and links and removes scripts, event handlers, and other unsafe markup. For the full list of what it keeps, see [Sanitizing untrusted HTML](/sdk/utils/#sanitizing-untrusted-html).
    ```html
    <p>{{ message|sanitize_html }}</p>
    ```
####  Rendering the Template in Python 
Here's how you can use the `render_to_string` utility to render the template and pass the resulting HTML to a `LaunchModalEffect` or `PortalWidget`:
    ```python
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.effects.widgets import PortalWidget
    from canvas_sdk.templates import render_to_string
    class ModalEffectHandler:
        def compute(self):
            # Define the context for the template
            context = {
                "title": "Welcome Modal",
                "heading": "Hello, User!",
                "message": "This is a dynamically rendered modal using Django templates."
            }
            # Render the HTML content using the template and context
            rendered_html = render_to_string("templates/custom_content.html", context)
            # Create a LaunchModalEffect with the rendered content
            modal_effect = LaunchModalEffect(
                content=rendered_html,
                target=LaunchModalEffect.TargetType.DEFAULT_MODAL
            )
            return [modal_effect.apply()]
    class PortalWidgetHandler:
        def compute(self):
            # Define the context for the template
            context = {
                "title": "Welcome Modal",
                "heading": "Hello, User!",
                "message": "This is a dynamically rendered modal using Django templates."
            }
            # Render the HTML content using the template and context
            rendered_html = render_to_string("templates/custom_content.html", context)
            # Create a PortalWidget with the rendered content
            portal_widget = PortalWidget(
                content=rendered_html,
                size=PortalWidget.Size.COMPACT,
                priority=25
            )
            return [portal_widget.apply()]
    ```
####  Rendering untrusted data safely 
`render_to_string` escapes every `{{ value }}` by default. That escaping is what stops text from a patient, an integration, or an external API from running as script in the browser of the staff member who opens your page.
  - Never use `|safe`, `{% autoescape off %}`, or `mark_safe` on data from patients, integrations, notes, messages, questionnaires, FHIR API input, or any external API.
  - For HTML that has to keep its formatting, such as a message body, use the `sanitize_html` filter: `{{ message.content|sanitize_html }}`. It keeps a small set of formatting tags and removes everything else. The same function is available in Python as [`sanitize_html`](/sdk/utils/#sanitizing-untrusted-html).
  - To pass data to JavaScript, use Django's `json_script` filter instead of printing JSON into a `<script>` block. `json.dumps` does not escape `</script>`, so a value containing it closes your script tag and whatever follows runs as HTML.
  - Never put [secrets](/sdk/secrets/) in template context or in any HTML or JavaScript response: anything sent to the browser can be read there. Call the external API server-side from a [SimpleAPI route](/sdk/handlers-simple-api-http/) and have your page call that route.
Instead of this, which breaks out of the script tag when any value contains `</script>`:
    ```html
    <script>
      const vitals = {{ vitals_json|safe }};
    </script>
    ```
pass the Python object itself (not a `json.dumps` string) in the context and let `json_script` serialize it:
    ```html
    {{ vitals|json_script:"vitals-data" }}
    <script>
      const vitals = JSON.parse(document.getElementById("vitals-data").textContent);
    </script>
    ```
##  Additional Configuration 
To use URLs or custom scripts within the `LaunchModalEffect` or `PortalWidget`, additional security configurations must be specified in the [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#url-permissions) file of your plugin.
  - **Allowing URLs** : URLs specified in the **url** property must be added to the [`url_permissions`](/sdk/canvas_manifest/#url-permissions) section of the `CANVAS_MANIFEST.json` in order for the URL to load properly.
  - **Allowing custom scripts** : If you need to load scripts from an external source, the URL for the script must be added to the `url_permissions` section of the `CANVAS_MANIFEST.json` and `'SCRIPTS'` must be in the permissions list.
  - **Requesting microphone access** : If the site in your modal or widget needs microphone access, `'MICROPHONE'` must be in the URL's permissions list.
  - **Requesting camera access** : If the site in your modal or widget needs camera access, `'CAMERA'` must be in the URL's permissions list.
  - **Requesting clipboard read access** : If the site in your modal or widget needs to read from the user's clipboard, `'CLIPBOARD_READ'` must be in the URL's permissions list.
  - **Requesting clipboard write access** : If the site in your modal or widget needs to write to the user's clipboard, `'CLIPBOARD_WRITE'` must be in the URL's permissions list.
  - **Allowing browser access to cookies from the iframe's origin** : If you want the loaded URL to access cookies for its domain, `'ALLOW_SAME_ORIGIN'` must be in the URL's permissions list. If the URL you're loading requires authentication, this will prevent your user from having to log in each time the modal is launched.
The URLs must match the format available [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#host-source).
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "0.0.1",
      "name": "custom_html",
      "description": "...",
      "url_permissions": [
        {
          "url": "https://example.com/info",
          "permissions": ["ALLOW_SAME_ORIGIN", "MICROPHONE", "CAMERA", "CLIPBOARD_READ", "CLIPBOARD_WRITE"]
        },
        {
          "url": "https://d3js.org/d3.v4.js",
          "permissions": ["SCRIPTS"]
        }
      ]
    }
    ```
###  The iframe sandbox and `ALLOW_SAME_ORIGIN`
Whether an application's iframe gets a `sandbox` attribute depends on the `url_permissions` entry its URL matches:
  - **With`ALLOW_SAME_ORIGIN`**, the iframe is sandboxed as `allow-same-origin allow-forms allow-popups allow-scripts`. Popups work, so `window.open(url, '_blank')` and popup-based sign-in flows are fine. Navigating the top window from inside the iframe is blocked.
  - **Without a matching entry that grants it** , the iframe has no `sandbox` attribute, and top-window navigation works.
URLs match by case-insensitive prefix, and every character counts, including the scheme, port, and trailing slash. An entry of `https://example.com/` does not match a page at `https://example.com`. If top-window navigation works in one environment but not another, the URLs are matching `url_permissions` differently. To navigate away while keeping `ALLOW_SAME_ORIGIN`, open the page with `window.open(url, '_blank')`, or remove `ALLOW_SAME_ORIGIN` if your application doesn't need it.

---

# Patient Chart Group

Source: https://docs.canvasmedical.com/sdk/patient-chart-group-effect/

This effect allows developers to group items in a patient chart section. You can define multiple groups with a name, priority, and the items that belong to each group.
This is supported for the Conditions, Medications, and Detected Issues sections.
Build a `PatientChartGroup` with the groups to show, then return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Groups the section's items.
  - `items` is required.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`items`| `dict[str, ``Group``]`| The groups, keyed by group name.| Yes  
##  Group 
Attribute| Type| Description  
---|---|---  
`items`| `list`| List of items for each group, for example conditions or medications.  
`priority`| `int`| The group's priority within the section.  
`name`| `str`| The group label.  
All three are required.
##  Example 
    ```python
    from canvas_sdk.effects.patient_chart_group import PatientChartGroup
    from canvas_sdk.effects.group import Group
    conditions = [{
        "id": 1,
        "codings": {
          "code": "111",
          "system": "ICD-10",
          "display": "Ophiasis",
        }
      }, {
        "id": 2,
        "codings": {
          "code": "112",
          "system": "ICD-10",
          "display": "Acute angle-closure glaucoma",
        }
    }]
    PatientChartGroup(items={
        "Psychiatry": Group(priority=100, items=conditions, name="Psychiatry"),
        "General": Group(priority=200, items=conditions, name="General"),
    }).apply()
    ```

---

# Patient Chart Summary Custom Section

Source: https://docs.canvasmedical.com/sdk/patient-chart-summary-custom-section-effect/

The `PatientChartSummaryCustomSection` effect allows plugin developers to supply the content for a custom section in the patient chart summary. It is returned by a [`PatientChartSummaryCustomSectionHandler`](/sdk/patient-chart-summary-custom-section-handler/) in response to a request for the section's content.
Content can be provided as an inline HTML string or as a URL to a hosted page. An icon must always be supplied; it is shown in the chart summary header when the section is collapsed.
Build a `PatientChartSummaryCustomSection` with the attributes you want to set, then return its `apply()` from your handler.
##  Methods 
###  apply() → Effect 
Supplies the section's content.
  - Exactly one of `content` or `url` is required.
  - Exactly one of `icon` or `icon_url` is required.
Providing both fields in a pair, or neither, raises a `ValidationError`.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`content`| `str` | `None`| Inline HTML content to render in the section. Mutually exclusive with `url`.| Exactly one of `content` or `url`  
`url`| `str` | `None`| URL of the page to load in the section iframe. Mutually exclusive with `content`.| Exactly one of `content` or `url`  
`icon`| `str` | `None`| Text or emoji displayed as the section icon when collapsed. Mutually exclusive with `icon_url`.| Exactly one of `icon` or `icon_url`  
`icon_url`| `str` | `None`| URL of an image to use as the section icon when collapsed. Mutually exclusive with `icon`.| Exactly one of `icon` or `icon_url`  
##  Examples 
###  Inline HTML content 
Return a rendered HTML template as the section content.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_chart_summary_custom_section import PatientChartSummaryCustomSection
    from canvas_sdk.handlers.patient_chart_summary_custom_section_handler import PatientChartSummaryCustomSectionHandler
    from canvas_sdk.templates import render_to_string
    class MySectionHandler(PatientChartSummaryCustomSectionHandler):
        SECTION_KEY = "my_section"
        def handle(self) -> list[Effect]:
            return [
                PatientChartSummaryCustomSection(
                    content=render_to_string("templates/my_section.html"),
                    icon="📋",
                ).apply()
            ]
    ```
###  URL-based content 
Load the section content from a hosted endpoint. This is useful when the section is a standalone page served by a [Simple API](/sdk/handlers-simple-api/) handler.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_chart_summary_custom_section import PatientChartSummaryCustomSection
    from canvas_sdk.handlers.patient_chart_summary_custom_section_handler import PatientChartSummaryCustomSectionHandler
    class MySectionHandler(PatientChartSummaryCustomSectionHandler):
        SECTION_KEY = "my_section"
        def handle(self) -> list[Effect]:
            return [
                PatientChartSummaryCustomSection(
                    url="/plugin-io/api/my_plugin/my-section",
                    icon_url="/plugin-io/api/my_plugin/icon.png",
                ).apply()
            ]
    ```
###  Passing data to the template 
Use `render_to_string` with a context dictionary to inject dynamic data into the HTML template.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_chart_summary_custom_section import PatientChartSummaryCustomSection
    from canvas_sdk.handlers.patient_chart_summary_custom_section_handler import PatientChartSummaryCustomSectionHandler
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data.patient import Patient
    class MySectionHandler(PatientChartSummaryCustomSectionHandler):
        SECTION_KEY = "my_section"
        def handle(self) -> list[Effect]:
            patient = Patient.objects.get(id=self.target)
            return [
                PatientChartSummaryCustomSection(
                    content=render_to_string(
                        "templates/my_section.html",
                        {"patient_name": patient.first_name},
                    ),
                    icon="📋",
                ).apply()
            ]
    ```

---

# Patient Chart Summary Custom Section Handler

Source: https://docs.canvasmedical.com/sdk/patient-chart-summary-custom-section-handler/

The `PatientChartSummaryCustomSectionHandler` is the base class for implementing custom sections in the patient chart summary. When Canvas needs to render a custom section, it fires an event that this handler intercepts, and the handler returns a [`PatientChartSummaryCustomSection`](/sdk/patient-chart-summary-custom-section-effect/) effect with the content to display.
##  Overview 
Custom chart summary sections are registered through [`PatientChartSummaryConfiguration`](/sdk/layout-effect/#patient-summary) and served by a `PatientChartSummaryCustomSectionHandler` subclass. Each handler is responsible for exactly one section, identified by its `SECTION_KEY`.
To implement a custom section you need two things:
  1. A `PatientChartSummaryConfiguration` handler that includes the section in the layout.
  2. A `PatientChartSummaryCustomSectionHandler` subclass that returns the section content.
Both handlers must be registered in [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#handlers).
##  Creating a Custom Section Handler 
Subclass `PatientChartSummaryCustomSectionHandler` and:
  1. Set `SECTION_KEY` to the unique identifier of your section. This must match the key used in `PatientChartSummaryConfiguration.CustomSection`.
  2. Implement `handle()` to return a `PatientChartSummaryCustomSection` effect.
  3. The patient id is available via `self.target`. Use it to scope database queries to the current patient.
  4. The logged-in user is available via `self.actor`. Use it to tailor the section content to the specific staff member viewing the chart.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_chart_summary_custom_section import PatientChartSummaryCustomSection
    from canvas_sdk.handlers.patient_chart_summary_custom_section_handler import PatientChartSummaryCustomSectionHandler
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data.patient import Patient
    class MySectionHandler(PatientChartSummaryCustomSectionHandler):
        """Handles the PATIENT_CHART_SUMMARY__GET_CUSTOM_SECTION event for 'my_section'.
        Fetches the current patient and renders a template with their name.
        """
        SECTION_KEY = "my_section"
        def handle(self) -> list[Effect]:
            patient = Patient.objects.get(id=self.target)
            return [
                PatientChartSummaryCustomSection(
                    content=render_to_string("templates/my_section.html", { "patient_name": patient.full_name() }),
                    icon="📋",
                ).apply()
            ]
    ```
###  Required 
  - **`SECTION_KEY`** A unique string identifier for the section. Must match the key passed to `PatientChartSummaryConfiguration.CustomSection`. Omitting or leaving it empty will raise an `ImproperlyConfigured` error when the plugin loads.
  - **`handle()`** Called when Canvas requests the content for this section. Must return a list containing a single [`PatientChartSummaryCustomSection`](/sdk/patient-chart-summary-custom-section-effect/) effect.
##  Configuring Chart Summary Sections 
A custom section handler alone is not enough — the section must also be included in the chart summary layout. Use `PatientChartSummaryConfiguration` to declare which sections appear in the chart summary and in what order. For the full list of available built-in sections, see [Patient Summary layout effects](/sdk/layout-effect/#patient-summary).
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_chart_summary_configuration import PatientChartSummaryConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MySummaryConfiguration(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION)]
        def compute(self) -> list[Effect]:
            return [
                PatientChartSummaryConfiguration(
                    sections=[
                        PatientChartSummaryConfiguration.CustomSection(name="my_section"),
                        PatientChartSummaryConfiguration.Section.MEDICATIONS,
                        PatientChartSummaryConfiguration.Section.CONDITIONS,
                    ]
                ).apply()
            ]
    ```
##  Full Example 
The following example shows a complete plugin with a custom section that displays a list of items fetched from command metadata.
###  `handlers/my_section.py`
    ```python
    import json
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_chart_summary_custom_section import PatientChartSummaryCustomSection
    from canvas_sdk.effects.patient_chart_summary_configuration import PatientChartSummaryConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.handlers.patient_chart_summary_custom_section_handler import PatientChartSummaryCustomSectionHandler
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data.command import CommandMetadata
    class MySectionHandler(PatientChartSummaryCustomSectionHandler):
        """Handles the PATIENT_CHART_SUMMARY__GET_CUSTOM_SECTION event for 'my_section'.
        Fetches all 'my_section' command metadata entries for the current patient
        and renders them as a list in the section template.
        """
        SECTION_KEY = "my_section"
        def handle(self) -> list[Effect]:
            entries = (
                CommandMetadata.objects.filter(
                    key="my_section",
                    command__patient__id=self.target,
                )
                .order_by("created")
            )
            items = []
            for entry in entries:
                try:
                    items.append(json.loads(entry.value))
                except (json.JSONDecodeError, TypeError):
                    items.append({"title": entry.value})
            return [
                PatientChartSummaryCustomSection(
                    content=render_to_string("templates/my_section.html", {"items": items}),
                    icon="📋",
                ).apply()
            ]
    class MySummaryConfiguration(BaseHandler):
        RESPONDS_TO = [EventType.Name(EventType.PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION)]
        def compute(self) -> list[Effect]:
            return [
                PatientChartSummaryConfiguration(
                    sections=[
                        PatientChartSummaryConfiguration.CustomSection(name="my_section"),
                        PatientChartSummaryConfiguration.Section.MEDICATIONS,
                        PatientChartSummaryConfiguration.Section.CONDITIONS,
                    ]
                ).apply()
            ]
    ```
###  `templates/my_section.html`
    ```html
    <ul>
      {% for item in items %}
        <li>{{ item.title }}</li>
      {% empty %}
        <li>No items on record.</li>
      {% endfor %}
    </ul>
    ```
###  `CANVAS_MANIFEST.json`
    ```json
    {
      "components": {
        "handlers": [
          {
            "class": "my_plugin.handlers.my_section:MySectionHandler",
            "description": "Serves content for the My Section custom chart section"
          },
          {
            "class": "my_plugin.handlers.my_section:MySummaryConfiguration",
            "description": "Configures the chart summary layout to include My Section"
          }
        ]
      }
    }
    ```

---

# Patient Metadata Create form

Source: https://docs.canvasmedical.com/sdk/patient-metadata-create-form-effect/

This allows developers to dynamically display additional fields in the patient profile. For more guidance, see the ["How to add additional profile fields" guide](/guides/profile-additional-fields/).
Build a `PatientMetadataCreateFormEffect` with the form fields to show, then return its `apply()` from a `PATIENT_METADATA__GET_ADDITIONAL_FIELDS` handler.
##  Methods 
###  apply() → Effect 
Displays the form fields in the patient profile.
  - `form_fields` is required.
  - `options` may only be set on fields whose `type` is `InputType.SELECT`.
##  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`form_fields`| `list[``FormField``]`| List of fields.| Yes  
##  FormField 
Attribute| Type| Description  
---|---|---  
`key`| `str`| Unique identifier of the field; the patient metadata key.  
`label`| `str`| The label displayed on the field.  
`type`| `InputType`| The type of the input: `TEXT`, `SELECT`, or `DATE`. Defaults to `TEXT`.  
`required`| `bool`| Whether the input is required. Defaults to `False`.  
`editable`| `bool`| Whether the input can be edited. Defaults to `True`.  
`options`| `list[str]`| Possible options when the input type is `SELECT`. Only allowed on `SELECT` fields.  
##  Example 
    ```python
    from canvas_sdk.effects.patient_metadata import PatientMetadataCreateFormEffect, InputType, FormField
    PatientMetadataCreateFormEffect(form_fields=[
        FormField(
            key='status',
            label='Status',
            type=InputType.SELECT,
            required=False,
            editable=True,
            options=["open", "close"]
        ),
    ]).apply()
    ```

---

# Patient Portal

Source: https://docs.canvasmedical.com/sdk/patient-portal/

The Canvas SDK allows you to configure and extend the patient portal. This page is the technical reference for the portal's effects and events. For a decision-oriented overview of how much of the patient experience to build, see [Choosing Your Patient Experience](/guides/choosing-your-patient-experience/).
##  Configure Portal Menu Items 
Decide which items appear in the patient portal's menu with the `PatientPortalMenuConfiguration` effect, returned from a handler on the `PATIENT_PORTAL__MENU_CONFIGURATION` event. Unlike the account-wide page toggles managed by Canvas Support, this lets you show or hide menu items with your own logic (per patient, program, and so on).
The list you return **replaces** the built-in menu — include every built-in item you want shown, in the order you want them to appear (**the list order is the navigation order**), and omit any you want hidden.
An item only appears if its page is **also enabled in your portal settings** (the `PATIENT_APP_*` settings managed by Canvas Support — see [Managing the Patient Portal](https://canvas-medical.help.usepylon.com/articles/7348270931-managing-the-patient-portal)). This effect selects and orders among the _enabled_ pages: it can hide or reorder them, but it can't surface a page that's turned off. Patient-portal [applications](/sdk/handlers-applications/) aren't part of this list — they're appended to the navigation after the built-in items through their own registration.
###  Methods 
####  apply() → Effect 
Sets the portal menu for the patient.
  - `items` is required, with at least one item.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`items`| list[`MenuItems`]| The built-in menu items to show, in navigation order (at least one). Replaces the default set — omit an item to hide it.| Yes  
###  MenuItems 
Member| Value| Menu item  
---|---|---  
`APPOINTMENTS`| `"appointments"`| Appointments  
`MESSAGING`| `"messaging"`| Messaging  
`MY_HEALTH`| `"my_health"`| My Health  
`PAYMENTS`| `"payments"`| Payments  
`LABS`| `"labs"`| Lab results  
`CONTACT`| `"contact"`| Contact  
`RECORDS`| `"records"`| Health Records  
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_portal_menu_configuration import PatientPortalMenuConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__MENU_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [
                PatientPortalMenuConfiguration(
                    items=[
                        PatientPortalMenuConfiguration.MenuItems.APPOINTMENTS,
                        PatientPortalMenuConfiguration.MenuItems.MESSAGING,
                    ]
                ).apply()
            ]
    ```
##  Portal Landing Page Widgets 
The `PortalWidget` class adds widgets to the patient portal landing page. Return `PortalWidget` effects from a handler on the `PATIENT_PORTAL__WIDGET_CONFIGURATION` event. You can fully customize a widget or use a ready-made one provided by Canvas (Appointments, Messaging).
###  Methods 
####  apply() → Effect 
Adds the widget to the landing page.
  - Exactly one of `url`, `content`, or `component` is required; more than one, or none, raises an error.
  - A `component` widget supports only the `EXPANDED` size.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`url`| `str`| A URL to load within the widget.| Exactly one of `url`, `content`, or `component`  
`content`| `str`| Content to display directly within the widget.| Exactly one of `url`, `content`, or `component`  
`component`| `Component`| A ready-made Canvas widget: `APPOINTMENTS` (upcoming appointments) or `MESSAGING` (quick messaging).| Exactly one of `url`, `content`, or `component`  
`size`| `Size`| Widget width on the grid: `EXPANDED` (12 columns), `MEDIUM` (8 columns), or `COMPACT` (4 columns). All are 300px tall. Defaults to `EXPANDED`.| No  
`priority`| `int`| Orders widgets within the portal; a lower number is higher priority. Defaults to `100`.| No  
###  Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.widgets import PortalWidget
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__WIDGET_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [
                PortalWidget(
                    url="https://example.com/info",
                    size=PortalWidget.Size.COMPACT,
                    priority=25,
                ).apply()
            ]
    ```
For a full walkthrough with examples, see the [Custom Landing Page guide](/guides/custom-landing-page/). Example plugins: [patient_portal_plugin](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/patient_portal_plugin), and the MSF [urgent-care-self-scheduler](https://github.com/medical-software-foundation/canvas/tree/main/extensions/urgent-care-self-scheduler) (a "Need to be seen today?" widget).
##  Customize Appointment Cards 
Customize your patient appointment cards so patients can easily join their telehealth appointments, cancel or reschedule appointments. Each appointment can be customized individually, allowing each one to have its own unique settings.
Each action is decided per appointment: Canvas fires a `PATIENT_PORTAL__APPOINTMENT_CAN_*` event for the appointment, and your handler returns the matching `PATIENT_PORTAL__APPOINTMENT_IS_*` (or `PATIENT_PORTAL__APPOINTMENT_SHOW_MEETING_LINK`) effect with a `{"result": <bool>}` payload — `False` hides the action; for the telehealth **Join** link, `True` shows it. Each action's exact event, effect, and payload are shown below.
The Cancel and Reschedule answers also decide what Canvas accepts, not only which buttons the portal shows. When a patient cancels or reschedules, Canvas checks the appointment again and refuses the request if the button wouldn't be offered.
  - With no plugin answer, a patient can cancel or reschedule an appointment until one day before it starts.
  - A plugin's `result` replaces that one-day rule. `True` lets the patient act within the final day, and `False` refuses the action at any time.
  - Some appointments never offer either action, and Canvas doesn't fire the event for them. These are appointments that are canceled, marked as a no-show, or checked in, and appointments whose note is signed, locked, or deleted. A patient also can't cancel an appointment that has already started.
MSF example: [portal_disable_cancel_appts](https://github.com/medical-software-foundation/canvas/tree/main/extensions/portal_disable_cancel_appts) hides the Cancel action.
###  Hide 'Cancel' button 
Respond to `PATIENT_PORTAL__APPOINTMENT_CAN_BE_CANCELED` and return a `PATIENT_PORTAL__APPOINTMENT_IS_CANCELABLE` effect with `{"result": False}` to hide the Cancel button.
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__APPOINTMENT_CAN_BE_CANCELED)
        def compute(self) -> list[Effect]:
            return [
              Effect(
                type=EffectType.PATIENT_PORTAL__APPOINTMENT_IS_CANCELABLE,
                payload=json.dumps({"result": False}))
            ]
    ```
###  Hide 'Reschedule' button 
Respond to `PATIENT_PORTAL__APPOINTMENT_CAN_BE_RESCHEDULED` and return a `PATIENT_PORTAL__APPOINTMENT_IS_RESCHEDULABLE` effect with `{"result": False}` to hide the Reschedule button.
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__APPOINTMENT_CAN_BE_RESCHEDULED)
        def compute(self) -> list[Effect]:
            return [
              Effect(
                type=EffectType.PATIENT_PORTAL__APPOINTMENT_IS_RESCHEDULABLE,
                payload=json.dumps({"result": False}))
            ]
    ```
###  Hide 'Join' button 
This button shows on telehealth appointments. Respond to `PATIENT_PORTAL__APPOINTMENT_CAN_SHOW_MEETING_LINK` and return a `PATIENT_PORTAL__APPOINTMENT_SHOW_MEETING_LINK` effect with `{"result": True}` to show the join link.
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__APPOINTMENT_CAN_SHOW_MEETING_LINK)
        def compute(self) -> list[Effect]:
            return [
              Effect(
                type=EffectType.PATIENT_PORTAL__APPOINTMENT_SHOW_MEETING_LINK,
                payload=json.dumps({"result": True}))
            ]
    ```
##  Configuring the Patient Portal 
Return a `PatientPortalApplicationConfiguration` effect from a handler on the `PATIENT_PORTAL__GET_APPLICATION_CONFIGURATION` event to set application-level portal options:
  - **Self-scheduling:** show or hide the self-scheduling entry points. Pair this with Shape Self-Scheduling to control _what_ patients can book.
  - **Default homepage:** open one of your plugin's portal applications, instead of the widgets landing page, when a patient lands on the portal home page.
###  Methods 
####  apply() → Effect 
Applies the portal options. Every attribute is optional; set only the options you want to change.
  - If `default_homepage_application_identifier` is set, it must match an installed application, or the effect raises a validation error.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`can_schedule_appointments`| `bool`| If the patient is allowed to book or reschedule appointments. When omitted, patients can self-schedule if at least one note type is schedulable through the patient portal.| No  
`default_homepage_application_identifier`| `str`| The application to open as the patient's portal homepage. Use the application's `class` string from [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#applications), the `<module path>:<ClassName>` value. When omitted, patients see the widgets landing page.| No  
The portal opens the default homepage application only when that application uses the `portal_menu_item` [scope](/sdk/handlers-applications/#application-scopes) and its plugin is enabled. Otherwise, patients see the widgets landing page.
While a default homepage application is set, every visit to the portal home page opens it, including the header logo link, so patients don't see landing page widgets. Portal consents, forms, and modals from `PATIENT_PORTAL__POST_LOGIN` handlers still appear on top of the application. A sign-in link that names another portal page, such as messages, opens that page instead.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_portal.application_configuration import PatientPortalApplicationConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class MyHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__GET_APPLICATION_CONFIGURATION)
        def compute(self) -> list[Effect]:
            return [
              PatientPortalApplicationConfiguration(
                can_schedule_appointments=True,
                default_homepage_application_identifier="my_plugin.apps.care_dashboard:CareDashboardApp",
              ).apply()
            ]
    ```
##  Shape Self-Scheduling 
When patients self-schedule, you can filter or reorder what they're offered _before they see it_ — the open time slots, and the appointment-type, location, and provider options on the scheduling form. Each search step fires a `…PRE_SEARCH` event (before Canvas runs the search) and a `…POST_SEARCH` event (with the results). Respond to the `POST_SEARCH` event and return an effect **of the same name with a`_RESULTS` suffix**, carrying the results you want the patient to see. (A `…PRE_SEARCH` event is available for each step too, if you need to act before the search runs.)
Canvas applies the same appointment-type, location, and provider filters when a patient books or reschedules. It runs your handlers again for that patient and refuses the request unless each selected option is in the lists they return. A booking or new time also needs:
  - Self-scheduling turned on for the patient. See `can_schedule_appointments` in Configuring the Patient Portal.
  - A start time in the future.
  - A duration no longer than the appointment type's patient portal duration (the [NoteType](/sdk/data-note/#notetype) `online_duration`).
Two example plugins put these together: [patient_portal_search_appointments_slots_plugin](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/patient_portal_search_appointments_slots_plugin) (slots) and [patient_app_schedule](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/patient_app_schedule) (appointment types, locations, and providers).
###  Filter available slots 
Respond to `PATIENT_PORTAL__APPOINTMENTS__SLOTS__POST_SEARCH` and return `PATIENT_PORTAL__APPOINTMENTS__SLOTS__POST_SEARCH_RESULTS`.
**Target:** `self.target` is the [Patient](/sdk/data-patient/#patient) id.
**Context:** `self.context["slots_by_provider"]` — a JSON string of `{provider: {date: [{"start", "end"}, ...]}}`, keyed by [Staff](/sdk/data-staff/#staff) id, where each `start`/`end` is an ISO-8601 datetime.
Example — enforce a 48-hour minimum lead time so patients can't self-book last minute:
    ```python
    import json
    import arrow
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    # Patients must book at least this far ahead — no last-minute self-scheduling
    MIN_LEAD_TIME_HOURS = 48
    class SlotFilter(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__APPOINTMENTS__SLOTS__POST_SEARCH)
        def compute(self) -> list[Effect]:
            # slots_by_provider maps each provider to {date: [{"start": ..., "end": ...}, ...]}
            slots_by_provider = json.loads(self.context.get("slots_by_provider") or "{}")
            cutoff = arrow.now().shift(hours=MIN_LEAD_TIME_HOURS)
            filtered = {}
            for provider, dates in slots_by_provider.items():
                # drop any slot starting before the cutoff
                kept = {
                    date: [slot for slot in slots if arrow.get(slot["start"]) >= cutoff]
                    for date, slots in dates.items()
                }
                # then drop empty dates, and providers left with no slots
                kept = {date: slots for date, slots in kept.items() if slots}
                if kept:
                    filtered[provider] = kept
            return [
                Effect(
                    type=EffectType.PATIENT_PORTAL__APPOINTMENTS__SLOTS__POST_SEARCH_RESULTS,
                    payload=json.dumps({"slots_by_provider": filtered}),
                )
            ]
    ```
###  Filter appointment types 
Respond to `PATIENT_PORTAL__APPOINTMENTS__FORM_APPOINTMENT_TYPES__POST_SEARCH` and return `PATIENT_PORTAL__APPOINTMENTS__FORM_APPOINTMENT_TYPES__POST_SEARCH_RESULTS`.
**Target:** `self.target` is the [Patient](/sdk/data-patient/#patient) id.
**Context:** `self.context["appointment_types"]` — a list of `{"id", "title"}` entries, where `id` is a [NoteType](/sdk/data-note/#notetype) id (its `unique_identifier`) and `title` is the note type's name.
Example — only let patients self-book a specific set of visit types (e.g. keep follow-ups and telehealth, hide new-patient intakes):
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    # Visit types patients are allowed to self-book
    PATIENT_BOOKABLE_TYPES = {"Follow-up", "Telehealth visit"}
    class AppointmentTypeFilter(BaseHandler):
        RESPONDS_TO = EventType.Name(
            EventType.PATIENT_PORTAL__APPOINTMENTS__FORM_APPOINTMENT_TYPES__POST_SEARCH
        )
        def compute(self) -> list[Effect]:
            # each entry is {"id": ..., "title": ...}
            appointment_types = self.context.get("appointment_types", [])
            filtered = [t for t in appointment_types if t["title"] in PATIENT_BOOKABLE_TYPES]
            return [
                Effect(
                    type=EffectType.PATIENT_PORTAL__APPOINTMENTS__FORM_APPOINTMENT_TYPES__POST_SEARCH_RESULTS,
                    payload=json.dumps({"appointment_types": filtered}),
                )
            ]
    ```
###  Filter locations 
Respond to `PATIENT_PORTAL__APPOINTMENTS__FORM_LOCATIONS__POST_SEARCH` and return `PATIENT_PORTAL__APPOINTMENTS__FORM_LOCATIONS__POST_SEARCH_RESULTS`.
**Target:** `self.target` is the [Patient](/sdk/data-patient/#patient) id.
**Context:** `self.context["locations"]` — a list of `{"id", "title"}` entries, where `id` is a [PracticeLocation](/sdk/data-practicelocation/#practicelocation) id and `title` is its full name.
Example — only show locations where the patient has been seen before:
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Appointment
    class LocationFilter(BaseHandler):
        RESPONDS_TO = EventType.Name(
            EventType.PATIENT_PORTAL__APPOINTMENTS__FORM_LOCATIONS__POST_SEARCH
        )
        def compute(self) -> list[Effect]:
            locations = self.context.get("locations", [])
            seen_location_ids = {
                str(loc_id)
                for loc_id in Appointment.objects.filter(patient__id=self.target)
                .exclude(location__isnull=True)
                .values_list("location__id", flat=True)
            }
            filtered = [loc for loc in locations if loc["id"] in seen_location_ids]
            return [
                Effect(
                    type=EffectType.PATIENT_PORTAL__APPOINTMENTS__FORM_LOCATIONS__POST_SEARCH_RESULTS,
                    payload=json.dumps({"locations": filtered}),
                )
            ]
    ```
###  Filter providers 
Respond to `PATIENT_PORTAL__APPOINTMENTS__FORM_PROVIDERS__POST_SEARCH` and return `PATIENT_PORTAL__APPOINTMENTS__FORM_PROVIDERS__POST_SEARCH_RESULTS`.
**Target:** `self.target` is the [Patient](/sdk/data-patient/#patient) id.
**Context:** `self.context["providers"]` — a list of `{"id", "title"}` entries, where `id` is a [Staff](/sdk/data-staff/#staff) id and `title` is the provider's name and roles.
Example — only offer the patient's own care-team providers:
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import CareTeamMembership
    from canvas_sdk.v1.data.care_team import CareTeamMembershipStatus
    class ProviderFilter(BaseHandler):
        RESPONDS_TO = EventType.Name(
            EventType.PATIENT_PORTAL__APPOINTMENTS__FORM_PROVIDERS__POST_SEARCH
        )
        def compute(self) -> list[Effect]:
            providers = self.context.get("providers", [])
            care_team_ids = {
                str(staff_id)
                for staff_id in CareTeamMembership.objects.filter(
                    patient__id=self.target, status=CareTeamMembershipStatus.ACTIVE
                ).values_list("staff__id", flat=True)
            }
            filtered = [p for p in providers if p["id"] in care_team_ids]
            return [
                Effect(
                    type=EffectType.PATIENT_PORTAL__APPOINTMENTS__FORM_PROVIDERS__POST_SEARCH_RESULTS,
                    payload=json.dumps({"providers": filtered}),
                )
            ]
    ```
##  Show a Modal After Login 
Show a patient a consent form, a tour, or an alert as soon as they log in to the portal. Respond to the [`PATIENT_PORTAL__POST_LOGIN`](/sdk/events/#patient-portal-events) event and return a [`LaunchModalEffect`](/sdk/layout-effect/#modals) with the `DEFAULT_MODAL` target. The portal opens the modal over the page the patient lands on.
The event targets the patient. Its context carries `login_method`, which tells you how the patient logged in:
`login_method`| How the patient logged in  
---|---  
`"credentials"`| Entered their username and password on the login page, including after setting a password from a portal invite or password reset link  
`"access_token"`| Followed the sign-in link in a message, lab result, or statement notification  
`"registration"`| Completed self-registration  
The event fires once per login, in the browser tab where the patient logged in. Refreshing the page or returning to the portal with a remembered session doesn't fire it. When no handler responds, or the plugin runner fails, the patient lands in the portal with no modal.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class WelcomeModal(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__POST_LOGIN)
        def compute(self) -> list[Effect]:
            # Only greet patients who just registered
            if self.context.get("login_method") != "registration":
                return []
            return [
                LaunchModalEffect(
                    content="<h2>Welcome to the portal</h2><p>Here's how to get started.</p>",
                    target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
                    title="Welcome",
                ).apply()
            ]
    ```
> **Warning:** The portal's built-in consents dialog also opens after login for any [Patient Consent Coding](https://help.canvasmedical.com/articles/8144965836-Managing-Consents) marked **Show in patient portal** that the patient hasn't completed. If your plugin collects consent after login, clear **Show in patient portal** on those consent codings in Settings so the patient doesn't see both.
##  Link to After-Visit Summaries 
A patient can download the after-visit summary of their own locked notes from the portal at `/app/note/<note id>/aftervisitsummary`, where `<note id>` is the [note's](/sdk/data-note/) `id`. The portal has no built-in link to it, so share the link from a plugin, such as a widget or a [portal page](/sdk/handlers-applications/), or in a message.
  - The PDF is the same after-visit summary a clinician prints from the note.
  - Only the patient the note belongs to can open it, and only once the note is locked. Any other note id returns a 404 error.
  - Each download is recorded in the [audit log](/guides/audit-logging-and-telemetry/) against the patient, and fires an event your plugin can respond to.
##  Link to Lab and Imaging Requisitions 
A patient can download the requisition of their own lab and imaging orders from the portal. As with after-visit summaries, the portal has no built-in link, so share the link from a plugin or in a message. Each order type has its own URL and PDF:
Order| Portal URL| PDF the patient gets  
---|---|---  
Lab| `/app/laborder/<order id>/requisition`| The requisition a clinician prints from the order. For an order sent electronically through Health Gorilla, the patient gets Health Gorilla's requisition form, as staff do.  
Imaging| `/app/imagingorder/<order id>/requisition`| The "Prepare for your imaging test" letter staff print for the patient.  
`<order id>` is the `id` of the [LabOrder](/sdk/data-labs/#laborder) or [ImagingOrder](/sdk/data-imaging/#imagingorder).
  - Only the patient the order belongs to can open it, and only once the order is committed and not entered in error. Any other order id returns a 404 error.
  - By default, patients can download the requisition only while the order is open. A lab order is open until the chart shows all of its reports received. An imaging order is open until it has a result, not counting results deleted in Data Integration. To let patients download the requisitions of completed orders too, [contact Canvas Support](https://canvas-medical.help.usepylon.com/) to set `PATIENT_PORTAL_REQUISITION_ORDER_STATES` to **Open and completed orders**.
  - Each download is recorded in the [audit log](/guides/audit-logging-and-telemetry/) against the patient, and fires an event your plugin can respond to.
##  Track Document Downloads 
Each after-visit summary or requisition download fires the [`PATIENT_PORTAL__DOCUMENT_DOWNLOADED`](/sdk/events/#patient-portal-events) event, so your plugin can keep its own record of which documents a patient has received. The event targets the patient. It is sent after the PDF is served, so a handler can't delay or block the download.
The event context names the `document` and the record it came from:
`document`| Record key| Record  
---|---|---  
`"after_visit_summary"`| `note_id`| The `id` of the [Note](/sdk/data-note/)  
`"lab_requisition"`| `order_id`| The `id` of the [LabOrder](/sdk/data-labs/#laborder)  
`"imaging_requisition"`| `order_id`| The `id` of the [ImagingOrder](/sdk/data-imaging/#imagingorder)  
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    class TrackDocumentDownloads(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__DOCUMENT_DOWNLOADED)
        def compute(self) -> list[Effect]:
            document = self.context.get("document")
            if document == "after_visit_summary":
                log.info(f"After-visit summary downloaded for note {self.context['note_id']}")
            elif document in ("lab_requisition", "imaging_requisition"):
                log.info(f"{document} downloaded for order {self.context['order_id']}")
            return []
    ```
##  Forms 
Forms let you dynamically display questionnaires to patients in the portal based on your own criteria, and commit each response to the patient's chart as a Questionnaire Command when they submit. Because your handler runs on every portal page load, return only the forms that should currently appear.
> **Warning:** Set `create_command=True` on almost every form. It's what puts the patient's response in the chart — as a committed Questionnaire Command in a note. Without it, the response is saved only as an Interview and never surfaces in the chart, so the care team won't see it. Leave it off only when you have a specific reason.
Respond to the `PATIENT_PORTAL__GET_FORMS` event and return a `FormResult` effect for each questionnaire to show.
###  Methods 
####  apply() → Effect 
Shows the questionnaire to the patient.
  - `questionnaire_id` is required.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`questionnaire_id`| `str` | `UUID`| The unique ID of the [Questionnaire](/sdk/data-questionnaire/#questionnaire) to show.| Yes  
`create_command`| `bool`| **Strongly recommended`True`.** Commits the response as a Questionnaire Command in a note so it appears in the chart. When `False` (the default), the response is saved only as an Interview and never appears in a note.| No  
`note_id`| `str` | `UUID` | `None`| The [Note](/sdk/data-note/#note) to place the command on. Only used when `create_command` is `True`; if omitted, Canvas creates and locks a new note for it. Has no effect on its own.| No  
###  Example 
Assign intake questionnaires when a patient has a confirmed upcoming visit, skipping any they've already completed:
    ```python
    import arrow
    from canvas_sdk.effects.patient_portal.form_result import FormResult
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Interview, Patient, Questionnaire
    from canvas_sdk.v1.data.appointment import AppointmentProgressStatus
    INTAKE_QUESTIONNAIRES = ["Insurance Details", "Preferred Pharmacy Details", "Social History"]
    APPOINTMENT_NOTE_TYPES = ["Telehealth", "Office visit"]
    class Handler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__GET_FORMS)
        def _upcoming_appointment_note_id(self, appointments):
            return appointments.filter(
                status=AppointmentProgressStatus.CONFIRMED,
                start_time__gt=arrow.now().date(),
                note_type__name__in=APPOINTMENT_NOTE_TYPES,
            ).values_list("note__id", flat=True).first()
        def compute(self):
            patient = Patient.objects.get(id=self.target)
            # Only assign intake forms when there's a confirmed upcoming visit
            note_id = self._upcoming_appointment_note_id(patient.appointments)
            if not note_id:
                return []
            # Which intake questionnaires are already completed *on this visit's note*.
            # committed() automatically drops entered-in-error and uncommitted interviews.
            # The same intake form is expected each visit, so scope the check to this note
            # rather than the whole patient.
            completed = set(
                Interview.objects.for_patient(patient.id)
                .committed()
                .filter(note_id=note_id, questionnaires__name__in=INTAKE_QUESTIONNAIRES)
                .values_list("questionnaires__name", flat=True)
            )
            missing = [name for name in INTAKE_QUESTIONNAIRES if name not in completed]
            missing_ids = Questionnaire.objects.filter(name__in=missing).values_list("id", flat=True)
            return [
                FormResult(questionnaire_id=qid, create_command=True, note_id=note_id).apply()
                for qid in missing_ids
            ]
    ```
**Best practices:**
  - **Match questionnaires by name, not ID — it always resolves to the latest version.** When a questionnaire is updated, the previous version is archived with a `(v#)` suffix on its name (e.g. `Social History (v1)`) while the current version keeps the clean name. Filtering by the exact name therefore returns only the latest version, and (as a bonus) stays portable across instances, where IDs differ.
  - **Prevent duplicates — but scope the check.** This logic runs on every page load, so check existing committed `Interview` responses before assigning a form again. Because the same intake form is typically expected at every visit, scope that check to the current appointment's `note_id` rather than the whole patient (use `.committed()` so entered-in-error responses are ignored automatically).
  - **Don't let forms linger.** Return a questionnaire only while it should be shown; once it's completed or no longer relevant, stop returning it.
  - **Always land responses in the chart.** Set `create_command=True` so each submission is committed as a Questionnaire Command; pass a `note_id` to target a specific note, or omit it to let Canvas create one. Without `create_command`, the response is only an Interview and the care team won't see it.
Real-world example: the MSF [patient-portal-forms](https://github.com/medical-software-foundation/canvas/tree/main/extensions/patient-portal-forms) extension assigns questionnaires (PHQ-9, GAD-7, ROS…) that patients complete in the portal, posting responses back to the chart.
###  Writing answers back to the chart 
A submitted form is stored as an [Interview](/sdk/data-questionnaire/#interview), which links the patient to the questionnaire. To use the answers elsewhere in the chart, such as updating the patient's demographics, respond to the [`INTERVIEW_CREATED`](/sdk/events/#interviews) event, and to `INTERVIEW_UPDATED` as well, since answers can arrive after the Interview is created. The event targets the Interview and carries the patient's id. Read the answers from the Interview, then:
  - Update demographics, contact details, and other patient fields with the [patient effects](/sdk/effect-patient/).
  - Record insurance coverage through the FHIR [Coverage](/api/coverage/) API, using the [Canvas FHIR client](/sdk/clients-canvas-fhir/), since no SDK effect writes coverage.
##  User Login 
These effects manage a patient's portal **user account** — the login they use to access the portal. Invites and password resets are sent to the email or phone linked on the user, so make sure those contact points are actually **verified** before you invite a patient or rely on an updated value. Trigger a verification with the [Send Contact Verification](/sdk/effect-send-contact-verification/) effect.
###  Update User 
The `UpdateUserEffect` updates a portal user's phone number or email. In the future this may support additional attributes, but for now only these two are supported. It isn't tied to a specific portal event — emit it from whatever handler fits your workflow (a common one is keeping the portal user in sync in response to `PATIENT_CONTACT_POINT_UPDATED`, as below).
####  Methods 
#####  apply() → Effect 
Updates the user's phone number or email.
  - `user_dbid` is required, and must be the `dbid` of an existing user; otherwise the effect returns a `User does not exist` error.
  - Only the fields you set are changed, and setting one to `None` clears it. With neither set, nothing changes.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`user_dbid`| `int`| The `dbid` of the [CanvasUser](/sdk/data-canvasuser/#user) to update.| Yes  
`phone_number`| `str`| The phone number to store.| No  
`email`| `str`| The email to store.| No  
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.update_user import UpdateUserEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import PatientContactPoint
    from canvas_sdk.v1.data.common import ContactPointSystem
    class SyncPortalUser(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CONTACT_POINT_UPDATED)
        def compute(self) -> list[Effect]:
            contact_point = PatientContactPoint.objects.get(id=self.target)
            # Only sync verified contact points. last_verified is set once the patient
            # completes the verification challenge (see Send Contact Verification); until
            # then the value shouldn't be trusted as the account's login channel.
            if not contact_point.last_verified:
                return []
            user = contact_point.patient.user
            # Only update when the value actually changed. Emitting an effect that sets the
            # user to what it already is is a no-op — and can retrigger
            # PATIENT_CONTACT_POINT_UPDATED, causing an update loop.
            if contact_point.system == ContactPointSystem.EMAIL and user.email != contact_point.value:
                return [UpdateUserEffect(user_dbid=user.dbid, email=contact_point.value).apply()]
            if contact_point.system == ContactPointSystem.PHONE and user.phone_number != contact_point.value:
                return [UpdateUserEffect(user_dbid=user.dbid, phone_number=contact_point.value).apply()]
            return []
    ```
###  Send Invite 
The `SendInviteEffect` triggers a portal invitation that lets the patient register or activate their portal account. Because the invite is delivered to the patient's email or phone, only send it once that contact point is **verified** (`PatientContactPoint.last_verified` is set — see [Send Contact Verification](/sdk/effect-send-contact-verification/)) and the patient hasn't already registered (`CanvasUser.is_portal_registered`). Verification completes with a save that fires `PATIENT_CONTACT_POINT_UPDATED`, which makes it a natural trigger for the invite. Re-inviting someone who has already activated their account just sends a redundant email/SMS.
####  Methods 
#####  apply() → Effect 
Sends the portal invitation.
  - `user_dbid` is required, and must be the `dbid` of an existing user; otherwise the effect returns a `User does not exist` error.
####  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`user_dbid`| `int`| The `dbid` of the [CanvasUser](/sdk/data-canvasuser/#user) to invite.| Yes  
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.send_invite import SendInviteEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import PatientContactPoint
    class InviteVerifiedPatient(BaseHandler):
        # Verification completes with a save that fires this event
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CONTACT_POINT_UPDATED)
        def compute(self) -> list[Effect]:
            contact_point = PatientContactPoint.objects.get(id=self.target)
            # Only invite once the contact point is actually verified — that's the
            # channel the invitation will be delivered to.
            if not contact_point.last_verified:
                return []
            user = contact_point.patient.user
            # Only invite once: skip if there's no portal user yet, or they've already registered
            if user is None or user.is_portal_registered:
                return []
            return [SendInviteEffect(user_dbid=user.dbid).apply()]
    ```
**Sending versus minting a link.** `SendInviteEffect` lets Canvas send the invite over the patient's verified contact point, and it records the send on `CanvasUser.last_invite_date_time`. To deliver the invite or password reset over your own transport instead, mint a link with [`patient_portal_http.get_login_url()`](/sdk/utils/#getting-a-patient-portal-login-link) and send it yourself. Minting a link does not update `last_invite_date_time`; only `SendInviteEffect` does. Canvas has no record that you delivered the link, so the patient's Portal section is unchanged and staff may send a second invite to a patient who already holds a live link.
What the patient does with the link is still visible in that section. Setting up the account sets `is_portal_registered` on the [CanvasUser](/sdk/data-canvasuser) data module, which replaces the pending username with theirs and changes the button to `Reset password`. Signing in is a separate step that sets `last_login`, which is what replaces "The patient has never logged in to the patient portal." with a last login time. Opening the link and setting a password does not sign the patient in, so a registered patient who has not yet signed in shows both their username and the never-logged-in line.

---

# Payment Processor

Source: https://docs.canvasmedical.com/sdk/payment-processor-effect/

These effects are returned from a custom [Payment Processor](/sdk/handlers-payment-processors/) handler in response to the `REVENUE__PAYMENT_PROCESSOR__*` [events](/sdk/events/#payment-processor-events). Each effect is the handler's reply to a specific stage of a payment workflow — advertising the processor, rendering a form, charging a card, or managing a patient's saved payment methods.
All of the classes below are importable from `canvas_sdk.effects.payment_processor`.
##  Methods 
###  apply() → Effect 
Every class on this page has an `apply()` method, and the base payment processor handler calls it for you: return the object itself from the matching handler method, as the examples below do. Attributes marked **Yes** under Required must be set.
##  PaymentProcessorMetadata 
Advertises a payment processor to Canvas in response to `REVENUE__PAYMENT_PROCESSOR__LIST`. Canvas uses it to discover which processors are installed and to route later events (charge, add card, etc.) to the right handler.
**You normally never construct this yourself.** The base `PaymentProcessor` handler builds and returns it automatically through its `metadata()` method, which fills in:
  - `identifier` — a stable, unique id derived from your handler class (its module path and class name), exposed as `self.identifier`. Canvas includes this `identifier` in every subsequent payment processor event so your handler knows the event is meant for it.
  - `type` — the processor's `TYPE` class attribute (for example, `CardPaymentProcessor` sets this to `CARD`).
Because the base handler already responds to `REVENUE__PAYMENT_PROCESSOR__LIST` with this effect, you only need to construct it directly in advanced cases where you override that default behavior.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`identifier`| `str`| Unique identifier of the payment processor. Generated automatically per handler.| Yes  
`type`| PaymentProcessorType| The kind of processor. Currently only `CARD` is supported.| Yes  
###  PaymentProcessorType 
Value| Description  
---|---  
`CARD`| A card-based processor.  
##  PaymentProcessorForm 
Returns the HTML form used to collect and tokenize card details, in response to `REVENUE__PAYMENT_PROCESSOR__SELECTED`. The `content` is rendered as inner HTML inside Canvas and must implement the [Form Workflow](/sdk/handlers-payment-processors/#form-workflow).
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`intent`| `str`| The purpose of the form. One of `"pay"` or `"add_card"`.| Yes  
`content`| `str`| The HTML content to render inside Canvas.| Yes  
    ```python
    from canvas_sdk.effects.payment_processor import PaymentProcessorForm
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Patient
    def payment_form(self, patient: Patient | None = None) -> PaymentProcessorForm:
        content = render_to_string("templates/payment_form.html")
        return PaymentProcessorForm(intent="pay", content=content)
    ```
##  CardTransaction 
Returns the result of charging a card, in response to `REVENUE__PAYMENT_PROCESSOR__CHARGE`.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`success`| `bool`| Whether the charge succeeded.| Yes  
`transaction_id`| `str \| None`| The identifier of the transaction, if one was created.| Yes  
`api_response`| `dict`| The raw response returned by the payment provider.| Yes  
`error_code`| `str \| None`| An error code describing why the charge failed, if applicable.| No  
    ```python
    from decimal import Decimal
    from typing import Any
    from canvas_sdk.effects.payment_processor import CardTransaction
    from canvas_sdk.v1.data import Patient
    def charge(
        self, amount: Decimal, token: str, patient: Patient | None = None, **kwargs: Any
    ) -> CardTransaction:
        return CardTransaction(
            success=True,
            transaction_id="txn_123",
            api_response={"status": "succeeded"},
        )
    ```
##  PaymentMethod 
Represents a patient's saved payment method, returned in response to `REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__LIST`.
The cards managed by your custom processor live with your third-party payment provider — your processor is responsible for persisting them there when a card is added and deleting them when a card is removed. Canvas does not persist them for you; it asks your handler for the current list each time it needs to display saved cards, and the values you return here are rendered directly.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`payment_method_id`| `str`| The identifier of the saved payment method.| Yes  
`brand`| `str`| The card brand (e.g. `"Visa"`).| Yes  
`card_holder_name`| `str \| None`| The name of the card holder.| Yes  
`expiration_year`| `int`| The card's expiration year.| Yes  
`expiration_month`| `int`| The card's expiration month.| Yes  
`card_last_four_digits`| `str`| The last four digits of the card number.| Yes  
`postal_code`| `str \| None`| The billing postal code.| No  
`country`| `str \| None`| The billing country.| No  
    ```python
    from canvas_sdk.effects.payment_processor import PaymentMethod
    from canvas_sdk.v1.data import Patient
    def payment_methods(self, patient: Patient | None = None) -> list[PaymentMethod]:
        return [
            PaymentMethod(
                payment_method_id="pm_1",
                brand="Visa",
                card_holder_name="John Doe",
                expiration_year=2030,
                expiration_month=12,
                card_last_four_digits="4242",
                postal_code="12345",
            )
        ]
    ```
##  AddPaymentMethodResponse 
Returns the result of adding a payment method, in response to `REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__ADD`.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`success`| `bool`| Whether the payment method was added.| Yes  
    ```python
    from typing import Any
    from canvas_sdk.effects.payment_processor import AddPaymentMethodResponse
    from canvas_sdk.v1.data import Patient
    def add_payment_method(self, token: str, patient: Patient, **kwargs: Any) -> AddPaymentMethodResponse:
        return AddPaymentMethodResponse(success=True)
    ```
##  RemovePaymentMethodResponse 
Returns the result of removing a payment method, in response to `REVENUE__PAYMENT_PROCESSOR__PAYMENT_METHODS__REMOVE`.
###  Attributes 
Attribute| Type| Description| Required  
---|---|---|---  
`success`| `bool`| Whether the payment method was removed.| Yes  
    ```python
    from canvas_sdk.effects.payment_processor import RemovePaymentMethodResponse
    from canvas_sdk.v1.data import Patient
    def remove_payment_method(self, token: str, patient: Patient) -> RemovePaymentMethodResponse:
        return RemovePaymentMethodResponse(success=True)
    ```

---

# Plugin Logs

Source: https://docs.canvasmedical.com/sdk/plugin-logs/

Canvas provides two ways to access **Plugin Logs** :
  - **UI:** `https://<your-instance>.canvasmedical.com/admin/plugin-io` → **Logs**
  - **CLI:** `canvas logs --help`
This guide explains how to open the UI view and how to use the CLI to filter, paginate, and (optionally) follow live logs.
* * *
###  Plugin Logs in the Admin UI 
From the Django Admin:
Navigation path:  
`Home` › `Plugin_IO` › **Plugin Logs**
The UI lets you:
  - Filter by **source** (e.g., `plugin-runner`, `effect-interpreter`)
  - Filter by **level** (`ERROR`, `WARN`, `INFO`, `DEBUG`)
  - Filter by **plugin** — multi-select; the dropdown is pre-populated with plugins seen in the last 7 days, and accepts free-text entries for older or yet-to-log plugins
  - Filter by **handler** — multi-select on the fully-qualified handler class; works the same as plugin (last 7 days + free-text)
  - Filter by **time** (start/end)
  - Inspect **full JSON** of a log entry in a modal
  - **Load more** results without leaving the page
The results table shows columns for `@timestamp`, `level`, `source`, `plugin`, and `message`. Click a row to open the full log entry as JSON.
> **Info:** The UI defaults to showing the most recent logs first (sorted by `@timestamp desc`).
* * *
###  CLI Overview 
`canvas logs` now supports **historical lookback** , **filters** , **stateless pagination** with **cursors** , and **interactive paging** , all without breaking the original behavior.
  - **Default (no flags)** → live stream (unchanged)
  - **Add a time window** → fetch history (tail), then **follow** by default
  - **Stop after history** → `--no-follow`
  - **Page through large result sets** → `--limit`, `--page-size`, `--interactive`, or **cursor** tokens
Run `canvas logs --help` to see all options.
###  Common Filters & Examples 
#####  Filter by source 
    ```console
    $ canvas logs --source plugin-runner
    ```
#####  Filter by level (repeat flag) 
    ```console
    # Only errors:
    $ canvas logs --level ERROR
    # Errors and warnings:
    $ canvas logs --level ERROR --level WARN
    ```
#####  Filter by plugin / handler (repeatable) 
    ```console
    # One plugin:
    $ canvas logs --plugin my_plugin
    # Multiple plugins:
    $ canvas logs --plugin my_plugin --plugin other_plugin
    # A specific handler (fully qualified class name):
    $ canvas logs --handler my_plugin.handlers.foo.MyHandler
    # Multiple handlers:
    $ canvas logs --handler my_plugin.handlers.foo.MyHandler --handler my_plugin.handlers.bar.OtherHandler
    ```
#####  Time windows: since / start / end 
**Relative lookback (`--since`)**  
Fetch the last 24 hours, then continue following:
    ```console
    $ canvas logs --since 24h
    ```
**Absolute window (`--start/--end`)**  
Fetch a fixed window and stop:
    ```console
    $ canvas logs --start "2025-09-12T10:00:00Z" --end "2025-09-12T12:00:00Z" --no-follow
    ```
> **Info:** `--since` is mutually exclusive with `--start/--end`.
#####  Combine filters 
    ```console
    # Errors from plugin-runner in the last 2 hours:
    $ canvas logs --since 2h --level ERROR --source plugin-runner --no-follow
    ```
* * *
###  Interactive Mode 
Use `--interactive` in **historical** mode to page through results one page at a time:
    ```console
    $ canvas logs --no-follow --since 24h --interactive
    # Shows one page, prompts:
    # Load more? [Y/n]
    ```
  - The prompt repeats after each page.
* * *
###  Stateless Paging with Cursors 
When more results are available, the CLI prints a **resume command** with a **cursor token** (encodes the `search_after` and original filters). Re-run it to continue exactly where you left off:
    ```console
    More available. To load the next page, run:
      canvas logs \
      --no-follow \
      --cursor <TOKEN>
    ```
> **Warning:** `--cursor` is **mutually exclusive** with filters (`--since`, `--start/--end`, `--level`, `--source`, `--plugin`, `--handler`) to enforce consistency. Use the token alone to resume
.
* * *
###  Limits & Page Size 
  - **`--page-size`** : how many logs to fetch per request (batching).  
Default is optimized for typical usage.
  - **`--limit`** : maximum number of logs to print **across pages**.
Examples:
    ```console
    # One fixed page of size 200 (default page-size):
    $ canvas logs --no-follow --since 24h
    # Fetch up to 2000 logs across pages (non-interactive):
    $ canvas logs --no-follow --since 72h --limit 2000
    # Smaller batches for slow connections:
    $ canvas logs --no-follow --since 24h --limit 1000 --page-size 100
    ```
> **Info:** In non-interactive, no-limit mode, the CLI prints **one page**. Add `--limit`, `--interactive`, or `--all` to keep paging.
* * *
###  No-Follow (Historical Only) 
Add `--no-follow` to fetch **only** historical logs and exit:
    ```console
    $ canvas logs --no-follow --since 24h
    ```

---

# Handlers & Protocols

Source: https://docs.canvasmedical.com/sdk/protocols/

The handlers module lets you define workflows and workflow automations. Handlers respond to [Events](/sdk/events/) and return zero, one, or many [Effects](/sdk/effects/).
`ClinicalQualityMeasure` is a specialized handler base class for clinical protocols — see ClinicalQualityMeasure below.
> **Danger:** **With great power comes great responsibility.** Your handler runs **synchronously** inside a worker. Slow handler code — especially code that makes a blocking network call to an external service (an LLM API, a third-party HTTP endpoint) — holds that worker for its entire duration. If the external service slows down or goes offline, every invocation piles up until the worker pool is exhausted, and your **entire Canvas instance can be negatively impacted or even temporarily stop responding to requests**. Long timeouts and retries multiply the damage: a 300 second timeout retried three times pins a single worker for over ten minutes. Keep your handler fast, and move long-running or failure-prone work off the synchronous path — see [Keep your handler fast](/sdk/handlers-basehandler/#keep-your-handler-fast).
##  Contents 
  - BaseHandler
  - ClinicalQualityMeasure
##  BaseHandler 
`BaseHandler` is the abstract base class all handler implementations inherit from. It provides the lifecycle and surface area plugin authors implement for event-driven handlers.
###  Purpose & lifecycle 
  - The framework will call `compute()` on the handler instance when an event should be handled. `compute()` must return a list of `Effect` objects that the runtime will apply.
  - Handlers must override the `compute()` method.
###  Constructor and attributes 
  - Your handler should inherit from `BaseHandler` and define the following:
    - `RESPONDS_TO` — The `Event(s)` that trigger the handler.
    - `compute` — The method that handles the Event and returns a list of Effects.
  - Instance attributes available to handler authors:
    - `self.event` — The `Event` instance.
    - `self.secrets` — Secrets provided to the handler (defaults to {}).
###  Example 
    ```python
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.events import EventType
    from canvas_sdk.effects.task import AddTask
    class SimpleFollowUpHandler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.IMAGING_REPORT_CREATED)
        def compute(self):
            # Use self.event, self.secrets
            patient_id = self.event.context["patient"]["id"]
            imaging_report_id = self.event.target.id
            # Create a follow-up task effect
            return [AddTask(patient_id=patient_id, title="Follow-up", linked_object_type=AddTask.LinkableObjectType.IMAGING, linked_object_id=imaging_report_id).apply()]
    ```
##  ClinicalQualityMeasure 
`ClinicalQualityMeasure` is the base class for clinical quality measure (CQM) protocols. CQMs are patient-centric protocols used to evaluate, detect, or surface clinical conditions, gaps in care, and population-level metrics. Plugin authors create concrete subclasses that implement the clinical logic and return Effects in response to incoming Events.
When using `ClinicalQualityMeasure`, you have the option to utilize the [Campaigns](https://help.canvasmedical.com/articles/3097826946-campaigns-populations-patients) module in Canvas. However, the `ClinicalQualityMeasure` must return a single [`ProtocolCard`](/sdk/effect-protocol-cards/) effect in order to for patients to be included in the population for that CQM.
###  Meta properties 
Subclasses should populate the `Meta` inner class. Common meta fields include:
  - `title` (str): Human-readable title for the protocol.
  - `identifiers` (list[str]): One or more external identifiers for the measure (for example, CMS/QDM ids). These will show in the subtitle of the protocol card.
  - `description` (str): A short description of what the measure evaluates.
  - `information` (str): Longer contextual information or rationale.
  - `references` (list[str]): Links or identifiers for authoritative references. These are visible in the info button on the protocol card.
  - `source_attributes` (dict[str, str]): Map of the 13 or 31 source attributes that certified health IT developers must reference when implementing DSI or PDSI. These are visible in the info button on the protocol card.
  - `types` (list[str]): Tags or classification strings for the measure, like "CQM" or "HCC". These are visible in the subtitle of the protocol card.
  - `authors` (list[str]): Authors or maintainers of the protocol.
  - `show_in_chart` (bool): Determines whether the protocol card will show on the patient's chart.
  - `show_in_population` (bool): Determines whether the protocol will be included in the Campaigns module of Canvas.
  - `can_be_snoozed` (bool): Determines whether a user can snooze the protocol card to be addressed at a later date.
  - `is_abstract`, `is_predictive` (bool): Behavioral flags for the framework.
###  Key methods 
  - `timeframe` (property) -> `Timeframe`
    - Provides the default timeframe used by the protocol when searching for relevant events or records. The default implementation returns a timeframe with a start one year before now and an end at the current time. Subclasses can override this property to adjust the window of interest.
  - `relative_float(value: str) -> float`
    - Parses comparison-style numeric strings that may include relational prefixes like `<`, `<=`, `>` or `>=`. Returns a float adjusted slightly (±1e-6) for strict `<` or `>` operators so comparisons can be expressed without ambiguity. If parsing fails, returns `0`.
  - `patient_id_from_target()` -> str
    - Extracts and caches the patient id from a protocol event target for supported event types. The method supports a variety of patient-centric event targets (Conditions, LabOrders, LabReports, Medications, Patient create/update events, and ProtocolOverride events). The first call will fetch and cache the patient id to avoid repeated DB lookups. If an unsupported event type is provided a `ValueError` is raised.
###  Example — react to a lab report 
This example shows a protocol that reacts to `LAB_REPORT_CREATED` events, uses `patient_id_from_target` to determine which patient the report belongs to, and emits an Effect when a particular lab value is out of range. Note the example avoids heavy synchronous DB work and emits an Effect for the platform to handle asynchronously.
    ```python
    from datetime import datetime
    from canvas_sdk.commands import TaskCommand
    from canvas_sdk.effects.protocol_card import ProtocolCard
    from canvas_sdk.events import EventType
    from canvas_sdk.protocols.clinical_quality_measure import ClinicalQualityMeasure
    class AbnormalPotassiumMeasure(ClinicalQualityMeasure):
        """Detects clinically significant potassium abnormalities and surfaces follow-up tasks."""
        class Meta:
            title = "Abnormal Potassium Alert"
            identifiers = ["CQM-K-001"]
            description = "Creates a task recommendation when a potassium lab report shows hypokalemia or hyperkalemia."
            information = (
                "Detects clinically significant potassium abnormalities and surfaces follow-up tasks."
            )
            references = ["Potassium Guideline https://example.org/guideline/potassium"]
            source_attributes = {"Canvas Medical": "Canvas Medical https://www.canvasmedical.com"}
            types = ["CQM"]
            authors = ["Clinical Team"]
            show_in_chart = True
            show_in_population = True
            can_be_snoozed = False
            is_abstract = False
            is_predictive = False
        RESPONDS_TO = EventType.Name(EventType.LAB_REPORT_CREATED)
        def compute(self):
            # Resolve patient id (cached on first call)
            patient_id = self.patient_id_from_target()
            # Read the lab report values from the event target (avoid extra DB queries here)
            report = self.event.target
            potassium_value = report.get_value('potassium')  # simplified accessor
            # Use relative_float to safely parse any comparator-style values
            k = self.relative_float(str(potassium_value))
            if k < 3.5 or k > 5.5:
                # Emit an effect — e.g., create a task. Keep heavy work to platform handlers.
                task = TaskCommand(
                    title="Follow-up on abnormal potassium",
                    due_date=datetime.now().date(),
                )
                return [
                    ProtocolCard(
                        patient_id=patient_id,
                        title=f"Abnormal potassium: {k}",
                        due=datetime.now(),
                        key="abnormal_potassium",
                        narrative="Talk to patient about potassium",
                        recommendations=[task.recommend(title="Follow-up on abnormal potassium")],
                    ).apply()
                ]
            return []
    ```
![ProtocolCard]()
When a CQM protocol that returns a single ProtocolCard effect is uploaded to Canvas, you can select the protocol as an option in the Campaigns module and view the population of patients, create campaigns, etc. More details on Populations and Campaigns can be found [here](https://help.canvasmedical.com/articles/3097826946-campaigns-populations-patients).
###  Caveats & notes 
  - Timeframe: by default the protocol looks at the 1-year window prior to now. Override `timeframe` if your measure requires a broader or narrower lookback.
  - patient id resolution: `patient_id_from_target()` supports only the event types enumerated by the implementation; verify the event you plan to subscribe to maps to a supported model. When used heavily, this method avoids extra DB queries by caching the patient id on the instance.
  - Event-driven handlers should avoid expensive synchronous DB operations inside their event handler. When possible, emit Effects that are handled asynchronously by the platform.

---

# Sandboxing and Allowed Imports

Source: https://docs.canvasmedical.com/sdk/sandboxing-and-allowed-imports/

Plugins developed with the Canvas SDK operate within a sandboxed environment. This sandbox strictly limits access to the host operating system, filesystem, and database. This security measure is designed to mitigate risks associated with accidental misconfigurations or malicious activities, thereby safeguarding sensitive patient data.
##  Standard Library Modules 
The following Python standard library modules and their allowed imports are available within the sandbox:
#####  `__future__`
Provides access to features from future Python versions for backwards compatibility. [read more](https://docs.python.org/3/library/__future__.html)
  - `annotations`
#####  `abc`
Provides infrastructure for defining Abstract Base Classes (ABCs) to enforce interfaces and create structured inheritance hierarchies. [read more](https://docs.python.org/3/library/abc.html)
  - `ABC`
  - `abstractmethod`
#####  `base64`
Provides functions for encoding and decoding data in base64 format, commonly used for data transmission and storage. [read more](https://docs.python.org/3/library/base64.html)
  - `b64decode`
  - `b64encode`
  - `urlsafe_b64decode`
  - `urlsafe_b64encode`
#####  `bisect`
Provides functions for finding insertion points in a sorted list and inserting items while keeping it sorted. [read more](https://docs.python.org/3/library/bisect.html)
  - `bisect_left`
  - `bisect_right`
  - `insort`
#####  `collections`
Provides specialized container datatypes that extend beyond the built-in types like lists and dictionaries. [read more](https://docs.python.org/3/library/collections.html)
  - `Counter`
  - `defaultdict`
  - `OrderedDict`
#####  `copy`
Provides shallow and deep copy operations for duplicating objects. [read more](https://docs.python.org/3/library/copy.html)
  - `copy`
  - `deepcopy`
#####  `dataclasses`
This module provides a decorator and functions for automatically adding generated special methods such as **init**() and **repr**() to user-defined classes. [read more](https://docs.python.org/3/library/dataclasses.html)
  - `asdict`
  - `astuple`
  - `dataclass`
  - `field`
  - `Field`
  - `fields`
  - `InitVar`
  - `is_dataclass`
  - `make_dataclass`
  - `replace`
#####  `datetime`
Provides classes for working with dates and times, essential for medical applications that need to track appointment schedules and patient timelines. [read more](https://docs.python.org/3/library/datetime.html)
  - `date`
  - `datetime`
  - `time`
  - `timedelta`
  - `timezone`
  - `UTC`
#####  `dateutil`
Extends Python's datetime capabilities with more flexible date parsing and arithmetic. [read more](https://dateutil.readthedocs.io/en/stable/)
  - `relativedelta`
#####  `dateutil.relativedelta`
Provides relative time delta calculations for more complex date arithmetic operations. [read more](https://dateutil.readthedocs.io/en/stable/relativedelta.html)
  - `relativedelta`
#####  `decimal`
Provides precise decimal arithmetic for financial and scientific calculations where floating-point accuracy is critical. [read more](https://docs.python.org/3/library/decimal.html)
  - `Decimal`
#####  `defusedxml.ElementTree`
The defusedxml package contains several Python-only workarounds and fixes for denial of service and other vulnerabilities in Python's XML libraries. [read more](https://pypi.org/project/defusedxml/)
  - `fromstring`
#####  `email.mime.multipart`
Provides the MIME class for building multipart email messages, such as a message with a plain-text and an HTML part. [read more](https://docs.python.org/3/library/email.mime.html)
  - `MIMEMultipart`
#####  `email.mime.text`
Provides the MIME class for the text parts of an email message. [read more](https://docs.python.org/3/library/email.mime.html)
  - `MIMEText`
#####  `enum`
Provides support for enumerations, useful for defining sets of named constants such as status codes or categories. [read more](https://docs.python.org/3/library/enum.html)
  - `Enum`
  - `StrEnum`
#####  `functools`
Provides utilities for higher-order functions and operations on callable objects. [read more](https://docs.python.org/3/library/functools.html)
  - `reduce`
  - `wraps`
#####  `hashlib`
Provides secure hash and message digest algorithms for data integrity verification and security purposes. [read more](https://docs.python.org/3/library/hashlib.html)
  - `sha1`
  - `sha256`
#####  `hmac`
Provides hash-based message authentication code (HMAC) functions for secure message authentication. [read more](https://docs.python.org/3/library/hmac.html)
  - `compare_digest`
  - `new`
#####  `html`
Provides functions for escaping and unescaping HTML entities. [read more](https://docs.python.org/3/library/html.html)
  - `escape`
  - `HTML`
  - `unescape`
#####  `http`
Provides HTTP status codes and related constants for web API development and HTTP response handling. [read more](https://docs.python.org/3/library/http.html)
  - `HTTPStatus`
#####  `io`
Provides in-memory text and binary streams for working with data as if it were a file. [read more](https://docs.python.org/3/library/io.html)
  - `BytesIO`
  - `StringIO`
#####  `json`
Provides functions for parsing and generating JSON data, essential for API communication and data serialization. [read more](https://docs.python.org/3/library/json.html)
  - `dump`
  - `dumps`
  - `JSONDecodeError`
  - `load`
  - `loads`
#####  `operator`
Provides function equivalents of operators for functional programming and complex data operations. [read more](https://docs.python.org/3/library/operator.html)
  - `and_`
  - `or_`
#####  `random`
Provides functions for generating random numbers and making random selections, useful for sampling and testing scenarios. [read more](https://docs.python.org/3/library/random.html)
  - `choice`
  - `choices`
  - `randint`
  - `random`
  - `Random`
  - `sample`
  - `uniform`
#####  `re`
Provides regular expression matching operations for pattern matching and text processing. [read more](https://docs.python.org/3/library/re.html)
  - `compile`
  - `DOTALL`
  - `escape`
  - `findall`
  - `finditer`
  - `fullmatch`
  - `I`
  - `IGNORECASE`
  - `M`
  - `match`
  - `MULTILINE`
  - `S`
  - `search`
  - `split`
  - `sub`
#####  `secrets`
Provides cryptographically secure random values for tokens, verification codes, and other values that must be hard to guess. Use it instead of `random`, whose output is predictable. This module is unrelated to the plugin secrets declared in `CANVAS_MANIFEST.json`. [read more](https://docs.python.org/3/library/secrets.html)
  - `choice`
  - `compare_digest`
  - `randbelow`
  - `token_bytes`
  - `token_hex`
  - `token_urlsafe`
#####  `statistics`
Provides functions for calculating statistics of numeric data. [read more](https://docs.python.org/3/library/statistics.html)
  - `median`
#####  `string`
Provides string constants and template classes for string manipulation and formatting operations. [read more](https://docs.python.org/3/library/string.html)
  - `ascii_lowercase`
  - `digits`
#####  `time`
Provides time-related functions for measuring execution time and adding delays in processing. [read more](https://docs.python.org/3/library/time.html)
  - `monotonic`
  - `perf_counter`
  - `time`
  - `time_ns`
#####  `traceback`
Provides functions for extracting, formatting, and printing stack traces. [read more](https://docs.python.org/3/library/traceback.html)
  - `format_exc`
#####  `typing`
Provides support for type hints and static type checking to improve code clarity and IDE support. [read more](https://docs.python.org/3/library/typing.html)
  - `Any`
  - `Callable`
  - `cast`
  - `ClassVar`
  - `Dict`
  - `Final`
  - `Iterable`
  - `List`
  - `Literal`
  - `NamedTuple`
  - `NotRequired`
  - `Optional`
  - `Pattern`
  - `Protocol`
  - `Sequence`
  - `Tuple`
  - `TYPE_CHECKING`
  - `Type`
  - `TypedDict`
  - `TypeGuard`
  - `Union`
#####  `urllib`
Provides modules for working with URLs, including URL parsing and manipulation. [read more](https://docs.python.org/3/library/urllib.html)
  - `parse`
#####  `urllib.parse`
Provides URL parsing utilities for breaking apart and constructing URLs and query strings. [read more](https://docs.python.org/3/library/urllib.parse.html)
  - `parse_qs`
  - `quote`
  - `unquote`
  - `urlencode`
  - `urlparse`
#####  `uuid`
Provides functions for generating universally unique identifiers (UUIDs) for creating unique record identifiers. [read more](https://docs.python.org/3/library/uuid.html)
  - `NAMESPACE_URL`
  - `UUID`
  - `uuid4`
  - `uuid5`
#####  `xml.etree`
The package that contains the ElementTree XML API. [read more](https://docs.python.org/3/library/xml.etree.elementtree.html)
  - `ElementTree`
#####  `xml.etree.ElementTree`
Provides the ElementTree API for parsing and building XML documents. In the sandbox, parsing does not resolve external entities. [read more](https://docs.python.org/3/library/xml.etree.elementtree.html)
  - `Element`
  - `ElementTree`
  - `fromstring`
  - `indent`
  - `iterparse`
  - `parse`
  - `QName`
  - `register_namespace`
  - `SubElement`
  - `tostring`
#####  `zlib`
Provides compression and decompression compatible with gzip, along with checksum functions. [read more](https://docs.python.org/3/library/zlib.html)
  - `adler32`
  - `compress`
  - `compressobj`
  - `crc32`
  - `decompress`
  - `decompressobj`
  - `error`
  - `MAX_WBITS`
#####  `zoneinfo`
Provides timezone support for handling datetime objects across different time zones. [read more](https://docs.python.org/3/library/zoneinfo.html)
  - `ZoneInfo`
##  Third-Party Modules 
The following third-party modules and their allowed imports are available within the sandbox:
#####  `arrow`
A human-friendly approach to creating, manipulating, formatting and converting dates and times. [read more](https://arrow.readthedocs.io/en/latest/)
  - `Arrow`
  - `get`
  - `now`
  - `parser`
  - `utcnow`
#####  `arrow.parser`
The exceptions Arrow raises when it can't parse a date or time string. [read more](https://arrow.readthedocs.io/en/latest/api-guide.html#module-arrow.parser)
  - `ParserError`
  - `ParserMatchError`
#####  `certifi`
Provides the path to Mozilla's bundle of trusted root certificates. [read more](https://github.com/certifi/python-certifi)
  - `where`
#####  `django.contrib.postgres.indexes`
Django's PostgreSQL-specific index types for advanced indexing strategies. [read more](https://docs.djangoproject.com/en/stable/ref/contrib/postgres/indexes/)
  - `GinIndex`
#####  `django.core.exceptions`
Django's core exceptions, including the ones model queries and validation raise. [read more](https://docs.djangoproject.com/en/stable/ref/exceptions/#django-core-exceptions)
  - `ObjectDoesNotExist`
  - `PermissionDenied`
  - `ValidationError`
#####  `django.db`
Django's database module providing core database exceptions. [read more](https://docs.djangoproject.com/en/stable/ref/exceptions/#database-exceptions)
  - `DatabaseError`
  - `IntegrityError`
#####  `django.db.models`
Django's database abstraction layer for defining database models and performing queries. [read more](https://docs.djangoproject.com/en/stable/topics/db/models/)
  - `Avg`
  - `BigIntegerField`
  - `BooleanField`
  - `CASCADE`
  - `Case`
  - `CharField`
  - `Count`
  - `DateField`
  - `DateTimeField`
  - `DecimalField`
  - `DO_NOTHING`
  - `Exists`
  - `F`
  - `FloatField`
  - `ForeignKey`
  - `Func`
  - `Index`
  - `IntegerField`
  - `JSONField`
  - `ManyToManyField`
  - `Max`
  - `Min`
  - `OneToOneField`
  - `OuterRef`
  - `Prefetch`
  - `Q`
  - `RowRange`
  - `SET_NULL`
  - `Subquery`
  - `Sum`
  - `TextField`
  - `UniqueConstraint`
  - `Value`
  - `ValueRange`
  - `When`
  - `Window`
#####  `django.db.models.expressions`
Django's database expressions for complex query operations and conditional logic. [read more](https://docs.djangoproject.com/en/stable/ref/models/expressions/)
  - `Case`
  - `Exists`
  - `OuterRef`
  - `Subquery`
  - `Value`
  - `When`
#####  `django.db.models.functions`
Django's database functions for common SQL operations and window functions. [read more](https://docs.djangoproject.com/en/stable/ref/models/database-functions/)
  - `Coalesce`
  - `CumeDist`
  - `DenseRank`
  - `FirstValue`
  - `Lag`
  - `LastValue`
  - `Lead`
  - `Length`
  - `NthValue`
  - `Ntile`
  - `PercentRank`
  - `Rank`
  - `RowNumber`
  - `Trim`
#####  `django.db.models.query`
Django's QuerySet class for database query operations and result handling. [read more](https://docs.djangoproject.com/en/stable/ref/models/querysets/)
  - `Prefetch`
  - `QuerySet`
#####  `django.db.transaction`
Django's transaction management for atomic database operations. [read more](https://docs.djangoproject.com/en/stable/topics/db/transactions/)
  - `atomic`
  - `on_commit`
  - `on_rollback`
#####  `django.utils`
Django's utility package. [read more](https://docs.djangoproject.com/en/stable/ref/utils/)
  - `timezone`
#####  `django.utils.functional`
Django's functional programming utilities including caching and lazy evaluation tools. [read more](https://docs.djangoproject.com/en/stable/ref/utils/)
  - `cached_property`
#####  `django.utils.timezone`
Django's helpers for working with time zone aware datetimes. [read more](https://docs.djangoproject.com/en/stable/ref/utils/#module-django.utils.timezone)
  - `get_current_timezone`
  - `localdate`
  - `localtime`
  - `make_aware`
  - `now`
  - `utc`
#####  `jwt`
A library for encoding and decoding JSON Web Tokens (JWT) for secure data transmission and authentication. [read more](https://pyjwt.readthedocs.io/en/stable/)
  - `decode`
  - `encode`
  - `ExpiredSignatureError`
  - `InvalidTokenError`
  - `PyJWKClient`
`encode` can sign tokens with RS256, which some external APIs, such as Google's, require. The `cryptography` package that RS256 relies on is installed, but plugins can't import it directly.
#####  `pydantic`
A data validation library using Python type annotations for parsing and validating data structures. [read more](https://docs.pydantic.dev/)
  - `BaseModel`
  - `ConfigDict`
  - `conint`
  - `constr`
  - `Field`
  - `RootModel`
  - `ValidationError`
#####  `rapidfuzz`
A fast string matching library for fuzzy string comparison and search operations. [read more](https://maxbachmann.github.io/RapidFuzz/)
  - `fuzz`
  - `process`
  - `utils`
#####  `rapidfuzz.fuzz`
RapidFuzz's string similarity scorers. [read more](https://rapidfuzz.github.io/RapidFuzz/Usage/fuzz.html)
  - `partial_ratio`
  - `partial_ratio_alignment`
  - `partial_token_ratio`
  - `partial_token_set_ratio`
  - `partial_token_sort_ratio`
  - `QRatio`
  - `ratio`
  - `token_ratio`
  - `token_set_ratio`
  - `token_sort_ratio`
  - `WRatio`
#####  `rapidfuzz.process`
RapidFuzz's functions for comparing a string against a list of choices. [read more](https://rapidfuzz.github.io/RapidFuzz/Usage/process.html)
  - `cdist`
  - `cpdist`
  - `extract`
  - `extract_iter`
  - `extractOne`
#####  `rapidfuzz.utils`
RapidFuzz's string preprocessing utilities. [read more](https://rapidfuzz.github.io/RapidFuzz/Usage/utils.html)
  - `default_process`
#####  `requests.exceptions`
The exceptions the requests library raises, which the [`Http`](/sdk/utils/) util passes through. [read more](https://requests.readthedocs.io/en/latest/api/#exceptions)
  - `ConnectionError`
  - `HTTPError`
  - `JSONDecodeError`
  - `RequestException`
  - `Timeout`
##  Canvas SDK Modules 
All Canvas SDK modules are available for import and use within your plugins:
  - `canvas_sdk.caching`
  - `canvas_sdk.commands`
  - `canvas_sdk.effects`
  - `canvas_sdk.events`
  - `canvas_sdk.handlers`
  - `canvas_sdk.protocols`
  - `canvas_sdk.questionnaires`
  - `canvas_sdk.templates`
  - `canvas_sdk.utils`
  - `canvas_sdk.v1.data`
  - `canvas_sdk.value_set`
  - `canvas_sdk.views`
  - `logger`
##  Builtin Functions 
The following Python builtin functions are available within the sandbox:
  - `all`
  - `any`
  - `ascii`
  - `bytearray`
  - `classmethod`
  - `delattr`
  - `dict`
  - `dir`
  - `enumerate`
  - `extract_exc_frames`
  - `filter`
  - `format`
  - `getattr`
  - `hasattr`
  - `iter`
  - `list`
  - `map`
  - `max`
  - `memoryview`
  - `min`
  - `next`
  - `property`
  - `reversed`
  - `setattr`
  - `staticmethod`
  - `sum`
  - `super`
  - `type`
  - `vars`
On top of those, the sandbox inherits RestrictedPython's safe builtins. That covers the basic types (`bool`, `bytes`, `complex`, `float`, `frozenset`, `int`, `set`, `slice`, `str`, `tuple`), the common functions (`abs`, `callable`, `chr`, `divmod`, `hash`, `hex`, `id`, `isinstance`, `issubclass`, `len`, `oct`, `ord`, `pow`, `range`, `repr`, `round`, `sorted`, `zip`), and the `NotImplemented` constant. Every built-in exception and warning class is also available, including the `OSError` family such as `TimeoutError` and `ConnectionError`.
For HTTP calls, catch the exceptions in `requests.exceptions`. The [`Http`](/sdk/utils/) util passes them through unchanged:
    ```python
    from requests.exceptions import Timeout
    from canvas_sdk.utils import Http
    from logger import log
    client = Http()
    try:
        response = client.get("https://example.com/api")
    except Timeout:
        log.warning("The request to example.com timed out.")
    ```
###  Builtins that work differently 
A few builtins are narrower in the sandbox than in standard Python, so that they can't reach past the runtime restrictions:
Builtin| In the sandbox  
---|---  
`type`| Takes exactly one argument. `type(x)` returns the same thing as `x.__class__`, so for an object from outside your plugin you get a proxy that exposes only names. The three-argument form raises `TypeError`; declare classes with `class …:` instead.  
`dir`| Takes exactly one argument, and lists only the names your plugin can read on that object.  
`setattr`, `delattr`| Follow the same rules as `obj.x = value` and `del obj.x` (see writing attributes). They also refuse any name starting with `__`, any class defined outside your plugin, and a name starting with `_` on an object defined outside your plugin.  
`vars`| Requires an argument. For an object or module from outside your plugin it returns a filtered copy, the same as `__dict__`.  
###  Builtins that are not available 
What you see above is the whole set. The sandbox works from an allow-list rather than a list of banned names, so any builtin not mentioned there raises `NameError` when your plugin runs — including builtins that future Python releases introduce.
These are the ones plugin authors reach for most often:
Not available| Use instead  
---|---  
`eval`, `exec`, `compile`| Write the logic directly. The sandbox cannot run code it never reviewed.  
`open`, `input`| Neither the filesystem nor a console is reachable from a plugin.  
`print`| `log` from `logger`. `print` is also a reserved name.  
`globals`, `locals`| Nothing. Namespace introspection is a sandbox-escape route.  
##  Forbidden Constructs 
Beyond the import allow-list above, a few Python constructs compile under RestrictedPython but are rejected when your code runs in the sandbox. `canvas validate` catches these statically before you install, so you don't have to wait for a runtime failure on the instance.
Construct| Why it's rejected| Use instead  
---|---|---  
`type(name, bases, dict)`| The sandbox's `type` takes one argument, so dynamic class creation raises `TypeError`| Declare the class normally with `class …:`  
`obj.attr += v`| Augmented assignment to an attribute is rejected, including on classes you defined yourself| Explicit reassignment: `obj.attr = obj.attr + v`  
`d[k] += v`| Augmented assignment to a dict item, list item, or slice is rejected| Explicit reassignment: `d[k] = d[k] + v`  
Augmented assignment to a plain variable is fine — `count += 1`, `total *= 2`, and the rest of the `-=` / `*=` / `//=` / `%=` / `**=` / `&=` / `|=` / `^=` / `<<=` / `>>=` family all work. It is only the attribute and item forms above that are rejected, and both fail when the plugin is compiled, so you find out at install time rather than mid-request.
> **Info:** `@dataclass(frozen=True)` and `@dataclass(slots=True)` load and run fine in the sandbox — they are not forbidden.
> **Info:** `match` statements are allowed in plugin code.
###  `extract_exc_frames()`
A sandbox-provided function that extracts frame information from the current exception's traceback. Must be called from within an `except` block. Returns an empty list if no exception is active.
Each frame exposes only safe attributes:
  - `filename` — the file path
  - `lineno` — the line number
  - `name` — the function name
Source code lines and local variables are not accessible.
    ```python
    from logger import log
    try:
        raise Exception("some failed operation")
    except Exception:
        frames = extract_exc_frames()
        for frame in frames:
            log.info(f"{frame.filename}:{frame.lineno} in {frame.name}")
    ```
##  Runtime Restrictions 
The sandbox enforces the rules in this section every time an attribute is read or written, so they surface as an `AttributeError` while your plugin is running. That is what separates them from the forbidden constructs, which are rejected when your code is compiled and reported by `canvas validate` before you install. Except for the helper-module check below, nothing described here is caught until the code executes.
Throughout this section, **your plugin's code** means modules inside your own plugin package. **External code** means everything else — the Canvas SDK, the standard library, and third-party modules.
###  Helper modules 
The rules apply to every module in your plugin, not only the modules your manifest names as handlers. A helper module that a handler imports runs in the sandbox too, so its functions keep the sandbox's rules when a handler calls them.
A function body in a helper module runs only when something calls it. So the plugin runner also reads those bodies when it loads your plugin. If one contains a construct the rules refuse, the runner doesn't load the plugin. Every handler in the plugin then fails with a `PluginInstallationError` that lists each construct with its module and line. `canvas validate` and `canvas install` report the same error. The check looks for:
  - an import of a module that isn't on the allow-list
  - importing or reading a name that the allow-list doesn't grant from an allowed module, such as `re.Match`
  - reading `__dict__`, `raw`, or a restricted method name on any object
  - a `format` or `format_map` template whose fields read attributes or items (see string formatting)
  - any call to `vars()`
Fix each listed line, then validate again.
###  Reading attributes 
Attribute names that begin with an underscore are restricted, and the rule depends on where the object came from:
Object defined in| `_single_underscore`| `__dunder__`  
---|---|---  
Your plugin's code| Readable| Only names on the allow-list below  
External code| Blocked, except `_meta` on SDK models| Only names on the allow-list below  
The dunder allow-list is the same in both cases:
  - `__annotations__`
  - `__args__`
  - `__ceil__`
  - `__class__`
  - `__dict__`
  - `__doc__`
  - `__eq__`
  - `__floor__`
  - `__init__`
  - `__members__`
  - `__name__`
  - `__origin__`
  - `__round__`
  - `__traceback__`
  - `__trunc__`
Several names return a restricted stand-in rather than the real object:
  - **`__class__`** on an object defined outside your plugin, or on any class, returns a read-only proxy that exposes only `__name__` and `__mro__`. On an object your plugin defined, it returns the real class.
  - **`__mro__`** on any class returns a tuple of proxies that each expose only `__name__`. You can check a class's ancestry by name, but `__subclasses__()` and the classes themselves can't be reached to get outside the sandbox.
  - **`__dict__`** on an object, class, or module from outside your plugin returns a copy without any name that starts with an underscore. For a module, the copy holds only the names its allow-list entry grants. For an object that declares `__exports__`, it holds only those names. Changing the copy doesn't change the object. `vars()` returns the same copy. On your plugin's own objects and modules, both return the real namespace.
  - **`__traceback__`** returns a safe traceback exposing only `tb_frame`, `tb_lineno`, and `tb_next`. Its frame exposes only `f_code` and `f_lineno`, and that code object exposes only `co_filename` and `co_name`. Local and global variables are never reachable. `extract_exc_frames()` is the more convenient way to read a traceback.
  - **`_meta`** on an SDK model class or instance returns a read-only view for inspecting the model's fields. It exposes `app_label`, `concrete_fields`, `db_table`, `fields`, `get_field()`, `get_fields()`, `local_fields`, `model_name`, `pk`, `verbose_name`, and `verbose_name_plural`. Each field in it exposes `attname`, `blank`, `choices`, `column`, `concrete`, `default`, `get_internal_type()`, `is_relation`, `many_to_many`, `many_to_one`, `max_length`, `name`, `null`, `one_to_many`, `one_to_one`, and `related_model`. A field's `default` reads as `None` when the default is a callable.
Reading a plain attribute off an imported module is also limited to that module's entry in the allow-list at the top of this page. `json.dumps` works because `dumps` is listed under `json`; `json.tool` raises an `AttributeError`.
###  Attributes that don't exist 
In the sandbox, reading an attribute that nothing defines returns `None`, where standard Python raises `AttributeError`. This behavior is deprecated, and a future release will raise `AttributeError` instead. Until then, the first time your plugin reads each such name, a warning naming it appears in your [plugin logs](/sdk/plugin-logs/). `canvas validate` also lists the names your handlers read while they load. It can't see names read later, inside a handler method.
To read an attribute that may be absent, pass `getattr` a default. That returns the default without a warning:
    ```python
    class Reading:
        def __init__(self) -> None:
            self.value = 98.6
    reading = Reading()
    reading.unit                    # None for now, with a warning; AttributeError in a future release
    getattr(reading, "unit", None)  # None, with no warning
    ```
An `AttributeError` raised by an attribute that does exist propagates as it does in standard Python, rather than reading as `None`. Two examples are an error raised inside a property, and Django's `RelatedObjectDoesNotExist` from a one-to-one relation that has no related record. Catch the error, or pass `getattr` a default, where the value may be missing.
A read that the rules on this page refuse, such as an underscore name on an external object, still raises `AttributeError`.
###  Reading items 
A string key that starts with an underscore can be read from any dictionary, including subclasses such as `defaultdict`, `Counter`, and `OrderedDict`. The same goes for built-in containers and objects from the allowed standard-library and third-party modules. Other objects, including a class in your plugin that implements `__getitem__` without subclassing `dict`, raise an `AttributeError` for that key:
    ```python
    config = {"timeout": 30, "_internal": True}
    config["timeout"]    # fine
    config["_internal"]  # fine
    ```
###  Writing attributes 
You can set attributes on modules that belong to your plugin. Setting an attribute on any other module is blocked.
For objects, whether a write is allowed depends on where the object's class was defined:
  - **Class defined in your plugin's code** — writable, including attributes that are not methods.
  - **Class defined in external code** — the write is blocked if any of the following is true:
    - the name you are assigning through was brought in by an `import`
    - the attribute currently holds a callable, so the assignment would replace a method
    ```python
    class MyThing:
        """Defined in your plugin, so its instances are writable."""
        def __init__(self) -> None:
            self.count = 0
    thing = MyThing()
    thing.count = 1       # fine
    thing.label = "new"   # fine
    ```
###  Reserved names 
These four names cannot be used for a function, variable, class, or argument anywhere in your plugin:
  - `print`
  - `printed`
  - `builtins`
  - `breakpoint`
`print` is among them, so use the SDK logger for output:
    ```python
    from logger import log
    log.info("plugin started")
    ```
The sandbox also reserves `__metaclass__` and the names of its own guards: `_apply_`, `_getattr_`, `_getitem_`, `_getiter_`, `_inplacevar_`, `_iter_unpack_sequence_`, `_print`, `_print_`, `_unpack_sequence_`, and `_write_`. Binding one of them in any way, including as an import alias, a loop target, or an `except … as` name, is an error.
Names that start with two underscores can't be bound either, with three exceptions:
  - `__all__`
  - methods defined directly in a class body, such as `__init__` or `__str__`
  - function and lambda argument names
###  Introspection attributes 
The attributes the `inspect` module relies on are unavailable, because they expose frames, globals, and raw bytecode:
`co_code`, `cr_await`, `cr_code`, `cr_frame`, `cr_origin`, `f_back`, `f_builtins`, `f_code`, `f_generator`, `f_globals`, `f_locals`, `f_trace`, `gi_code`, `gi_frame`, `gi_yieldfrom`, `tb_frame`, `tb_next`
The safe traceback wrappers under reading attributes are the one exception: they re-expose `tb_frame`, `tb_next`, and `f_code` through an explicit allow-list, stripped down to the fields listed there.
These method names can't be read from any object, including your plugin's own:
`create_module`, `eval`, `exec`, `exec_module`, `find_loader`, `find_module`, `find_spec`, `load_module`, `mro`
To read a class's ancestry, use `__mro__` rather than `mro()`.
###  String formatting 
`format` and `format_map` work when you call them on a string. Their replacement fields can't read attributes or items of the values they format, so a field such as `{0.name}` or `{0[first_name]}` raises `NotImplementedError`. Read the value out first, then format it. Calling `format` through the `str` type, as in `str.format(template, value)`, also raises `NotImplementedError`.
    ```python
    patient = {"first_name": "Ada"}
    name = patient["first_name"]
    greeting = "Hello {}".format(name)                 # fine
    greeting = "Hello {name}".format(name=name)        # fine
    greeting = f"Hello {patient['first_name']}"        # fine
    greeting = "Hello {0[first_name]}".format(patient)  # NotImplementedError
    greeting = str.format("Hello {}", name)            # NotImplementedError
    ```
###  `__exports__`
Some SDK objects declare an `__exports__` attribute listing exactly which attribute names may be read from them. Where it is present it takes precedence over the other rules in this section: names in the list are readable, and anything else raises an `AttributeError`.
> **Info:** These rules are enforced by `plugin_runner/sandbox.py` in the [Canvas Plugins repository](https://github.com/canvas-medical/canvas-plugins), which is the authoritative reference if you hit a restriction that isn't described here.
##  Requesting Additional Imports 
If there is a library or function not on this list that you wish to import in your plugin, reach out on the [Canvas developer forum](https://github.com/canvas-medical/canvas-plugins/discussions). Additional imports can often be added after a security review.
The allowed imports are defined in the [Canvas Plugins repository](https://github.com/canvas-medical/canvas-plugins/blob/main/plugin_runner/sandbox.py) and are regularly updated to support common development needs while maintaining security.
###  Error monitoring 
Error-monitoring SDKs such as `sentry_sdk` are not available in the sandbox. Record errors and diagnostics with [plugin logging](/sdk/plugin-logs/) instead.
##  Policy on Vendor-Specific Libraries: 
The current policy strongly discourages the inclusion of vendor-specific libraries. Introducing such libraries presents several challenges:
  - Vendor Prioritization: It risks implicitly favoring one vendor over others, which can be problematic in a multi-vendor ecosystem.
  - Dependency Bloat: Incorporating libraries for each vendor within a specific category (e.g., AI model providers like OpenAI, Anthropic) leads to a significant increase in overall dependencies.
##  Technical Implications of Excessive Dependencies: 
Adding a multitude of vendor-specific libraries can result in:
  - Increased Memory Usage: Each additional library contributes to the application's memory footprint.
  - Dependency Conflicts: Different libraries may require different versions of shared dependencies, leading to versioning conflicts and system instability.
Given these considerations, the platform maintains a strict and judicious approach to approving and incorporating external libraries or imports.

---

# Managing Variables

Source: https://docs.canvasmedical.com/sdk/secrets/

Canvas provides a secure key-value store that lets your plugins access configuration data — including sensitive secrets such as API tokens — without hardcoding values into source files. Configuration values are declared in your plugin's [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#variables) as **variables** , set at install time or through the Admin UI, and read from `self.secrets` at runtime.
Each variable can be marked **sensitive** (treated like a secret: not displayed in admin or CLI listings) or **non-sensitive** (a regular configuration value, displayed in plaintext for verification). All variable values are write-only through the CLI and API.
###  Declaring Variables in `CANVAS_MANIFEST.json`
Variables are declared in your plugin's `CANVAS_MANIFEST.json` file under the top-level `variables` field. Each variable is an object with a `name` and an optional `sensitive` flag (defaults to `false`). Variables marked as `sensitive: true` are write-only and behave like secrets. These declared variables become available for configuration in the Canvas Admin UI when the plugin is installed.
    ```json
    {
      "sdk_version": "0.1.4",
      "plugin_version": "0.0.1",
      "name": "live_notifications",
      "description": "Edit the description in CANVAS_MANIFEST.json",
      "components": {
        "handlers": [
          {
            "class": "live_notifications.handlers.my_handler:Handler",
            "description": "A handler that does xyz..."
          }
        ]
      },
      "variables": [
        {"name": "API_TOKEN", "sensitive": true},
        {"name": "WEBHOOK_URL"},
        {"name": "LOG_LEVEL", "sensitive": false}
      ],
      "tags": {}
    }
    ```
Field| Type| Required| Description  
---|---|---|---  
`name`| string| Yes| The variable name used in your plugin code  
`sensitive`| boolean| No| When `true`, marks the variable as sensitive for display purposes (default: `false`)  
####  Legacy `secrets` array (deprecated) 
The flat `secrets` array is still accepted for backwards compatibility:
    ```json
    "secrets": ["API_TOKEN"]
    ```
It emits a deprecation warning during `canvas validate-manifest` and is mapped internally to `variables` entries with `sensitive: false`. To preserve sensitive treatment, migrate to the `variables` schema with `sensitive: true` and re-install the plugin.
> **Warning:** **Deprecation Notice:** The legacy `secrets` array format is deprecated. Use the `variables` format shown above instead. The legacy format will continue to work but displays a deprecation warning during `canvas validate-manifest`.
> ⚠️ **Pre-existing values default to non-sensitive.** Any plugin secret that existed before Canvas 1.305.0 — or any value configured via the legacy `secrets:` array — is stored with `sensitive: false`. It will appear in plain text in the Admin UI until the owning plugin is migrated to the `variables` schema with `sensitive: true` and re-installed.
###  Configuring Variables from the CLI 
Set values with [`canvas config set`](/sdk/canvas_cli/#canvas-config-set), passing `KEY=value` pairs. Each value keeps the sensitivity the manifest declares for it.
For a plugin deployed with [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy), Canvas Platform stores the values for each instance and a configure deployment brings them to the running plugin:
    ```console
    $ canvas config set acme__my_plugin API_TOKEN=abc123 LOG_LEVEL=info --instance acme-staging
    ```
Values stored for an instance before the plugin is installed there wait for its first deploy, so a plugin that needs a value from its first run can have it set first:
    ```console
    $ canvas deploy my-plugin/acme__my_plugin --push-only
    $ canvas config set acme__my_plugin API_TOKEN=abc123 --instance acme-staging
    $ canvas deploy my-plugin/acme__my_plugin --instance acme-staging
    ```
Clear a value with [`canvas config unset`](/sdk/canvas_cli/#canvas-config-unset):
    ```console
    $ canvas config unset acme__my_plugin LOG_LEVEL --instance acme-staging
    ```
> **Warning:** **Deprecated:** `canvas install --secret` and `--variable` set values while installing straight onto an instance with `credentials.ini`. Support ends on December 14, 2026; see [Moving to Canvas Platform](/guides/moving-to-canvas-platform/).
####  Listing configured values 
Run `canvas config list <plugin_name>` to see which variables are configured for a plugin. Each variable is rendered as `[set]` or `[not set]`, with a `(sensitive)` annotation for sensitive variables. Values themselves are never displayed in the listing.
    ```console
    $ canvas config list my_plugin
      API_TOKEN  [set]  (sensitive)
      LOG_LEVEL  [not set]
    ```
To read a value, use the Django Admin UI (access is gated by managing-user permissions).
> _The`--variable` flag, `canvas config list` sensitive marking, and Admin UI masking require Canvas CLI 0.146.0 or newer. Upgrade with `pip install --upgrade canvas`._
###  Configuring Variables in the Admin UI 
After install you can also set values through the Admin interface.
Navigation path: `Home` › `Plugin_IO` › `Plugins` › `(your plugin)`
Or, go directly to:
    https://<your_canvas_instance>/admin/plugin_io/plugin/<plugin_id>/change/
On this page, you will find input fields for each variable defined in your manifest. Sensitive values display as `SENSITIVE` and are no longer rendered in the form HTML — submit a new value to overwrite, or leave the field blank to keep the existing value. Non-sensitive values display their current value and can be edited inline.
![Setting plugin variables](/assets/images/sdk/secrets/plugins_secrets_settings_with_permissions.png)
Sensitive variables can be protected by managing user permissions. Only users explicitly assigned as "managing users" for a plugin can view or modify its sensitive variables (as well as other sensitive settings like the plugin package file download link). Other users can see basic plugin details and enable or disable plugins, but they will not be able to access or change sensitive variable values. To add or remove managing users for a plugin, use the "Managing users" section on the plugin detail page in the Admin UI. This ensures that sensitive configuration, such as API tokens, remains visible only to authorized personnel.
###  Accessing Variables in Your Plugin 
All variables — sensitive and non-sensitive alike — are exposed to your plugin code through `self.secrets`, a Python dictionary keyed by variable name:
    ```python
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects import Effect
    class MyHandler(BaseHandler):
        def compute(self) -> list[Effect]:
            api_token = self.secrets["API_TOKEN"]
            webhook_url = self.secrets["WEBHOOK_URL"]
            log_level = self.secrets["LOG_LEVEL"]
            ...
    ```
This access pattern is unchanged from earlier Canvas versions, so migrating a plugin from the legacy `secrets:` array to the new `variables:` schema requires no handler code changes.
> **Both steps are required.** `self.secrets["KEY"]` returns a value only after you have:
> 
>   1. Declared the key in `CANVAS_MANIFEST.json`.
>   2. Set a value for it, with the CLI or on the plugin configuration page in the Admin UI (`/admin/plugin_io/plugin/`).
> 
> 
> If either step is missing, the lookup returns no value.
###  Configuring SimpleAPI credentials 
A SimpleAPI route that authenticates with [`APIKeyAuthMixin`](/sdk/handlers-simple-api-http/#authentication-mixins) reads its key from the `simpleapi-api-key` secret, unless the route sets a different name in `API_KEY_SECRET_NAME`. Declare that secret, set its value in the secrets Admin UI, then send the **same** value in the `Authorization` header of each request to the route. If the configured secret and the header value do not match, or the secret has no value set, the endpoint responds with `401 Unauthorized` ("Provided credentials are invalid").

---

# SSO Capabilities

Source: https://docs.canvasmedical.com/sdk/sso/

Canvas supports SAML 2.0 single sign-on, and exposes hooks that let plugins participate in the post-login flow. Use these hooks to capture data from the identity provider's SAML response, or to send a user to a custom landing page after they authenticate.
Both hooks fire after the SAML assertion has been validated and the user has been logged in. The user's identity is available as [`self.event.actor`](/sdk/events/#event-actor); the SAML response data is available in `self.event.context`.
##  Hooks at a glance 
Hook| Type| Purpose  
---|---|---  
`SSO__PROCESS_ADDITIONAL_REQUEST_DATA`| Event| Read-only access to the SAML response so a plugin can capture IdP attributes (group memberships, employee ID, etc.).  
`SSO__GET_POST_LOGIN_REDIRECT`| Event| Override the URL the user lands on after SSO login.  
`REDIRECT_CONTEXT`| Effect| The effect returned from `SSO__GET_POST_LOGIN_REDIRECT` to set the post-login destination.  
##  `SSO__PROCESS_ADDITIONAL_REQUEST_DATA`
Fires once per successful SAML login, immediately after the user is authenticated. The event is **read-only** : any effects a handler returns are discarded. Use it for side-effects such as syncing IdP attributes onto a [`Staff`](/sdk/data-staff/) record, writing an audit log, or notifying an external system that a user signed in.
###  Context 
Key| Type| Description  
---|---|---  
`session_info`| dict| The validated SAML response data from pysaml2. Common keys include `name_id` (the SAML NameID), `issuer` (IdP entity ID), `ava` (a dict of IdP-supplied user attributes keyed by attribute name with list-valued entries), `session_index`, `not_on_or_after`, and `authn_info`.  
###  Target 
The Canvas user that just logged in. `self.event.target` resolves to a [`Staff`](/sdk/data-staff/) or [`Patient`](/sdk/data-patient/) via `self.event.actor.instance.person_subclass`.
###  Example 
    ```python
    import json
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from logger import log
    class CaptureSSOAttributes(BaseHandler):
        """Log the IdP-supplied group memberships for every SSO login."""
        RESPONDS_TO = EventType.Name(EventType.SSO__PROCESS_ADDITIONAL_REQUEST_DATA)
        def compute(self):
            session_info = json.loads(self.event.context)["session_info"]
            groups = session_info.get("ava", {}).get("groups", [])
            log.info(f"SSO login for {session_info['name_id']} with groups={groups}")
            return []
    ```
##  `SSO__GET_POST_LOGIN_REDIRECT`
Fires once per successful SAML login, right before Canvas decides where to send the user. A plugin that returns a `REDIRECT_CONTEXT` effect sets the destination URL; if no plugin returns one (or the value is falsy), Canvas falls back to its default post-login redirect.
Only the first `REDIRECT_CONTEXT` effect returned is used. If multiple plugins register a handler, ordering between them is not guaranteed — coordinate across plugins to avoid conflicting redirects.
###  Context 
Key| Type| Description  
---|---|---  
`relay_state`| str| The SAML `RelayState` value from the original login request, if any. Often used by IdPs to encode a "deep link" — the URL the user was trying to reach before they were bounced to the IdP.  
`session_info`| dict| Same shape as for `SSO__PROCESS_ADDITIONAL_REQUEST_DATA`.  
###  Target 
Same as `SSO__PROCESS_ADDITIONAL_REQUEST_DATA` — the Canvas user that just logged in.
###  Example 
    ```python
    import json
    from canvas_generated.messages.effects_pb2 import EffectType
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class RouteSSOByGroup(BaseHandler):
        """Send admins to the admin app and everyone else to the schedule."""
        RESPONDS_TO = EventType.Name(EventType.SSO__GET_POST_LOGIN_REDIRECT)
        def compute(self):
            session_info = json.loads(self.event.context)["session_info"]
            groups = session_info.get("ava", {}).get("groups", [])
            if "canvas-admins" in groups:
                url = "/admin/"
            else:
                url = "/schedule/"
            return [
                Effect(
                    type=EffectType.REDIRECT_CONTEXT,
                    payload=json.dumps({"url": url}),
                )
            ]
    ```
##  `REDIRECT_CONTEXT`
The effect that carries the post-login URL back to Canvas. It is only meaningful when returned from a `SSO__GET_POST_LOGIN_REDIRECT` handler.
###  Payload 
Key| Type| Description  
---|---|---  
`url`| str| The URL Canvas should redirect the user to after SSO login. Relative paths (e.g. `/schedule/`) and absolute URLs are both accepted.  
There is no SDK helper class for this effect — construct it directly with `Effect(type=EffectType.REDIRECT_CONTEXT, payload=json.dumps({"url": ...}))` as shown in the example above.

---

# Testing Utilities

Source: https://docs.canvasmedical.com/sdk/testing-utils/

Canvas SDK provides a streamlined testing environment and local database support to help developers test their plugins with real data.
This guide covers two key capabilities:
  1. Plugin testing with pytest — `canvas[test-utils]` introduces a set of tools and dependencies for writing database-backed tests.
  2. Database seeding in CLI — populate or reset your local database when running plugins locally.
* * *
##  Project Structure 
The recommended layout for plugin development is now scaffolded automatically by the `canvas init` command. This structure ensures compatibility with Canvas testing tools and CLI features, and it's strongly encouraged for all new plugin projects. We also recommend to use [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for managing dependencies.
    ```bash
    plugin-folder/
    ├── my_plugin/
    │   └── ...
    ├── tests/
    │   ├── __init__.py
    │   └── test_example.py
    └── pyproject.toml
    ```
##  Plugin Testing with Pytest 
Installing the `test-utils` extra provides everything needed to test plugins with pytest.
###  Features 
  - `pytest` with `factoryboy` style fixtures
  - Each test is wrapped in a transaction and rolled back automatically.
  - Use actual models or prebuilt factories to generate test data.
  - No need for mocks or fake database layers.
###  Installation 
Add the following to your `pyproject.toml`:
    ```toml
    [project]
    name = "canvas-plugins"
    version = "0.1.0"
    requires-python = ">=3.11,<3.13"
    dependencies = [
        "canvas[test-utils]",
        # other dependencies...
    ]
    ```
or install directly via `uv`:
    ```bash
    uv add "canvas[test-utils]"
    ```
You can now run your test suite using:
    ```bash
    uv run pytest
    ```
###  Using Factories 
Factories simplify test data creation and follow the [`factory_boy`](https://factoryboy.readthedocs.io/en/stable/) pattern.
    ```python
    from canvas_sdk.test_utils.factories import PatientFactory
    def test_factory() -> None:
        patient = PatientFactory.create()
        assert patient.id is not None
    ```
###  Using Models Directly 
You can also create records manually using the model classes:
    ```python
    from canvas_sdk.v1.data.discount import Discount
    def test_model() -> None:
        Discount.objects.create(
            name="10%",
            adjustment_group="30",
            adjustment_code="CO",
            discount=0.10,
        )
        assert Discount.objects.first().pk is not None
    ```
> Whether using a factory or model directly, your test will run inside a transaction and automatically roll back at the end.
###  Available Factories 
All factories are available from:
    ```python
    from canvas_sdk.test_utils import factories
    ```
Developers are encouraged to add new factories for their own models, and to submit PRs with contributions.
At this time, Canvas has factory support for the following models:
  - Claim
  - Claim Diagnosis Code
  - Facility
  - Medication History
  - Note
  - Organization
  - Patient
  - PracticeLocation
  - ProtocolCurrent
  - Staff
  - User
A complete list of available factories is located [here](https://github.com/canvas-medical/canvas-plugins/tree/main/canvas_sdk/test_utils/factories).
##  Local DB Seeding via `run-plugin`
You can run plugins locally with full access to the database using the CLI. Two options are available:
Option| Description  
---|---  
`--db-seed-file`| Path to a Python file that populates your database. _Warning_ : It resets the database before running the seed file.  
`--reset-db`| Clears and recreates the database before running the plugin  
###  Seed the Database 
To seed your plugin's database with test data:
    ```bash
    canvas run-plugin my_plugin --db-seed-file ./seed.py
    ```
Example `seed.py`:
    ```python
    from canvas_sdk.test_utils.factories import PatientFactory
    from canvas_sdk.v1.data.discount import Discount
    PatientFactory.create(first_name="Seeded", last_name="Patient")
    Discount.objects.create(
        name="20%",
        adjustment_group="X",
        adjustment_code="Y",
        discount=0.20
    )
    ```
###  Reset the Database 
To reset the database before running a plugin:
    ```bash
    canvas run-plugin my_plugin --reset-db
    ```
This will remove the existing database (if present) and recreate a clean version.
###  Simulate Events 
After your database is set up, simulate incoming events with:
    ```bash
    canvas emit
    ```
Run `canvas emit --help` for more info.

---

# Utils

Source: https://docs.canvasmedical.com/sdk/utils/

##  Making requests with Http 
The Canvas SDK offers a helper class for completing HTTP calls.
    ```python
    from canvas_sdk.utils import Http
    http = Http()
    ```
###  get 
Sends a GET request.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`url`|  _string_| `true`| The url of the request.  
`headers`|  _dict_| `false`| The headers to include in the request.  
**Example** :
    ```python
    from canvas_sdk.utils import Http
    http = Http()
    http.get("https://my-url.com/", headers={"Authorization": f"Bearer token"})
    ```
###  post 
Sends a POST request.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`url`|  _string_| `true`| The url of the request.  
`headers`|  _dict_| `false`| The headers to include in the request.  
`json`|  _dict_| `false`| The json to include in the request.  
`data`|  _dict_ or _string_| `false`| The data to include in the request.  
**Example** :
    ```python
    from canvas_sdk.utils import Http
    http = Http()
    http.post(
        "https://my-url.com/",
        headers={"Authorization": f"Bearer token"},
        json={"post": "json"},
        data="this-is-my-data"
    )
    ```
###  put 
Sends a PUT request.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`url`|  _string_| `true`| The url of the request.  
`headers`|  _dict_| `false`| The headers to include in the request.  
`json`|  _dict_| `false`| The json to include in the request.  
`data`|  _dict_ or _string_| `false`| The data to include in the request.  
**Example** :
    ```python
    from canvas_sdk.utils import Http
    http = Http()
    http.put(
        "https://my-url.com/",
        headers={"Authorization": f"Bearer token"},
        json={"put": "json"},
        data="this-is-my-data"
    )
    ```
###  patch 
Sends a PATCH request.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`url`|  _string_| `true`| The url of the request.  
`headers`|  _dict_| `false`| The headers to include in the request.  
`json`|  _dict_| `false`| The json to include in the request.  
`data`|  _dict_ or _string_| `false`| The data to include in the request.  
**Example** :
    ```python
    from canvas_sdk.utils import Http
    http = Http()
    http.patch(
        "https://my-url.com/",
        headers={"Authorization": f"Bearer token"},
        json={"patch": "json"},
        data="this-is-my-data"
    )
    ```
##  Making concurrent requests with Http 
There is an interface for executing HTTP requests in parallel.
The `batch_requests` method will execute the requests in parallel using multithreading, and return once all the requests have completed.
The first parameter to the method is an iterable of `BatchableRequest` objects. These can be created with the following helper functions:
    batch_get
    batch_post
    batch_put
    batch_patch
The parameters that these helper functions accept match what the corresponding single-request methods accept.
The `timeout` parameter allows for specifying a timeout value in seconds; if a request has not completed before the timeout value, an error will be returned for that request. The maximum allowed value for `timeout` is 30 seconds. If `timeout` is not specified, it will be set to the maximum value.
The return value will be a list of responses to the requests. The order of the return value will correspond to the order of the provided requests.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`batch_requests`|  _Iterable[BatchableRequest]_| `true`| The list of batched requests.  
`timeout`|  _integer_| `false`| The timeout value in seconds.  
**Example** :
    ```python
    from canvas_sdk.utils import Http, batch_get, batch_post, batch_put, batch_patch
    http = Http()
    requests = [
        batch_get("https://my-url.com/", headers={"Authorization": f"Bearer token"}),
        batch_post("https://my-url.com/", headers={"Authorization": f"Bearer token"}, json={"post": "json"}),
        batch_put("https://my-url.com/", headers={"Authorization": f"Bearer token"}, data="this-is-my-data"),
        batch_patch("https://my-url.com/", headers={"Authorization": f"Bearer token"}, json={"patch": "json"})
    ]
    responses = http.batch_requests(requests, timeout=10)
    ```
##  Generating PDFs 
Plugin authors can generate PDFs using the `pdf_generator` client. There are two approaches: generating from a URL that serves HTML, or generating directly from an HTML string. Both methods upload the resulting PDF to S3 and return a presigned URL.
    ```python
    from canvas_sdk.utils.pdf import pdf_generator
    ```
The client exposes only `from_url` and `from_html`. Direct HTTP methods (get, post, put, patch) are not available.
###  from_url 
Generates a PDF from a URL that returns HTML. The service fetches the HTML from the given URL, converts it to PDF, uploads it to S3, and returns a presigned URL.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`print_url`|  _string_| `true`| The path to the HTML endpoint.  
`auth`|  _PdfAuthRequest_| `false`| Credentials forwarded to the PDF service so it can fetch authenticated endpoints.  
**Returns** : `PdfUrlResponse | None` — `None` if PDF generation failed.
When using `from_url`, the PDF service fetches the HTML from your endpoint directly. If that endpoint requires authentication, the SimpleAPI serving the HTML should use [`BasicAuthMixin`](/sdk/handlers-simple-api-http/#authentication-mixins) and pass the credentials via `PdfAuthRequest`.
**Example** :
    ```python
    from canvas_sdk.utils.pdf import PdfAuthRequest, pdf_generator
    # The PDF service will fetch this endpoint to get the HTML.
    # Because the endpoint uses BasicAuthMixin, we pass credentials
    # so the service can authenticate on our behalf.
    auth = PdfAuthRequest(
        username="user",
        password="password",
    )
    response = pdf_generator.from_url(
        print_url="plugin-io/api/my_plugin/printout/html?note_uuid=abc-123",
        auth=auth,
    )
    if response and response.url:
        # response.url is a presigned S3 URL to the generated PDF
        pdf_url = response.url
    ```
###  from_html 
Generates a PDF from a raw HTML string. Use this when you already have the HTML content and don't need the service to fetch it from a URL.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`content`|  _string_| `true`| The HTML content to convert.  
**Returns** : `PdfUrlResponse | None` — `None` if PDF generation failed.
**Example** :
    ```python
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.utils.pdf import pdf_generator
    html = render_to_string("templates/note_printout.html", {
        "patient_name": "Jane Doe",
        "note_type": "Office Visit",
    })
    response = pdf_generator.from_html(content=html)
    if response and response.url:
        pdf_url = response.url
    ```
###  PdfUrlResponse 
Both methods return a `PdfUrlResponse` on success, or `None` on failure.
Attribute| Type| Description  
---|---|---  
`url`|  _string_|  Presigned S3 URL to the generated PDF.  
###  Choosing between the two methods 
Use case| Method  
---|---  
Plugin serves an HTML page via SimpleAPI that requires authentication| `from_url` with `PdfAuthRequest`  
You already have the HTML string in memory (e.g. from `render_to_string`)| `from_html`  
##  Sanitizing untrusted HTML 
Content that comes from a patient or an integration, such as a patient portal message or a `POST /Communication` request, can contain HTML. If a plugin renders that HTML as-is, any script in it runs in the session of the staff member who views the page. Escaping the content prevents that, but it also shows formatting that staff wrote, such as bold text or lists, as literal tags.
`sanitize_html` keeps a small set of formatting markup and removes everything else. Use it whenever you render HTML from an untrusted source.
    ```python
    from canvas_sdk.utils.html import sanitize_html
    untrusted = '<p onclick="alert(1)">Can I refill <b>my</b> prescription?</p><script>alert(1)</script>'
    safe = sanitize_html(untrusted)
    # '<p>Can I refill <b>my</b> prescription?</p>'
    ```
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`value`|  _string_| `true`| The HTML to sanitize.  
**Returns** : `str` — the sanitized HTML.
The sanitizer keeps:
  - The tags `p`, `br`, `b`, `strong`, `i`, `em`, `u`, `ul`, `ol`, `li`, `a`, `span`, and `div`.
  - The `href` attribute on `a` tags, when the URL uses the `http`, `https`, or `mailto` scheme. Every link also gets `rel="noopener noreferrer"`.
The sanitizer removes:
  - All other tags and attributes, including `style`, `class`, `id`, `title`, and event handlers such as `onclick`.
  - Comments, and the contents of `script` and `style` tags.
  - Link URLs that use any other scheme, such as `javascript:`, `data:`, or `vbscript:`. The link text stays.
Text is HTML-escaped, so `5 < 6` becomes `5 &lt; 6`.
###  Using the template filter 
In templates rendered with [`render_to_string`](/sdk/layout-effect/#custom-html-and-django-templates), use the builtin `sanitize_html` filter. You don't need a `{% load %}` tag.
    ```html
    <span class="message-text-content">{{ msg.text|sanitize_html }}</span>
    ```
The filter marks its output as safe, so don't add `|safe`. A `None` value renders as an empty string.
For the other rules on rendering untrusted data in templates, such as passing data to JavaScript, see [Rendering untrusted data safely](/sdk/layout-effect/#rendering-untrusted-data-safely).
##  Making requests to the Ontologies service 
Plugin authors can make requests to our Ontologies service using the `ontologies_http` wrapper.
In addition to the `json()` method of the response, which you'll use to access the response itself, you can also access the `status_code` to verify that the request was succcessful.
> **Use these endpoints for chart-parity lookups.** The medication and allergen search endpoints below back the autocompletes providers use in the chart. Use them — not the FHIR `/Medication` or `/Allergen` search endpoints — when you need a code that will resolve when used in a command. FHIR `/Medication` and `/Allergen` search different, narrower interoperability catalogs and can return codes the chart can't resolve (or omit ones it can); a code returned by the endpoints below resolves consistently with what the picker shows.
> **Tip:** The Medical Software Foundation's [`coding_lookup`](https://github.com/Medical-Software-Foundation/canvas/tree/main/data-migrations/data_migrations/plugins/coding_lookup) reference plugin wraps the medication and allergen lookups below as ready-made SimpleAPI endpoints (`/medication_search`, `/allergy_search`) returning a clean `{count, results}` shape. Install it as-is, or use it as a template for calling `ontologies_http` from your own plugin.
###  Searching for medications 
Plugin authors can search for medications by NDC code, RxNorm RXCUI, FDB code, or full-text search.
####  `fdb_code`
Elsewhere in the SDK there are commands that take an `fdb_code` or `new_fdb_code`, some examples being [`AdjustPrescriptionCommand`](/sdk/commands/#adjustprescription), [`MedicationStatementCommand`](/sdk/commands/#medicationstatement), [`PrescribeCommand`](/sdk/commands/#prescribe), and [`RefillCommand`](/sdk/commands/#refill). The value to be sent as the `fdb_code` is returned in the search payloads below as the `med_medication_id`.
####  `GET /fdb/grouped-medication/` — text and RxNorm search 
**Used by:** [Prescribe](/sdk/commands/#prescribe), [MedicationStatement](/sdk/commands/#medicationstatement), and [Refill](/sdk/commands/#refill) (`fdb_code`), and [Adjust Prescription](/sdk/commands/#adjustprescription) (`new_fdb_code`).
Search the medication catalog by full-text query or exact RxNorm RXCUI. Query parameters:
Parameter| Type| Description  
---|---|---  
`search`| string| Full-text search over the medication name, description, and synonyms.  
`rxnorm_rxcui`| string or int| Match a specific RxNorm RXCUI.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    # full-text search of the medication name, description, and synonyms
    response_json = ontologies_http.get_json(
        f"/fdb/grouped-medication/?{urlencode({'search': 'tylenol'})}"
    ).json()
    # search by a specific RxNorm RXCUI (same response shape)
    response_json = ontologies_http.get_json(
        f"/fdb/grouped-medication/?{urlencode({'rxnorm_rxcui': 313782})}"
    ).json()
    ```
The response contains a `results` list; each entry looks like:
    ```json
    {
      "results": [
        {
          "description_and_quantity": "Athenol 325 mg tablet",
          "med_medication_id": 436095,
          "search_rank": 0.082745634,
          "search_terms": "Athenol 325 mg tablet|ACETAMINOPHEN ORAL|...|TYLENOL|...",
          "med_medication_description": "Athenol 325 mg tablet",
          "clinical_quantities": [
            {
              "erx_quantity": "1.0000000",
              "representative_ndc": "11822317640",
              "clinical_quantity_description": "tablet",
              "erx_ncpdp_script_quantity_qualifier_code": "C48542",
              "erx_ncpdp_script_quantity_qualifier_description": "Tablet"
            }
          ],
          "etc_path_id": [3645, 574, 578, 577],
          "etc_path_name": [
            "Analgesic, Anti-inflammatory or Antipyretic",
            "Analgesic, Anti-inflammatory or Antipyretic - Non-Opioid",
            "Analgesic or Antipyretic Non-Opioid and Combinations",
            "Analgesic or Antipyretic Non-Opioid"
          ],
          "rxnorm_rxcui": "313782"
        }
      ]
    }
    ```
Each result's `clinical_quantities` array supplies the values for a [`ClinicalQuantity`](/sdk/commands/#clinicalquantity) on prescribe commands — `representative_ndc`, `erx_ncpdp_script_quantity_qualifier_code` → `ncpdp_quantity_qualifier_code`, and `clinical_quantity_description` → `description`.
####  `GET /fdb/grouped-medication/{med_medication_id}/` — look up by FDB code 
Fetch one or more medications by FDB code. Pass a single `med_medication_id`, or a comma-separated list of ids, as the path segment.
Parameter| Type| Description  
---|---|---  
`med_medication_id` (path)| int, or comma-separated ints| One or more FDB medication ids.  
    ```python
    from canvas_sdk.utils.http import ontologies_http
    # single FDB code
    response_json = ontologies_http.get_json("/fdb/grouped-medication/123456/").json()
    # multiple FDB codes
    med_medication_ids = ["123456", "123457"]
    response_json = ontologies_http.get_json(
        f"/fdb/grouped-medication/{','.join(med_medication_ids)}/"
    ).json()
    ```
Returns the same full `results` shape as the text/RxNorm search above — each entry includes every field, including `clinical_quantities`:
    ```json
    {
      "results": [
        {
          "description_and_quantity": "Athenol 325 mg tablet",
          "med_medication_id": 123456,
          "search_terms": "Athenol 325 mg tablet|ACETAMINOPHEN ORAL|...|TYLENOL|...",
          "med_medication_description": "Athenol 325 mg tablet",
          "clinical_quantities": [
            {
              "erx_quantity": "1.0000000",
              "representative_ndc": "11822317640",
              "clinical_quantity_description": "tablet",
              "erx_ncpdp_script_quantity_qualifier_code": "C48542",
              "erx_ncpdp_script_quantity_qualifier_description": "Tablet"
            }
          ],
          "etc_path_id": [3645, 574, 578, 577],
          "etc_path_name": [
            "Analgesic, Anti-inflammatory or Antipyretic",
            "Analgesic, Anti-inflammatory or Antipyretic - Non-Opioid",
            "Analgesic or Antipyretic Non-Opioid and Combinations",
            "Analgesic or Antipyretic Non-Opioid"
          ],
          "rxnorm_rxcui": "313782"
        }
      ]
    }
    ```
####  `GET /fdb/ndc-to-medication/{ndc}/` — look up by NDC 
Resolve a single NDC to its medication.
Parameter| Type| Description  
---|---|---  
`ndc` (path)| string| The NDC to resolve.  
    ```python
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json("/fdb/ndc-to-medication/76420037215/").json()
    ```
The response is a single medication object:
    ```json
    {
      "description_and_quantity": "Aphen 325 mg tablet",
      "med_medication_id": 572345,
      "search_terms": "Aphen 325 mg tablet|APHEN 325 MG TABLET|ACETAMINOPHEN 325 MG TABLET",
      "med_medication_description": "Aphen 325 mg tablet",
      "clinical_quantities": [
        {
          "erx_quantity": "1.0000000",
          "representative_ndc": "76420037215",
          "clinical_quantity_description": "tablet",
          "erx_ncpdp_script_quantity_qualifier_code": "C48542",
          "erx_ncpdp_script_quantity_qualifier_description": "Tablet"
        }
      ],
      "etc_path_id": [3645, 574, 578, 577],
      "etc_path_name": [
        "Analgesic, Anti-inflammatory or Antipyretic",
        "Analgesic, Anti-inflammatory or Antipyretic - Non-Opioid",
        "Analgesic or Antipyretic Non-Opioid and Combinations",
        "Analgesic or Antipyretic Non-Opioid"
      ],
      "rxnorm_rxcui": "313782"
    }
    ```
####  `GET /fdb/ndcs-to-medications/{ndcs}/` — look up by multiple NDCs 
Resolve several NDCs at once. Pass a comma-separated list of NDCs as the path segment.
Parameter| Type| Description  
---|---|---  
`ndcs` (path)| comma-separated strings| The NDCs to resolve.  
    ```python
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json(
        "/fdb/ndcs-to-medications/76420037215,11822317640/"
    ).json()
    ```
The response is a dictionary keyed by NDC; each value is the full medication object (same shape as the single-NDC lookup above), including `clinical_quantities`:
    ```json
    {
      "76420037215": {
        "description_and_quantity": "Aphen 325 mg tablet",
        "med_medication_id": 572345,
        "search_terms": "Aphen 325 mg tablet|APHEN 325 MG TABLET|ACETAMINOPHEN 325 MG TABLET",
        "med_medication_description": "Aphen 325 mg tablet",
        "clinical_quantities": [
          {
            "erx_quantity": "1.0000000",
            "representative_ndc": "76420037215",
            "clinical_quantity_description": "tablet",
            "erx_ncpdp_script_quantity_qualifier_code": "C48542",
            "erx_ncpdp_script_quantity_qualifier_description": "Tablet"
          }
        ],
        "etc_path_id": [3645, 574, 578, 577],
        "etc_path_name": [
          "Analgesic, Anti-inflammatory or Antipyretic",
          "Analgesic, Anti-inflammatory or Antipyretic - Non-Opioid",
          "Analgesic or Antipyretic Non-Opioid and Combinations",
          "Analgesic or Antipyretic Non-Opioid"
        ],
        "rxnorm_rxcui": "313782"
      },
      "11822317640": {
        "description_and_quantity": "Athenol 325 mg tablet",
        "med_medication_id": 436095,
        "search_terms": "Athenol 325 mg tablet|ACETAMINOPHEN ORAL|...|TYLENOL|...",
        "med_medication_description": "Athenol 325 mg tablet",
        "clinical_quantities": [
          {
            "erx_quantity": "1.0000000",
            "representative_ndc": "11822317640",
            "clinical_quantity_description": "tablet",
            "erx_ncpdp_script_quantity_qualifier_code": "C48542",
            "erx_ncpdp_script_quantity_qualifier_description": "Tablet"
          }
        ],
        "etc_path_id": [3645, 574, 578, 577],
        "etc_path_name": [
          "Analgesic, Anti-inflammatory or Antipyretic",
          "Analgesic, Anti-inflammatory or Antipyretic - Non-Opioid",
          "Analgesic or Antipyretic Non-Opioid and Combinations",
          "Analgesic or Antipyretic Non-Opioid"
        ],
        "rxnorm_rxcui": "313782"
      }
    }
    ```
**Codes that resolve vs. free text.** A `med_medication_id` returned above resolves cleanly when passed as an `fdb_code` to a command. Some FDB entries — for example the `THSC …`-prefixed results the FHIR `/Medication` search can return — are not in this catalog and will render with a **blank medication name** if used. To record a historical or non-catalog medication as free text instead, pass a `Coding` with `system=CodeSystems.UNSTRUCTURED` (its `display` is used as-is) — see [MedicationStatement](/sdk/commands/#medicationstatement).
###  Searching for allergens 
Plugin authors can search the allergen catalog — the same catalog behind the chart's allergen autocomplete — by full-text or by RxNorm code.
####  `GET /fdb/allergy` — full-text search 
**Used by:** [Allergy](/sdk/commands/#allergy) (`allergy` — the allergen `concept_id` \+ `concept_type`).
Full-text search of the allergen catalog. Query parameters:
Parameter| Type| Description  
---|---|---  
`dam_allergen_concept_id_description__fts`| string| Full-text search over the allergen concept description.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json(
        f"/fdb/allergy?{urlencode({'dam_allergen_concept_id_description__fts': 'chocolate'})}"
    ).json()
    ```
The response contains a `results` list of allergen concepts:
    ```json
    {
      "results": [
        {
          "dam_allergen_concept_id": 19561,
          "dam_allergen_concept_id_description": "chocolate",
          "concept_type": "ingredient"
        }
      ]
    }
    ```
####  `GET /fdb/allergen` — RxNorm lookup 
Look up allergen concepts mapped to an external code. Query parameters:
Parameter| Type| Description  
---|---|---  
`code`| string| The external code to match, in `{system}\|{code}` form — e.g. `rxnorm\|217013`.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json(
        f"/fdb/allergen?{urlencode({'code': 'rxnorm|217013'})}"
    ).json()
    ```
Each result carries the FDB vocabulary type and id:
    ```json
    {
      "results": [
        {
          "evd_fdb_vocabulary_type_identifier": 104,
          "imk_fdb_vocabulary_no_identifier": 19561,
          "imk_fdb_vocabulary_description": "chocolate"
        }
      ]
    }
    ```
####  `GET /fdb/allergy/` — look up by concept id 
Resolve a specific allergen concept by id — for example, to confirm a stored allergy. Query parameters:
Parameter| Type| Description  
---|---|---  
`dam_allergen_concept_id`| int| The FDB allergen concept id.  
`dam_allergen_concept_id_type`| int| The allergen category — `1` (allergy group), `2` (medication), or `6` (ingredient).  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json(
        f"/fdb/allergy/?{urlencode({'dam_allergen_concept_id': 19561, 'dam_allergen_concept_id_type': 6})}"
    ).json()
    ```
Returns a `results` list containing the matching allergen concept (same fields as the full-text search above):
    ```json
    {
      "results": [
        {
          "dam_allergen_concept_id": 19561,
          "dam_allergen_concept_id_description": "chocolate",
          "concept_type": "ingredient"
        }
      ]
    }
    ```
####  Mapping results to `AllergyCommand`
To record one of these on a patient, pass the concept id and its type to [`AllergyCommand`](/sdk/commands/#allergy) as `concept_id` and `concept_type`. The catalog's allergen type maps to the command's category as follows:
Allergen type| `concept_type` (text search)| FDB vocabulary type (RxNorm search)| `AllergyCommand` category  
---|---|---|---  
Allergy group| `allergy group`| `110`| `1`  
Medication| `medication`| `1`| `2`  
Ingredient| `ingredient`| `104`| `6`  
For example, an allergy to chocolate is ingredient concept `19561` → category `6`.
###  Looking up clinical codes 
Beyond medications and allergens, the ontologies service resolves coded concepts that back several commands — ICD-10 conditions and CVX immunizations. (SNOMED concept searches are under Searching clinical concepts.)
####  `GET /icd/condition/` — ICD-10 conditions 
**Used by:** [Diagnose](/sdk/commands/#diagnose) (`icd10_code`), [Assess](/sdk/commands/#assess) (`icd10_code`), [Medical History](/sdk/commands/#medicalhistory) (`past_medical_history`), and the `diagnosis_codes` fields on [Refer](/sdk/commands/#refer), [Imaging Order](/sdk/commands/#imagingorder), and other diagnosis-code commands. _(Prescribe/Refill`icd10_codes` come from the patient's active conditions, not this search.)_
Search ICD-10 conditions by text, or resolve a specific code. This backs the condition/diagnosis autocompletes on commands such as [Diagnose](/sdk/commands/#diagnose), [Assess](/sdk/commands/#assess), and [Medical History](/sdk/commands/#medicalhistory). Query parameters:
Parameter| Type| Description  
---|---|---  
`search`| string| Full-text search over ICD-10 conditions.  
`icd10_code`| string| Resolve an exact ICD-10 code instead of searching. Dots optional (`E119` / `E11.9`).  
`date`| string| Optional. `YYYY-MM-DD`; resolves codes as of that date.  
`limit`| int| Optional. Maximum number of results.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    # full-text search
    response_json = ontologies_http.get_json(
        f"/icd/condition/?{urlencode({'search': 'type 2 diabetes'})}"
    ).json()
    # resolve a specific code
    response_json = ontologies_http.get_json(
        f"/icd/condition/?{urlencode({'icd10_code': 'E119'})}"
    ).json()
    ```
Returns a `results` list of matching conditions:
    ```json
    {
      "results": [
        {
          "icd10_code": "E11.9",
          "icd10_text": "Type 2 diabetes mellitus without complications",
          "snomed_concept_id": "44054006",
          "preferred_snomed_term": "Type 2 diabetes mellitus"
        }
      ]
    }
    ```
####  `GET /cpt/immunization/` — search immunizations 
**Used by:** [Immunization Statement](/sdk/commands/#immunizationstatement) (`cvx_code` / `cpt_code`).
Search vaccines by name or code. Query parameters:
Parameter| Type| Description  
---|---|---  
`name_or_code`| string| A vaccine code, or a text fragment of its name.  
`cvx_code`| string| Optional. Filter to a specific CVX code.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json(
        f"/cpt/immunization/?{urlencode({'name_or_code': 'influenza'})}"
    ).json()
    ```
The response contains a `results` list of matching vaccines:
    ```json
    {
      "results": [
        {
          "medium_name": "influenza, injectable, quadrivalent",
          "cpt_code": "90686",
          "cvx_code": "150",
          "cvx_description": "Influenza, injectable, quadrivalent"
        }
      ]
    }
    ```
###  Searching clinical concepts 
These endpoints back the concept autocompletes on several commands. Each returns a `results` list of matching concepts.
####  `GET /snomed/family-history/` — family-history conditions 
**Used by:** [Family History](/sdk/commands/#familyhistory) (`family_history`).
Search SNOMED family-history conditions.
Parameter| Type| Description  
---|---|---  
`search`| string| Full-text search over family-history conditions.  
`limit`| int| Optional. Maximum number of results.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json(
        f"/snomed/family-history/?{urlencode({'search': 'diabetes'})}"
    ).json()
    ```
The response contains a `results` list of SNOMED concepts:
    ```json
    {
      "results": [
        {
          "concept_id": "73211009",
          "term": "Diabetes mellitus"
        }
      ]
    }
    ```
####  `GET /snomed/family-relation/` — family relationships 
**Used by:** [Family History](/sdk/commands/#familyhistory) (`relative`).
Search SNOMED family relationships (mother, father, sibling, …).
Parameter| Type| Description  
---|---|---  
`term__icontains`| string| Case-insensitive substring match on the relationship term.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json(
        f"/snomed/family-relation/?{urlencode({'term__icontains': 'mother'})}"
    ).json()
    ```
The response contains a `results` list of SNOMED concepts:
    ```json
    {
      "results": [
        {
          "concept_id": "72705000",
          "term": "Mother"
        }
      ]
    }
    ```
####  `GET /snomed/instruction/` — instructions 
**Used by:** [Instruct](/sdk/commands/#instruct) (`coding`).
Search SNOMED instructions.
Parameter| Type| Description  
---|---|---  
`term__icontains`| string| Case-insensitive substring match on the instruction term.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json(
        f"/snomed/instruction/?{urlencode({'term__icontains': 'physical therapy'})}"
    ).json()
    ```
The response contains a `results` list of SNOMED concepts:
    ```json
    {
      "results": [
        {
          "concept_id": "229065009",
          "term": "Physical therapy"
        }
      ]
    }
    ```
####  `GET /snomed/procedures/` — surgical-history procedures 
**Used by:** [Surgical History](/sdk/commands/#surgicalhistory) (`past_surgical_history`).
Search SNOMED procedures.
Parameter| Type| Description  
---|---|---  
`search`| string| Full-text search over procedures.  
`limit`| int| Optional. Maximum number of results.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    response_json = ontologies_http.get_json(
        f"/snomed/procedures/?{urlencode({'search': 'appendectomy'})}"
    ).json()
    ```
The response contains a `results` list of SNOMED concepts:
    ```json
    {
      "results": [
        {
          "concept_id": "80146002",
          "term": "Appendectomy"
        }
      ]
    }
    ```
###  Screening for drug–allergy interactions 
**Used by:** the [Prescribe](/sdk/commands/#prescribe) safety screening; also callable directly from a plugin (it is not tied to a command field).
> **Info:** Canvas runs this screening automatically on staged medication commands in the UI and displays the results to the provider. If you are using the SDK to automate the charting of these commands, that interactive screening may not surface — you may want to run this check yourself.
Canvas's drug–allergy screening — the same FDB-backed check the chart runs when a provider adds a medication — is available through `ontologies_http`.
`GET /fdb/medication-allergy/` takes a candidate medication and the patient's allergy list, both as JSON-encoded query parameters:
Parameter| Type| Description  
---|---|---  
`consideredMedication`| JSON string| The candidate drug's FDB codings as a flat list of `[code, "FDB"]` pairs, e.g. `[["217012", "FDB"]]`.  
`allergyList`| JSON string| The patient's allergies as `[code, category]` pairs, where `category` is the FDB allergen-concept type carried on the allergy record, e.g. `[["476", 1], ["1886", 6]]`.  
    ```python
    import json
    from urllib.parse import urlencode
    from canvas_sdk.commands.constants import CodeSystems
    from canvas_sdk.utils.http import ontologies_http
    from canvas_sdk.v1.data import Medication, Patient
    def fdb_codings(med: Medication) -> list[list[str]]:
        """The medication's FDB codings as [code, "FDB"] pairs."""
        return [
            [c.code, "FDB"]
            for c in med.codings.all()
            if c.code and c.system == CodeSystems.FDB
        ]
    def screen_medication_against_allergies(patient: Patient, considered_med: Medication) -> list[dict]:
        # Candidate medication: [[code, "FDB"], ...]
        considered_codings = fdb_codings(considered_med)
        # Patient's allergies: [[fdb_allergen_code, category], ...]
        allergy_ids = []
        for allergy in patient.allergy_intolerances.committed():
            fdb_coding = next(
                (c for c in allergy.codings.all() if c.code and c.system == CodeSystems.FDB),
                None,
            )
            if fdb_coding:
                allergy_ids.append([fdb_coding.code, allergy.category])
        if not considered_codings or not allergy_ids:
            return []  # nothing to screen → "all clear"
        params = urlencode(
            {
                "consideredMedication": json.dumps(considered_codings),
                "allergyList": json.dumps(allergy_ids),
            }
        )
        return ontologies_http.get_json(f"/fdb/medication-allergy/?{params}").json()
    ```
The response is a list of interaction objects — one per matched allergy, distinguishing a direct match from a cross-sensitive one (e.g. a penicillin allergy against a cephalosporin). An empty list `[]` means no interactions (all clear):
    ```json
    [
      {
        "drug": { "...": "full FDB medication payload" },
        "allergy_concept": {
          "dam_allergen_concept_id": 476,
          "dam_allergen_concept_id_type": 1,
          "dam_allergen_concept_id_description": "Penicillins"
        },
        "specific_ingredients": [],
        "cross_sensitive_ingredients": []
      }
    ]
    ```
###  Screening for drug–drug interactions 
**Used by:** the [Prescribe](/sdk/commands/#prescribe) safety screening; also callable directly from a plugin (it is not tied to a command field).
> **Info:** Canvas runs this screening automatically on staged medication commands in the UI and displays the results to the provider. If you are using the SDK to automate the charting of these commands, that interactive screening may not surface — you may want to run this check yourself.
The sibling `GET /fdb/medication-list-interaction/` endpoint checks a single candidate medication against the patient's existing medication list. It checks the candidate against each existing med — it does **not** check the existing meds against each other. Both inputs are JSON-encoded query parameters:
Parameter| Type| Description  
---|---|---  
`consideredMedication`| JSON string| The candidate drug's FDB codings as a flat list of `[code, "FDB"]` pairs, e.g. `[["217012", "FDB"]]`.  
`medicationList`| JSON string| The patient's existing meds as a list of per-drug coding lists — **one inner list per drug** , e.g. `[[["155744", "FDB"]], [["261266", "FDB"]]]`.  
> **Group`medicationList` one inner list per drug.** If you flatten it to one entry per coding row, a multi-coding drug can appear to interact with itself and produce false positives.
    ```python
    import json
    from urllib.parse import urlencode
    from canvas_sdk.commands.constants import CodeSystems
    from canvas_sdk.utils.http import ontologies_http
    from canvas_sdk.v1.data import Medication, Patient
    def fdb_codings(med: Medication) -> list[list[str]]:
        """The medication's FDB codings as [code, "FDB"] pairs."""
        return [
            [c.code, "FDB"]
            for c in med.codings.all()
            if c.code and c.system == CodeSystems.FDB
        ]
    def screen_drug_drug(patient: Patient, considered_med: Medication) -> list[dict]:
        considered_medication = fdb_codings(considered_med)
        # One inner list per existing drug; exclude the candidate itself.
        medication_list = [
            fdb_codings(med)
            for med in Medication.objects.for_patient(patient).active()
            if med.id != considered_med.id
        ]
        medication_list = [codings for codings in medication_list if codings]
        if not considered_medication or not medication_list:
            return []
        params = urlencode(
            {
                "consideredMedication": json.dumps(considered_medication),
                "medicationList": json.dumps(medication_list),
            }
        )
        return ontologies_http.get_json(
            f"/fdb/medication-list-interaction/?{params}"
        ).json()
    ```
The response is a list of interaction objects, one per interacting pair:
    ```json
    [
      {
        "existing_medication": 155744,
        "considered_medication": 217012,
        "existing_medication_description": "metformin 500 mg tablet",
        "severity": 2,
        "severity_text": "Severe Interaction: Action is required to reduce the risk of severe adverse interaction.",
        "monograph_text": ["Drug A / Drug B", "Clinical Effects: ...", "..."]
      }
    ]
    ```
`severity` uses FDB's DDIM scale — **lower number = more clinically significant** (the chart uses the same scale):
`severity`| Meaning  
---|---  
`1`| Contraindicated drug combination  
`2`| Severe interaction  
`3`| Moderate interaction  
`9`| Undetermined severity / alternative therapy  
**Screening several new medications at once:** checking each new med only against the patient's _current_ list misses interactions _between_ the new meds. Accumulate — after screening each new med, add it to the list you screen the next one against:
    ```python
    from canvas_sdk.v1.data import Medication, Patient
    patient = Patient.objects.get(id="e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b")
    new_meds = list(Medication.objects.none())  # the medications you're about to add
    existing = list(Medication.objects.for_patient(patient).active())
    for new_med in new_meds:
        # screen new_med against `existing`, then:
        existing.append(new_med)  # so the next new med is checked against it too
    ```
##  Making requests to the Pharmacy service 
Plugin authors can make requests to our Pharmacy service using the `PharmacyHttp` client. This client provides a simplified interface for searching pharmacies and retrieving pharmacy details.
    ```python
    from canvas_sdk.utils.http import pharmacy_http
    ```
Unlike the general Http client, PharmacyHttp only provides two specific methods for pharmacy operations. Direct HTTP methods (get, post, put, patch) are not available.
###  Searching for pharmacies 
Search for pharmacies using full-text search, specific field filters, or location-based ordering.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`search_term`|  _string_| `false`| Full-text search across name, address, city, state, zip, and NCPDP ID.  
`latitude`|  _string_| `false`| Latitude coordinate for location-based ordering.  
`longitude`|  _string_| `false`| Longitude coordinate for location-based ordering.  
`id`|  _integer_| `false`| Exact pharmacy ID match.  
`ncpdp_id`|  _string_| `false`| Exact NCPDP ID match.  
`organization_name`|  _string_| `false`| Case-insensitive contains match on organization name.  
`specialty_type`|  _string_| `false`| Case-insensitive contains match on specialty type (e.g. "Retail").  
`state`|  _string_| `false`| Case-insensitive exact match on state (e.g. "NY").  
`zip_code_prefix`|  _string_| `false`| One or more comma-separated zip code prefixes (e.g. "100,902").  
**Example** :
    ```python
    from canvas_sdk.utils.http import pharmacy_http
    # Full-text search by name
    results = pharmacy_http.search_pharmacies("CVS")
    # Search with location-based ordering
    results = pharmacy_http.search_pharmacies(
        "pharmacy",
        latitude="40.7128",
        longitude="-74.0060"
    )
    # Filter by state and specialty type
    results = pharmacy_http.search_pharmacies(state="NY", specialty_type="Retail")
    # Filter by zip code prefixes
    results = pharmacy_http.search_pharmacies(zip_code_prefix="100,902")
    # Look up by exact NCPDP ID
    results = pharmacy_http.search_pharmacies(ncpdp_id="1234567")
    # The results list contains pharmacy objects like:
    # [
    #   {
    #     "id": 123456,
    #     "distance_miles": 0.8,
    #     "ncpdp_id": "1234567",
    #     "store_number": "#1234",
    #     "organization_name": "CVS Pharmacy #1234",
    #     "address_line_1": "123 MAIN ST",
    #     "address_line_2": "",
    #     "city": "New York",
    #     "state": "NY",
    #     "zip_code": "10001",
    #     "phone_primary": "2125551234",
    #     "fax": "2125555678",
    #     "latitude": 40.7128,
    #     "longitude": -74.0060,
    #     "npi": "1234567890",
    #     "specialty_type": "Retail",
    #     ...
    #   },
    #   ...
    # ]
    ```
###  Looking up a pharmacy by NCPDP ID 
Retrieve detailed information about a specific pharmacy using its NCPDP (National Council for Prescription Drug Programs) identifier.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`ncpdp_id`|  _string_| `true`| The NCPDP identifier of the pharmacy.  
**Example** :
    ```python
    from canvas_sdk.utils.http import pharmacy_http
    # Look up a specific pharmacy
    pharmacy = pharmacy_http.get_pharmacy_by_ncpdp_id("1234567")
    # The response contains detailed pharmacy information:
    # {
    #   "id": 123456,
    #   "ncpdp_id": "1234567",
    #   "store_number": "#1234",
    #   "organization_name": "Example Pharmacy #1234",
    #   "address_line_1": "123 MAIN ST",
    #   "address_line_2": "",
    #   "city": "New York",
    #   "state": "NY",
    #   "zip_code": "10001",
    #   "country": "US",
    #   "standardized_address_line_1": "123 Main St",
    #   "standardized_city": "New York",
    #   "standardized_state": "NY",
    #   "standardized_zip_code": "100010000",
    #   "phone_primary": "2125551234",
    #   "fax": "2125555678",
    #   "email": "",
    #   "active_start_time": "2020-01-01T00:00:00Z",
    #   "active_end_time": "2099-12-31T23:59:59Z",
    #   "service_level": "New~Refill~Change~Cancel~ControlledSubstance",
    #   "npi": "1234567890",
    #   "specialty_type": "Retail",
    #   "dea_number": "",
    #   "organization_type": "Pharmacy",
    #   "organization_id": 1234567,
    #   "latitude": 40.7128,
    #   "longitude": -74.0060,
    #   ...
    # }
    ```
###  Response fields 
Both methods return pharmacy objects with the following key fields:
  - `ncpdp_id`: Unique NCPDP identifier for the pharmacy
  - `organization_name`: Name of the pharmacy
  - `address_line_1`, `address_line_2`, `city`, `state`, `zip_code`: Physical address
  - `phone_primary`: Primary phone number
  - `fax`: Fax number
  - `npi`: National Provider Identifier
  - `specialty_type`: Type of pharmacy (e.g., "Retail", "Mail Order")
  - `service_level`: Services available (e.g., "New~Refill~Change~Cancel~ControlledSubstance")
  - `latitude`, `longitude`: Geographic coordinates
  - `distance_miles`: Distance from search location (only present in search results when location is provided)
##  Making requests to the Science service 
Plugin authors can make requests to our Science service using the `science_http` wrapper. The Science service backs autocomplete behavior in the Canvas note UI for imaging order codes (via parse templates) and for imaging centers and other clinical contacts.
    ```python
    from canvas_sdk.utils.http import science_http
    ```
Like `ontologies_http` and `pharmacy_http`, `science_http` is a JSON-only client. You can call `get_json()` and access the response with `json()` and `status_code`. Direct `get`/`post`/`put`/`patch` methods are not available.
###  Searching for imaging codes 
Use this to populate the `image_code` field of [`ImagingOrderCommand`](/sdk/commands/#imagingorder). `GET /parse-templates/imaging-reports/` accepts these query parameters:
Parameter| Type| Description  
---|---|---  
`query`| string| Full-text search over imaging report templates.  
`format`| string| Response format; pass `json`.  
`limit`| int| Maximum number of results to return.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import science_http
    params = {"query": "chest x-ray", "format": "json", "limit": 10}
    response_json = science_http.get_json(f"/parse-templates/imaging-reports/?{urlencode(params)}").json()
    ```
The response contains a `results` list of imaging report templates:
    ```json
    {
      "results": [
        {
          "code": "71046",
          "name": "X-ray of chest, 2 views",
          "code_system": "CPT"
        }
      ]
    }
    ```
Use the returned `code` on the command:
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.commands import ImagingOrderCommand
    from canvas_sdk.utils.http import science_http
    params = {"query": "chest x-ray", "format": "json", "limit": 10}
    response_json = science_http.get_json(f"/parse-templates/imaging-reports/?{urlencode(params)}").json()
    command = ImagingOrderCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        image_code=response_json["results"][0]["code"],
        diagnosis_codes=["R05"],
    )
    ```
###  Searching for contacts and service providers 
`GET /contacts/` searches the external contact directory — referring providers, specialists, imaging centers, and other service providers. Use it to populate a `ServiceProvider` on commands such as [Refer](/sdk/commands/#refer) and [Imaging Order](/sdk/commands/#imagingorder), to add external care-team members, or to look up a fax number for outbound faxing. Imaging centers are just contacts with a radiology job title — filter for them with `job_title__icontains=radiology`.
Query parameters (all optional; combine as needed):
Parameter| Type| Description  
---|---|---  
`search` (or `query`)| string| Full-text search over first/last name, practice name, job title, business address, phone, and fax.  
`job_title__icontains`| string| Filter by job-title substring — pass `radiology` to limit results to imaging centers.  
`business_postal_code__in`| string| Comma-separated ZIP codes to bias toward local results.  
`first_name__icontains`, `last_name__icontains`| string| Filter by contact name.  
`practice_name__icontains`| string| Filter by practice name.  
`business_fax__icontains`, `business_fax`| string| Filter by fax number (substring, or exact match).  
`format`| string| Response format; pass `json`.  
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import science_http
    # General service-provider search (e.g. for a referral)
    params = {"search": "cardiology", "format": "json"}
    response_json = science_http.get_json(f"/contacts/?{urlencode(params)}").json()
    # Imaging centers: narrow to a radiology job title
    params = {
        "search": "advanced imaging",
        "job_title__icontains": "radiology",
        "format": "json",
        # Optional location filter:
        # "business_postal_code__in": "10001,10002",
    }
    response_json = science_http.get_json(f"/contacts/?{urlencode(params)}").json()
    ```
The response contains a `results` list of contact objects:
    ```json
    {
      "results": [
        {
          "firstName": "...",
          "lastName": "...",
          "practiceName": "Advanced Imaging Center",
          "specialty": "Radiology",
          "businessPhone": "2125551234",
          "businessFax": "2125555678",
          "businessAddress": "123 Main St, New York, NY 10001",
          "notes": "..."
        }
      ]
    }
    ```
Pass a selected contact as the `service_provider` on [Refer](/sdk/commands/#refer), [Imaging Order](/sdk/commands/#imagingorder), or other commands that accept a `ServiceProvider`; its `businessFax` and `businessAddress` also drive outbound faxing.
##  Getting a patient portal login link 
Plugin authors can mint a patient's portal login link using `patient_portal_http`, then deliver portal invites and password resets over their own transport (their own SMS or email provider) instead of letting Canvas send them. To have Canvas send the invite for you instead, use [Send Invite](/sdk/patient-portal/#send-invite).
    ```python
    from canvas_sdk.utils.patient_portal import PatientPortalLinkError, patient_portal_http
    ```
Unlike the other service clients, `patient_portal_http` is imported from its own `canvas_sdk.utils.patient_portal` module, and it exposes only `get_login_url`.
###  get_login_url 
Mints a login link for a patient and returns it as a string.
**Parameters** :
Name| Type| Required| Description  
---|---|---|---  
`patient_id`|  _string_| `true`| The `id` of the [Patient](/sdk/data-patient/#patient).  
`link_type`| `"invite"` or `"reset"`| `false`| Defaults to `"invite"`. Both return the same link: when it is opened, the portal shows account activation or password reset based on whether the patient has already registered. Read `is_portal_registered` on the [CanvasUser](/sdk/data-canvasuser) data module to choose the copy of the message you send.  
`next_path`|  _string_| `false`| Where in the portal to land the patient, up to 50 characters. Defaults to `"/"`. A path that leaves the portal is rejected. See `next_path` destinations.  
`ttl`|  _integer_| `false`| The link's lifetime, in seconds, from `1` to `86400` (24 hours). A value outside that range raises `PatientPortalLinkError`. Omit it to use the instance's own default, described below.  
####  `next_path` destinations 
Path| Lands the patient on  
---|---  
`/`| The portal landing page.  
`/appointments`| Appointments, including self-scheduling.  
`/messaging`| Messages.  
`/payments`| Payments.  
`/labs`| Lab results.  
`/records`| Health records.  
`/my-health`| My Health.  
`/contact`| Contact.  
`/application/<application_id>`| A patient [application](/sdk/handlers-applications/) your plugin ships. See below for the id.  
The landing page and applications are always reachable. Every other destination requires that section to be turned on for the instance, and a path whose section is off sends the patient to the portal's login screen instead.
`<application_id>` is the base64 of the application's `identifier`, which the [Application](/sdk/data-application/) data module holds:
    ```python
    from base64 import b64encode
    from canvas_sdk.v1.data import Application
    application = Application.objects.get(name="Care Plan")
    application_id = b64encode(application.identifier.encode()).decode()
    next_path = f"/application/{application_id}"
    ```
An identifier defaults to `<module>:<ClassName>`, and base64 makes it about a third longer again, so this fits the 50-character limit only for identifiers of 27 characters or fewer. Give an application you intend to link to a short module path, and check the length of the path you build before relying on it.
Omitting `ttl` uses the `normal` tier of the instance's access token expiration setting, which Canvas ships as `10800` (3 hours). An instance can hold a different value, so treat 3 hours as the shipped default rather than a guarantee. The `86400` cap is the longest tier that setting ships with.
**Returns** : the login URL as a string.
`get_login_url()` raises `PatientPortalLinkError` when it can't obtain a link: Canvas was unreachable, returned a non-success response, or returned a response with no link. This is the one exception to catch, because a plugin can't catch the underlying `requests` exceptions.
> **Warning:** Treat the link as a credential: it authenticates as the patient and authorizes a password change. Deliver it only over a channel you have verified for the patient, and never log it.
The following handler fires when a patient's mobile number is added or changed, mints a link for the patient on the event, chooses the message copy from whether they have registered, and texts it over the plugin's own provider.
**Example** :
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.utils import Http
    from canvas_sdk.utils.patient_portal import PatientPortalLinkError, patient_portal_http
    from canvas_sdk.v1.data import PatientContactPoint
    from canvas_sdk.v1.data.common import ContactPointSystem, ContactPointUse
    class InvitePatient(BaseHandler):
        # A number can arrive as a new contact point or as an edit to an existing one.
        RESPONDS_TO = [
            EventType.Name(EventType.PATIENT_CONTACT_POINT_CREATED),
            EventType.Name(EventType.PATIENT_CONTACT_POINT_UPDATED),
        ]
        def compute(self) -> list[Effect]:
            # The event targets the contact point, which carries the patient it belongs to.
            contact_point = PatientContactPoint.objects.get(id=self.target)
            # Only the mobile number, since this handler sends a text.
            if (
                contact_point.system != ContactPointSystem.PHONE
                or contact_point.use != ContactPointUse.MOBILE
            ):
                return []
            # The link is a credential, so only send it to a number the patient confirmed.
            if not contact_point.last_verified:
                return []
            patient = contact_point.patient
            user = patient.user
            if user is None:
                return []  # No portal user yet, so nothing to invite.
            # A registered patient gets a password reset; a new one gets an activation
            # invite. The portal decides the same way when the link is opened.
            registered = user.is_portal_registered
            link_type = "reset" if registered else "invite"
            try:
                login_url = patient_portal_http.get_login_url(patient.id, link_type=link_type)
            except PatientPortalLinkError:
                return []
            body = (
                f"Reset your Canvas portal password: {login_url}"
                if registered
                else f"Activate your Canvas portal account: {login_url}"
            )
            # Deliver over your own verified channel: here, an SMS provider's API.
            Http().post(
                "https://sms-provider.example.com/send",
                headers={"Authorization": "Bearer <your-provider-token>"},
                json={"to": contact_point.value, "body": body},
            )
            return []
    ```
For a full, runnable plugin that mints a link, delivers it over a configurable provider, and reports the provider's delivery status, see the [patient_portal_link example plugin](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/patient_portal_link).

---

# Accessing Resource Attachment Files

Source: https://docs.canvasmedical.com/api/accessing-resource-attachment-files/

Several Canvas FHIR resources include a `url` attribute that points to an attachment file stored in S3. When you read or search these resources, the `url` value will be a `/files/` path on the Canvas FHIR server. Fetching that URL requires a **Bearer token** and returns a **redirect** to a pre-signed S3 URL that **expires after 10 minutes**.
There are two ways to retrieve the file, depending on whether you want the raw file content or the pre-signed URL itself.
##  Endpoints that return file URLs 
Resource| URL pattern  
---|---  
[Consent](/api/consent)| `GET /Consent/{id}/files/sourceAttachment`  
[DiagnosticReport](/api/diagnosticreport)| `GET /DiagnosticReport/{id}/files/presentedForm`  
[DocumentReference](/api/documentreference)| `GET /DocumentReference/{id}/files/content`  
[Media](/api/media)| `GET /Media/{id}/files/content`  
[Patient](/api/patient)| `GET /Patient/{id}/files/photo`  
[Practitioner](/api/practitioner)| `GET /Practitioner/{id}/files/signature`  
##  Option 1: Follow the redirect to get the file content 
The simplest approach is to let your HTTP client follow the redirect automatically. The pre-signed S3 URL contains its own authentication in the query parameters, so no additional headers are needed for the second request.
  - **curl**
        ```bash
        curl -L -o downloaded_file.pdf \
          -H "Authorization: Bearer $TOKEN" \
          "https://fumage-{instance}.canvasmedical.com/DocumentReference/abc123/files/content"
        ```
  - **python**
        ```python
        import requests
        base_url = "https://fumage-{instance}.canvasmedical.com"
        token = "your_bearer_token"
        file_url = f"{base_url}/DocumentReference/abc123/files/content"
        response = requests.get(
            file_url,
            headers={"Authorization": f"Bearer {token}"},
        )
        with open("downloaded_file.pdf", "wb") as f:
            f.write(response.content)
        ```
  - **javascript**
        ```javascript
        const response = await axios.get(url, {
          headers: { Authorization: `Bearer ${token}` },
          responseType: 'arraybuffer',
        });
        // response.data contains the raw file content
        writeFileSync('downloaded_file.pdf', Buffer.from(response.data));
        ```
##  Option 2: Capture the pre-signed URL without following the redirect 
If you need the pre-signed S3 URL itself — for example, to load it in an `<iframe>`, pass it to a frontend, or open it in a browser — you can configure your client to not follow redirects, and read the `Location` header in the response.
  - **curl**
        ```bash
        PRESIGNED_URL=$(curl -s -o /dev/null -w '%{redirect_url}' \
          -H "Authorization: Bearer $TOKEN" \
          "https://fumage-{instance}.canvasmedical.com/DocumentReference/abc123/files/content")
        echo "$PRESIGNED_URL"
        ```
  - **python**
        ```python
        import requests
        base_url = "https://fumage-{instance}.canvasmedical.com"
        token = "your_bearer_token"
        file_url = f"{base_url}/DocumentReference/abc123/files/content"
        response = requests.get(
            file_url,
            headers={"Authorization": f"Bearer {token}"},
            allow_redirects=False,
        )
        presigned_url = response.headers["Location"]
        # This URL works without auth and expires after 10 minutes
        ```
  - **javascript**
        ```javascript
        const response = await axios.get(url, {
          maxRedirects: 0,
          validateStatus: (status) => status === 307,
          headers: { Authorization: `Bearer ${token}` },
        });
        const presignedUrl = response.headers['location'];
        // This URL works without auth — use it in an iframe, open in browser, etc.
        ```
##  Note on HTTP client redirect behavior 
Per [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#section-15.4), compliant HTTP clients should strip the `Authorization` header when following a redirect to a different host. However, some HTTP clients do not do this, which can cause S3 to reject the request with a dual-auth error:
    ```xml
    <Error>
      <Code>InvalidArgument</Code>
      <Message>Only one auth mechanism allowed; only the X-Amz-Algorithm
      query parameter or the Authorization header should be specified,
      not both.</Message>
    </Error>
    ```
If you encounter this error, your client is forwarding the Bearer token to S3. Use **Option 2** above to handle the redirect manually, or configure your client to strip authorization headers on cross-origin redirects.

---

# Allergen

Source: https://docs.canvasmedical.com/api/allergen/

### 
A substance that, upon exposure to an individual, may cause a harmful or undesirable physiological response.   
Best practices is to utilize this endpoint to find codings to feed the [Allergy Intolerance Create/Update](/api/allergyintolerance/#create). These substances come directly from our integration with FDB.
### Endpoints
get/Allergen/{id} get/Allergen
get
/Allergen/{id}
#### Allergen read
Read an Allergen resource.
### Path Parameters
id required
string
The unique identifier for the Allergen   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Allergen.
text
json
Text summary of the Allergen, for human interpretation.
Click to view child attributes
status
All allergens returned from this endpoint will show a status of `generated` since this resource is generated from FDB.
div
Limited xhtml content that contains the human readable text of the Allergen.
code
json
Code that identifies the allergen   
In Canvas we will return two different codings: one from FDB and one RxNorm
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://snomed.info/sct
  - http://www.fdbhealth.com/
code
string
The code of the allergen
display
string
The display name of the coding
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Allergen
#### Allergen search
Search for Allergen resources.
### Query Parameters
**An Allergen Search requires either a code or _text search parameter to perform.**
_text
string
Performs a case insensitive partial search on the narrative of the Allergen.
code
string
System url and code that identifies the allergen formatted like   
`system_url|code`.
**Search Values Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm|code
  - http://snomed.info/sct|code
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Allergen.
text
json
Text summary of the Allergen, for human interpretation.
Click to view child attributes
status
All allergens returned from this endpoint will show a status of `generated` since this resource is generated from FDB.
div
Limited xhtml content that contains the human readable text of the Allergen.
code
json
Code that identifies the allergen   
In Canvas we will return two different codings: one from FDB and one RxNorm
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://snomed.info/sct
  - http://www.fdbhealth.com/
code
string
The code of the allergen
display
string
The display name of the coding
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Allergen/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Allergen/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Allergen",
            "id": "fdb-6-2754",
            "text": {
                "status": "generated",
                "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>minocycline HCl</p><p>6979</p>\"</div>"
            },
            "code": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "6-2754",
                        "display": "minocycline HCl"
                    },
                    {
                        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                        "code": "6979"
                    }
                ]
            }
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Allergen resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Allergen?code=http://www.nlm.nih.gov/research/umls/rxnorm|6979' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Allergen?code=http://www.nlm.nih.gov/research/umls/rxnorm|6979"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Allergen?code=http%3A%2F%2Fwww.nlm.nih.gov%2Fresearch%2Fumls%2Frxnorm%7C6979&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Allergen?code=http%3A%2F%2Fwww.nlm.nih.gov%2Fresearch%2Fumls%2Frxnorm%7C6979&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Allergen?code=http%3A%2F%2Fwww.nlm.nih.gov%2Fresearch%2Fumls%2Frxnorm%7C6979&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Allergen",
                        "id": "fdb-6-2754",
                        "text": {
                            "status": "generated",
                            "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>minocycline HCl</p><p>6979</p>\"</div>"
                        },
                        "code": {
                            "coding": [
                                {
                                    "system": "http://www.fdbhealth.com/",
                                    "code": "6-2754",
                                    "display": "minocycline HCl"
                                },
                                {
                                    "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                                    "code": "6979"
                                }
                            ]
                        }
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# AllergyIntolerance

Source: https://docs.canvasmedical.com/api/allergyintolerance/

### 
Risk of harmful or undesirable, physiological response which is unique to an individual and associated with exposure to a substance.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-allergyintolerance.html>   
To learn more about documenting allergies in Canvas see [here](https://canvas-medical.help.usepylon.com/articles/9964004914-document-allergies).
### Endpoints
post/AllergyIntolerance get/AllergyIntolerance/{id} put/AllergyIntolerance/{id} get/AllergyIntolerance
post
/AllergyIntolerance
#### AllergyIntolerance create
Create an AllergyIntolerance resource.
### Attributes
resourceType
string
The FHIR Resource name.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Canvas recommends sending the note identifier extension or the Encounter reference, but not both. If both are supplied, they must both refer to the same note. If neither is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
clinicalStatus
json required
The clinical status of the allergy or intolerance.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical
code
string required
The code of the clinical status.
**Value Options Supported:**
  - active
  - inactive
verificationStatus
json required
Assertion about certainty associated with the propensity, or potential risk, of a reaction to the identified substance (including pharmaceutical product).
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/allergyintolerance-verification
code
string required
The code of the verification status.
**Value Options Supported:**
  - confirmed
  - entered-in-error
type
enum [ allergy | intolerance ] required
Identification of the underlying physiological mechanism for the reaction risk.
code
json required
Code that identifies the allergy or intolerance.
Supported codings for create interactions are obtained from the [Allergen search endpoint](/api/allergen/#search). At least one coding needs to be an FDB coding.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://www.fdbhealth.com/
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://snomed.info/sct
code
string required
The code of the allergen.
patient
json required
Who the sensitivity is for.
Click to view child attributes
reference
string required
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter when the allergy or intolerance was asserted.
Supply an encounter reference to be able to insert the allergy command into a specific note on the patient's timeline. If no encounter is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.   
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/086cd6fe-2c94-455d-a53e-6ff1c2652cae"`.
type
string
Type the reference refers to (e.g. "Encounter").
onsetDateTime
date
When allergy or intolerance was identified.
recorder
json
Who recorded the sensitivity.   
In Canvas this will be the originator and committer of the allergy command.
Click to view child attributes
reference
string required
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e`.
type
string
Type the reference refers to (e.g. "Practitioner").
lastOccurrence
date
Date of last known occurrence of a reaction.   
This date will not appear in the Canvas UI and can only be supplied or read through FHIR.
note
array[json]
Additional text not captured in other fields.   
Canvas will display this in the `reaction` field of the allergy command. If there are multiple objects given, they will be separeted by a new line on the UI.
Click to view child attributes
text
string required
The annotation - text content.
reaction
array[json]
Adverse Reaction Events linked to exposure to substance. Only one reaction is supported.
Click to view child attributes
manifestation
array[json] required
Clinical symptoms/signs associated with the Event.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/data-absent-reason
code
string required
The code of the verification status.
**Value Options Supported:**
  - unknown
severity
string
Clinical assessment of the severity of the reaction event as a whole.
**Value Options Supported:**
  - mild
  - moderate
  - severe
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/AllergyIntolerance/{id}
#### AllergyIntolerance read
Read an AllergyIntolerance resource.
### Path Parameters
id required
string
The unique identifier for the AllergyIntolerance   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the AllergyIntolerance.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
clinicalStatus
json
The clinical status of the allergy or intolerance.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical
code
string
The code of the clinical status.
**Value Options Supported:**
  - active
  - inactive
display
string
The display name of the coding.
**Value Options Supported:**
  - Active
  - Inactive
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Active
  - Inactive
verificationStatus
json
Assertion about certainty associated with the propensity, or potential risk, of a reaction to the identified substance (including pharmaceutical product).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/allergyintolerance-verification
code
string
The code of the verification status.
**Value Options Supported:**
  - confirmed
  - entered-in-error
display
string
The display name of the coding.
**Value Options Supported:**
  - Confirmed
  - Entered in Error
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Confirmed
  - Entered in Error
type
enum [ allergy | intolerance ]
Identification of the underlying physiological mechanism for the reaction risk.
code
json
Code that identifies the allergy or intolerance.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.fdbhealth.com/
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://snomed.info/sct
code
string
The code of the allergen.
display
string
The display name of the coding.
patient
json
Who the sensitivity is for.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter when the allergy or intolerance was asserted.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/086cd6fe-2c94-455d-a53e-6ff1c2652cae"`.
type
string
Type the reference refers to (e.g. "Encounter").
onsetDateTime
date
When allergy or intolerance was identified.
recordedDate
datetime
Date first version of the resource instance was recorded.
recorder
json
Who recorded the sensitivity.   
In Canvas this will be the originator and committer of the allergy command.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e`.
type
string
Type the reference refers to (e.g. "Practitioner").
lastOccurrence
date
Date of last known occurrence of a reaction.   
This date will not appear in the Canvas UI and can only be supplied or read through FHIR.
note
array[json]
Additional text not captured in other fields.   
Canvas will display this in the `reaction` field of the allergy command. If there are multiple objects given, they will be separeted by a new line on the UI.
Click to view child attributes
text
string
The annotation - text content.
reaction
array[json]
Adverse Reaction Events linked to exposure to substance. Only one reaction is supported.
Click to view child attributes
manifestation
array[json]
Clinical symptoms/signs associated with the Event.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/data-absent-reason
code
string
The code of the verification status.
**Value Options Supported:**
  - unknown
display
string
The display name of the coding.
**Value Options Supported:**
  - Unknown
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Unknown
severity
string
Clinical assessment of the severity of the reaction event as a whole.
**Value Options Supported:**
  - mild
  - moderate
  - severe
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/AllergyIntolerance/{id}
#### AllergyIntolerance update
Update an AllergyIntolerance resource.  
The only type of AllergyIntolerance update interaction that is supported by Canvas is to mark an existing AllergyIntolerance as **entered-in-error** using the `verificationStatus` attribute. No changes to other fields will be processed; however, required fields still need to be supplied.
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The identifier of the AllergyIntolerance.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
clinicalStatus
json required
The clinical status of the allergy or intolerance.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical
code
string required
The code of the clinical status.
**Value Options Supported:**
  - active
  - inactive
verificationStatus
json required
Assertion about certainty associated with the propensity, or potential risk, of a reaction to the identified substance (including pharmaceutical product).
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/allergyintolerance-verification
code
string required
The code of the verification status.
**Value Options Supported:**
  - confirmed
  - entered-in-error
type
enum [ allergy | intolerance ] required
Identification of the underlying physiological mechanism for the reaction risk.
code
json required
Code that identifies the allergy or intolerance.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://www.fdbhealth.com/
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://snomed.info/sct
code
string required
The code of the allergen.
patient
json required
Who the sensitivity is for.
Click to view child attributes
reference
string required
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter when the allergy or intolerance was asserted.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/086cd6fe-2c94-455d-a53e-6ff1c2652cae"`.
type
string
Type the reference refers to (e.g. "Encounter").
onsetDateTime
date
When allergy or intolerance was identified.
recorder
json
Who recorded the sensitivity.   
In Canvas this will be the originator and committer of the allergy command.
Click to view child attributes
reference
string required
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e`.
type
string
Type the reference refers to (e.g. "Practitioner").
lastOccurrence
date
Date of last known occurrence of a reaction.   
This date will not appear in the Canvas UI and can only be supplied or read through FHIR.
note
array[json]
Additional text not captured in other fields.   
Canvas will display this in the `reaction` field of the allergy command. If there are multiple objects given, they will be separeted by a new line on the UI.
Click to view child attributes
text
string required
The annotation - text content.
reaction
array[json]
Adverse Reaction Events linked to exposure to substance. Only one reaction is supported.
Click to view child attributes
manifestation
array[json] required
Clinical symptoms/signs associated with the Event.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/data-absent-reason
code
string required
The code of the verification status.
**Value Options Supported:**
  - unknown
severity
string
Clinical assessment of the severity of the reaction event as a whole.
**Value Options Supported:**
  - mild
  - moderate
  - severe
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/AllergyIntolerance
#### AllergyIntolerance search
Search for AllergyIntolerance resources.
### Query Parameters
****
_id
string
The identifier of the AllergyIntolerance.
patient
string
The patient reference associated to the AllergyIntolerance in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the AllergyIntolerance.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
clinicalStatus
json
The clinical status of the allergy or intolerance.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical
code
string
The code of the clinical status.
**Value Options Supported:**
  - active
  - inactive
display
string
The display name of the coding.
**Value Options Supported:**
  - Active
  - Inactive
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Active
  - Inactive
verificationStatus
json
Assertion about certainty associated with the propensity, or potential risk, of a reaction to the identified substance (including pharmaceutical product).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/allergyintolerance-verification
code
string
The code of the verification status.
**Value Options Supported:**
  - confirmed
  - entered-in-error
display
string
The display name of the coding.
**Value Options Supported:**
  - Confirmed
  - Entered in Error
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Confirmed
  - Entered in Error
type
enum [ allergy | intolerance ]
Identification of the underlying physiological mechanism for the reaction risk.
code
json
Code that identifies the allergy or intolerance.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.fdbhealth.com/
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://snomed.info/sct
code
string
The code of the allergen.
display
string
The display name of the coding.
patient
json
Who the sensitivity is for.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter when the allergy or intolerance was asserted.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/086cd6fe-2c94-455d-a53e-6ff1c2652cae"`.
type
string
Type the reference refers to (e.g. "Encounter").
onsetDateTime
date
When allergy or intolerance was identified.
recordedDate
datetime
Date first version of the resource instance was recorded.
recorder
json
Who recorded the sensitivity.   
In Canvas this will be the originator and committer of the allergy command.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e`.
type
string
Type the reference refers to (e.g. "Practitioner").
lastOccurrence
date
Date of last known occurrence of a reaction.   
This date will not appear in the Canvas UI and can only be supplied or read through FHIR.
note
array[json]
Additional text not captured in other fields.   
Canvas will display this in the `reaction` field of the allergy command. If there are multiple objects given, they will be separeted by a new line on the UI.
Click to view child attributes
text
string
The annotation - text content.
reaction
array[json]
Adverse Reaction Events linked to exposure to substance. Only one reaction is supported.
Click to view child attributes
manifestation
array[json]
Clinical symptoms/signs associated with the Event.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/data-absent-reason
code
string
The code of the verification status.
**Value Options Supported:**
  - unknown
display
string
The display name of the coding.
**Value Options Supported:**
  - Unknown
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Unknown
severity
string
Clinical assessment of the severity of the reaction event as a whole.
**Value Options Supported:**
  - mild
  - moderate
  - severe
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/AllergyIntolerance' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "AllergyIntolerance",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                        "code": "active",
                        "display": "Active"
                    }
                ],
                "text": "Active"
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
                        "code": "confirmed",
                        "display": "Confirmed"
                    }
                ],
                "text": "Confirmed"
            },
            "type": "allergy",
            "code": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "2-15588",
                        "display": "Allergy Medicine"
                    }
                ],
                "text": "Allergy Medicine"
            },
            "patient": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "recorder": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "lastOccurrence": "2023-06-17",
            "note": [
                {
                    "text": "AllergyIntolerance note"
                }
            ],
            "reaction": [
                {
                    "manifestation": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                    "code": "unknown",
                                    "display": "Unknown"
                                }
                            ],
                            "text": "Unknown"
                        }
                    ],
                    "severity": "moderate"
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/AllergyIntolerance"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "AllergyIntolerance",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                        "code": "active",
                        "display": "Active"
                    }
                ],
                "text": "Active"
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
                        "code": "confirmed",
                        "display": "Confirmed"
                    }
                ],
                "text": "Confirmed"
            },
            "type": "allergy",
            "code": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "2-15588",
                        "display": "Allergy Medicine"
                    }
                ],
                "text": "Allergy Medicine"
            },
            "patient": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "recorder": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "lastOccurrence": "2023-06-17",
            "note": [
                {
                    "text": "AllergyIntolerance note"
                }
            ],
            "reaction": [
                {
                    "manifestation": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                    "code": "unknown",
                                    "display": "Unknown"
                                }
                            ],
                            "text": "Unknown"
                        }
                    ],
                    "severity": "moderate"
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/AllergyIntolerance/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/AllergyIntolerance/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "AllergyIntolerance",
            "id": "3340c331-d446-4700-9c23-7959bd393f26",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                        "code": "active",
                        "display": "Active"
                    }
                ],
                "text": "Active"
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
                        "code": "confirmed",
                        "display": "Confirmed"
                    }
                ],
                "text": "Confirmed"
            },
            "type": "allergy",
            "code": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "2-15588",
                        "display": "Allergy Medicine"
                    }
                ],
                "text": "Allergy Medicine"
            },
            "patient": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "recorder": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "lastOccurrence": "2023-06-17",
            "note": [
                {
                    "text": "AllergyIntolerance note"
                }
            ],
            "reaction": [
                {
                    "manifestation": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                    "code": "unknown",
                                    "display": "Unknown"
                                }
                            ],
                            "text": "Unknown"
                        }
                    ],
                    "severity": "moderate"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown AllergyIntolerance resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/AllergyIntolerance/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "AllergyIntolerance",
             "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                        "code": "active",
                        "display": "Active"
                    }
                ],
                "text": "Active"
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
                        "code": "entered-in-error",
                        "display": "Entered in Error"
                    }
                ],
                "text": "Entered in Error"
            },
            "type": "allergy",
            "code": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "2-15588",
                        "display": "Allergy Medicine"
                    }
                ],
                "text": "Allergy Medicine"
            },
            "patient": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "recorder": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "lastOccurrence": "2023-06-17",
            "note": [
                {
                    "text": "AllergyIntolerance note"
                }
            ],
            "reaction": [
                {
                    "manifestation": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                    "code": "unknown",
                                    "display": "Unknown"
                                }
                            ],
                            "text": "Unknown"
                        }
                    ],
                    "severity": "moderate"
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/AllergyIntolerance/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "AllergyIntolerance",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                        "code": "active",
                        "display": "Active"
                    }
                ],
                "text": "Active"
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
                        "code": "entered-in-error",
                        "display": "Entered in Error"
                    }
                ],
                "text": "Entered in Error"
            },
            "type": "allergy",
            "code": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "2-15588",
                        "display": "Allergy Medicine"
                    }
                ],
                "text": "Allergy Medicine"
            },
            "patient": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "recorder": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "lastOccurrence": "2023-06-17",
            "note": [
                {
                    "text": "AllergyIntolerance note"
                }
            ],
            "reaction": [
                {
                    "manifestation": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                    "code": "unknown",
                                    "display": "Unknown"
                                }
                            ],
                            "text": "Unknown"
                        }
                    ],
                    "severity": "moderate"
                }
            ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown AllergyIntolerance resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/AllergyIntolerance?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/AllergyIntolerance?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/AllergyIntolerance?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/AllergyIntolerance?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/AllergyIntolerance?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "AllergyIntolerance",
                        "id": "3340c331-d446-4700-9c23-7959bd393f26",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                                "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                            }
                        ],
                        "clinicalStatus": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                                    "code": "active",
                                    "display": "Active"
                                }
                            ],
                            "text": "Active"
                        },
                        "verificationStatus": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
                                    "code": "confirmed",
                                    "display": "Confirmed"
                                }
                            ],
                            "text": "Confirmed"
                        },
                        "type": "allergy",
                        "code": {
                            "coding": [
                                {
                                    "system": "http://www.fdbhealth.com/",
                                    "code": "2-15588",
                                    "display": "Allergy Medicine"
                                }
                            ],
                            "text": "Allergy Medicine"
                        },
                        "patient": {
                            "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
                        },
                        "encounter": {
                            "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
                        },
                        "onsetDateTime": "2023-06-15",
                        "recorder": {
                            "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
                        },
                        "lastOccurrence": "2023-06-17",
                        "note": [
                            {
                                "text": "AllergyIntolerance note"
                            }
                        ],
                        "reaction": [
                            {
                                "manifestation": [
                                    {
                                        "coding": [
                                            {
                                                "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                                "code": "unknown",
                                                "display": "Unknown"
                                            }
                                        ],
                                        "text": "Unknown"
                                    }
                                ],
                                "severity": "moderate"
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Appointment

Source: https://docs.canvasmedical.com/api/appointment/

### 
A booking of a healthcare event among patient(s), practitioner(s), related person(s) and/or device(s) for a specific date/time. This may result in one or more Encounter(s).  
<https://hl7.org/fhir/R4/appointment.html>   
This may result in one or more [Encounters](/api/encounter).  
The appointment resource maps to both [patient appointments](https://canvas-medical.help.usepylon.com/articles/4617508394-appointment-management) as well as [other events](https://canvas-medical.help.usepylon.com/articles/4617508394-appointment-management#scheduling-other-events-30) in Canvas. Instructions for configuring event and note types can be found [here](https://canvas-medical.help.usepylon.com/articles/6785045644-appointment-event-note-types).
### Endpoints
post/Appointment get/Appointment/{id} put/Appointment/{id} get/Appointment
post
/Appointment
#### Appointment create
Create an **Appointment**  
It is recommended to utilize the [FHIR Slot Search](/api/slot#search) to find appointment times for a specific practitioner.  
**Prevent Double Booking** By default, Canvas does not prevent appointments from being created if there is already an existing appointment for that provider. However, Canvas has a config setting to disable double booking. If double booking is not allowed and the Appointment Create or Appointment Update request is trying to book an appointment for a given Provider that already has a scheduled appointment at that time, you will see a 422 error status with the following error message returned `This appointment time is no longer available.` On instances in the [Google Calendar Sync beta](/product-updates/google-calendar-sync/), busy time from a provider's connected Google calendars counts as a scheduled appointment for this check. That busy time is not an Appointment, so it is not returned by Appointment search.
### Attributes
resourceType
string
The FHIR Resource name.
contained
array[json]
Contained, inline Resources. Used to store links for telehealth appointments.
This endpoint allows one custom video meeting link to be passed in that will be utilized on the UI over the default provider's meeting link if the appointment is a telemedicine. You can specify a telehealth meeting link by adding an element in the `SupportingInformation` attribute where the `SupportingInformation.reference` is `#appointment-meeting-endpoint-0` and matches the `contained[0].id` attribute of `appointment-meeting-endpoint-0`. See examples for help.
Click to view child attributes
resourceType
enum [ Endpoint ] required
id
string required
The `id` of the contained entry. This needs to be `appointment-meeting-endpoint-0` and the SupportingInformation.reference will be `#appointment-meeting-endpoint-0`.
address
string required
The technical base address for connecting to this endpoint.
identifier
array[json]
External Ids for this item.   
The identifier list defines additional identifiers that are able to be stored for an appointment.  
These identifiers will not be surfaced on the Patient's chart, but they may help you identify the patient in your system by associating your identifier with the resource's `id`.
Click to view child attributes
use
enum [ usual | official | temp | secondary | old ]
The purpose of this identifier. If this is omitted, it will default to `usual`.
system
string
The namespace for the identifier value.
value
string
The value that is unique
assigner
json
Text representing Organization that issued id. If ommitted it will default to the system of the identifier.
Click to view child attributes
display
string
period
json
Time period when id is/was valid for use.
Click to view child attributes
start
datetime
Starting time with inclusive boundary. If omitted this will default to `1970-01-01`.
end
datetime
End time with inclusive boundary, if not ongoing. If ommitted this will default to `2100-12-31`.
status
enum [ arrived | booked | cancelled | checked-in | fulfilled | noshow | pending | proposed ] required
The status of the appointment. The status `entered-in-error` may also be returned on read but is not accepted on create or update.   
This table shows the mappings of statuses/states an appointment is in within Canvas to the FHIR status attribute.   
FHIR Status| Canvas Status  
---|---  
proposed| unconfirmed  
pending| attempted  
booked| confirmed  
arrived| arrived  
checked-in| roomed  
fulfilled| exited  
noshow| noshowed  
cancelled| cancelled  
entered-in-error| deleted  
If any of the first 7 FHIR statuses are used, the appointment will appear on the schedule from the dropdown on the Appointment Card in the Schedule view with one of those statuses.   
An appointment can be created as `cancelled` for historical purposes, but it will not appear on the schedule view and will be a restorable note on the patient's timeline.   
The Create endpoint does NOT accept a status of `entered-in-error`.
appointmentType
json
The style of appointment or patient that has been booked in the slot (not service type). Canvas supports configurable [event and note types](https://canvas-medical.help.usepylon.com/articles/6785045644-appointment-event-note-types).
There are a few things to note with this attribute:   
1.If the `appointmentType` attribute is omitted from the body completely, the note type that has `Is default appointment type` will be used (usually Office Visit if unchanged)  
2.If the code / system pair does not exist, you will see a 422 error status with error message `Appointment Type does not exist with code: {code} and system: {system}`   
3.If the code / system pair passed is not marked as `Is Scheduleable` in Canvas, you will get a 422 error status with error message `Note type: {name} is not scheduleable`.
Click to view child attributes
coding
array[json]
The type of appointment
Click to view child attributes
system
string
The system of the appointment. On create and update, only `http://snomed.info/sct` and `INTERNAL` are accepted; other systems will be rejected.
**Value Options Supported:**
  - http://snomed.info/sct
  - INTERNAL
code
string
The code of the appointment.   
This needs to match a coding in the Event and Note Types Canvas Settings and be deemed as Is Scheduleable.
reasonCode
array[json]
Coded reason this appointment is scheduled.   
Canvas supports two ways to specify the reason for vist (RFV): [structured](/sdk/data-reason-for-visit/#reasonforvisitsettingcoding) and unstructured. Both the `coding` and `text` attributes are used for Structured RFVs, whereas unstructured RFVs only leverage the `text` attribute.
Canvas only accepts the first item in the reasonCode list.  
If you are taking advantage of our [structured reason for visit](/sdk/data-reason-for-visit/#reasonforvisitsettingcoding) feature, you can provide a `coding` that Canvas can use to look up the `code` value in configured in settings and display the structured RFV matching that code. If `Appointment.reasonCode[0].coding[0].code` is not a valid ReasonForVisitSettingCoding you will get the error "structured reason for visit with code {code} does not exist". You will also receive an error if the RFV code in Canvas' setting's page is not unique.   
The `text` attribute maps to the free text Reason For Visit command. If you are using the structured reason for visit feature, this text will display as the `comment` in the command. If you are not using the structured reason for visit feature, then only `Appointment.reasonCode[0].text` needs to be populated in your message and `coding` should be omitted.   
If this field is omitted (along with the deprecated `description` field), the RFV command in the appointment note will be defaulted to `No description given`.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
code
string
The code of the reason for visit.
text
string
description
string
Shown on a subject line in a meeting request, or appointment list.  
This description attribute is useful for Scheduled Events in Canvas that do no have a corresponding timeline entry.  
For appointments associated with a patient timeline entry, we strongly suggest using the `reasonCode` field to map to the Reason For Visit command in a Canvas Note. However, this descrition will match the reasonCode.text attribute in a Read/Search
supportingInformation
array[json] required
Additional information to support the appointment. Currently, Canvas supports the ability to write 2 different types of references:   
  1. `Location`: A reference to a Location captures what Practice Location in Canvas the appointment will take place at.  
  2. `Meeting Link`: For appointments that are telehealth in Canvas, there can be a reference to an endpoint in this list. The reference attribute will need to match an `id` in the `Appointment.contained` attribute list, but will need to have a `#` in front of the reference string. See examples for help. For telehealth appointments where no meeting link reference is supplied, it will default to the practitioner's personal meeting room link as defined in Canvas Settings.
Click to view child attributes
reference
string required
The reference string of the supporting information.
If the entry is for a Location the format will be `"Location/9d3a079f-22c0-4918-96d7-72eb567563ec"`. You can retrieve this information for a [Location Search](/api/location#search).  
If the entry is for a virtual meeting link, the reference should be `#appointment-meeting-endpoint-0`.
type
string
Type the reference refers to (e.g. "Location", "Endpoint", "Encounter", "Appointment").
start
datetime required
When appointment is to take place.
The `start` attribute determines the start timestamp of the appointment. It is written in [instant format for FHIR](https://www.hl7.org/fhir/datatypes.html#instant). Seconds and milliseconds can be omitted, but YYYY-MM-DDTHH:MM are required.
end
datetime required
When appointment is to conclude.
The end attribute is used with the start timestamp to determine the duration in minutes of the appointment. The duration of the appointment must be greater than 0 minutes. It is written in [instant format for FHIR](https://www.hl7.org/fhir/datatypes.html#instant). Seconds and milliseconds can be omitted, but YYYY-MM-DDTHH:MM are required.
participant
array[json] required
Participants involved in appointment. At least one object needs to be supplied that corresponds to the practitioner, there will always be a practitioner involved in every appointment type. An optional 2nd object corresponding to the patient reference will be accepted if the `appointmentType` allows/requires a patient participant.
Click to view child attributes
actor
json required
Reference to person involved in appointment.
Click to view child attributes
reference
string required
The reference string of the practitioner or patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
**Value Options Supported:**
  - Practitioner/id
  - Patient/id
type
string
Type the reference refers to (e.g. "Patient", "Practitioner").
**Value Options Supported:**
  - Practitioner
  - Patient
status
enum [ accepted ] required
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Appointment/{id}
#### Appointment read
Read an Appointment
### Path Parameters
id required
string
The unique identifier for the Appointment   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the appointment.
contained
array[json]
Contained, inline Resources. Used to store links for telehealth appointments.
There will be a reference in the `supportingInformation` attribute with a `type` of `Endpoint` and a reference` of `#appointment-meeting-endpoint-0` that will match the `contained[0].id`.
Click to view child attributes
resourceType
enum [ Endpoint ]
id
string
The `id` of the contained entry. This needs to be `appointment-meeting-endpoint-0` and the SupportingInformation.reference will be `#appointment-meeting-endpoint-0`.
status
enum [ active ]
connectionType
json
Click to view child attributes
code
string
Protocol/Profile/Standard to be used with this endpoint connection
payloadType
array[json]
Click to view child attributes
coding
array[json]
Click to view child attributes
code
enum [ video-call ]
address
string
The technical base address for connecting to this endpoint.
extension
array[json]
Canvas supports a note identifier extension on this resource for read and search interactions. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
identifier
array[json]
External Ids for this item.   
The identifier list defines additional identifiers that are able to be stored for an appointment.  
These identifiers will not be surfaced on the Patient's chart, but they may help you identify the patient in your system by associating your identifier with the resource's `id`.
Click to view child attributes
id
string
Unique id for inter-element referencing
use
enum [ usual | official | temp | secondary | old ]
The purpose of this identifier. If this is omitted, it will default to `usual`.
system
string
The namespace for the identifier value.
value
string
The value that is unique
period
json
Time period when id is/was valid for use.
Click to view child attributes
start
datetime
Starting time with inclusive boundary. If omitted this will default to `1970-01-01`.
end
datetime
End time with inclusive boundary, if not ongoing. If ommitted this will default to `2100-12-31`.
status
enum [ arrived | booked | cancelled | checked-in | fulfilled | noshow | pending | proposed ]
The status of the appointment. The status `entered-in-error` may also be returned on read but is not accepted on create or update.   
This table shows the mappings of statuses/states an appointment is in within Canvas to the FHIR status attribute.   
FHIR Status| Canvas Status  
---|---  
proposed| unconfirmed  
pending| attempted  
booked| confirmed  
arrived| arrived  
checked-in| roomed  
fulfilled| exited  
noshow| noshowed  
cancelled| cancelled  
entered-in-error| deleted  
The first 7 statuses come from the dropdown on the Appointment Card in the Schedule view. A `cancelled` status comes from a patient appointment or an other event being cancelled. The `deleted/entered-in-error` status is when a checked-in appointment note has been deleted in Canvas.
appointmentType
json
The style of appointment or patient that has been booked in the slot (not service type). Canvas supports configurable [event and note types](https://canvas-medical.help.usepylon.com/articles/6785045644-appointment-event-note-types).
Click to view child attributes
coding
array[json]
The type of appointment
Click to view child attributes
system
string
The system of the appointment
**Value Options Supported:**
  - http://snomed.info/sct
  - INTERNAL
code
string
The code of the appointment.   
This needs to match a coding in the Event and Note Types Canvas Settings and be deemed as Is Scheduleable.
display
string
The display of the appointment
reasonCode
array[json]
Coded reason this appointment is scheduled.   
Canvas supports two ways to specify the reason for vist (RFV): [structured](/sdk/data-reason-for-visit/#reasonforvisitsettingcoding) and unstructured. Both the `coding` and `text` attributes are used for Structured RFVs, whereas unstructured RFVs only leverage the `text` attribute.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system of the coding.
code
string
The code of the reason for visit.
display
string
The display name of the coding.
userSelected
boolean
If this coding was chosen directly by the user. In Canvas this indicates if the coding is currently active or not.
text
string
description
string
Shown on a subject line in a meeting request, or appointment list.  
This description attribute is useful for Scheduled Events in Canvas that do no have a corresponding timeline entry.  
For appointments associated with a patient timeline entry, we strongly suggest using the `reasonCode` field to map to the Reason For Visit command in a Canvas Note. However, this descrition will match the reasonCode.text attribute in a Read/Search
supportingInformation
array[json]
Additional information to support the appointment. Currently, Canvas supports different types of references in this list:   
  1. `Location`: A reference to a Location captures what Practice Location in Canvas the appointment will take place at.  
  2. `Meeting Link`: For appointments that are telehealth in Canvas, there will be a reference to an endpoint in this list. The reference attribute will match an `id` in the `Appointment.contained` attribute list. That element will display the url address of the virtual meeting link.   
  3. `Appointment`: If an appointment has been rescheduled, this list could display an associated Appointment reference. If you see a display of `Previously Rescheduled Appointment`, it means that the appointment you are currently looking at was created after rescheduling the appointment in that Reference. If you see a display of `Rescheduled Replacement Appointment`, it means that the appointment you are currently looking at is now outdated by a new appointment. If you see a display of `Co-scheduled Appointment`, it means that the appointment you are currently looking at was scheduled with other additional associated appointments for which the appointment reference ID is noted.   
  4. `Encounter`: If there is any encounter associated with the appointment made in Canvas, the reference will appear in this list.
Click to view child attributes
reference
string
The reference string of the supporting information.
type
string
Type the reference refers to (e.g. "Location", "Endpoint", "Encounter", "Appointment").
display
string
Display name of the reference
**Value Options Supported:**
  - Previously Rescheduled Appointment
  - Rescheduled Replacement Appointment
  - Co-scheduled Appointment
start
datetime
When appointment is to take place.
end
datetime
When appointment is to conclude.
participant
array[json]
Participants involved in appointment. There will be at least one entry for a practitioner. An optional 2nd entry will display if the appointment involves a specific patient. This will be dictated by the `appointmentType` and if it relates to a generic event or a patient's appointment.
Click to view child attributes
actor
json
Reference to person involved in appointment.
Click to view child attributes
reference
string
The reference string of the practitioner or patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
**Value Options Supported:**
  - Practitioner/id
  - Patient/id
type
string
Type the reference refers to (e.g. "Patient", "Practitioner").
**Value Options Supported:**
  - Practitioner
  - Patient
status
enum [ accepted ]
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Appointment/{id}
#### Appointment update
This is almost identical to the [Appointment Create](/api/appointment/#create). You must include **all required fields** in the request body, even if only some fields are changing; omitting required fields will result in a validation error. Optional fields that are omitted will be ignored and left as they are currently set in the Canvas database.  
A FHIR Appointment update interaction behaves differently than a rescheduling workflow in the Canvas UI. FHIR updates will directly modify the Appointment referred to by the `id` rather than creating a new appointment.  
Canvas prevents updating the patient an appointment is already associated to. Best practice is to cancel the existing appointment and create a new appointment with the correct patient.
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The identifier of the appointment.
contained
array[json]
Contained, inline Resources. Used to store links for telehealth appointments.
This endpoint allows one custom video meeting link to be passed in that will be utilized on the UI over the default provider's meeting link if the appointment is a telemedicine. You can specify a telehealth meeting link by adding an element in the `SupportingInformation` attribute where the `SupportingInformation.reference` is `#appointment-meeting-endpoint-0` and matches the `contained[0].id` attribute of `appointment-meeting-endpoint-0`. See examples for help.
Click to view child attributes
resourceType
enum [ Endpoint ] required
id
string required
The `id` of the contained entry. This needs to be `appointment-meeting-endpoint-0` and the SupportingInformation.reference will be `#appointment-meeting-endpoint-0`.
address
string required
The technical base address for connecting to this endpoint.
identifier
array[json]
External Ids for this item.   
The identifier list defines additional identifiers that are able to be stored for an appointment.  
These identifiers will not be surfaced on the Patient's chart, but they may help you identify the patient in your system by associating your identifier with the resource's `id`.
To update an existing `identifier`, include the `id` in the `identifier[x].id` field returned from Read/Search.  
The `identifier` section sent in an update will entirely replace existing identifiers currently within the period.start and period.end dates.  
If an `identifier` already exists in the Canvas database and is not included in the Update message, it will be deleted if and only if the period.end date is in the future.
Click to view child attributes
id
string
Unique id for inter-element referencing
use
enum [ usual | official | temp | secondary | old ]
The purpose of this identifier. If this is omitted, it will default to `usual`.
system
string
The namespace for the identifier value.
value
string
The value that is unique
assigner
json
Text representing Organization that issued id. If ommitted it will default to the system of the identifier.
Click to view child attributes
display
string
period
json
Time period when id is/was valid for use.
Click to view child attributes
start
datetime
Starting time with inclusive boundary. If omitted this will default to `1970-01-01`.
end
datetime
End time with inclusive boundary, if not ongoing. If ommitted this will default to `2100-12-31`.
status
enum [ arrived | booked | cancelled | checked-in | fulfilled | noshow | pending | proposed ] required
The status of the appointment. The status `entered-in-error` may also be returned on read but is not accepted on create or update.   
This table shows the mappings of statuses/states an appointment is in within Canvas to the FHIR status attribute.   
FHIR Status| Canvas Status  
---|---  
proposed| unconfirmed  
pending| attempted  
booked| confirmed  
arrived| arrived  
checked-in| roomed  
fulfilled| exited  
noshow| noshowed  
cancelled| cancelled  
entered-in-error| deleted  
If any of the first 7 FHIR statuses are used, the appointment will appear on the schedule from the dropdown on the Appointment Card in the Schedule view with one of those statuses.   
An appointment can be updated to `cancelled` and as a result it will disappear from the schedule view and/or will be a restorable note on the patient's timeline. Once an appointment is in a cancelled state, it should not be updated to a different status via FHIR, instead the note should be reverted directly in the Patient's chart before it can be updated via FHIR again.   
The Update endpoint does NOT accept a status of `entered-in-error`.
appointmentType
json
The style of appointment or patient that has been booked in the slot (not service type). Canvas supports configurable [event and note types](https://canvas-medical.help.usepylon.com/articles/6785045644-appointment-event-note-types).
There are a few things to note with this attribute:   
  1. If the `appointmentType` is an Other Event that does not require a patient, you must provide the `appointmentType` in the upload payload to pass validation.   
  2. For all appointments that require a patient, if the `appointmentType` attribute is omitted from the body completely on an update, the note type will stay as it already is in Canvas.  
  3. If the code / system pair does not exist, you will see a 422 error status with error message `Appointment Type does not exist with code: {code} and system: {system}`   
  4. If the code / system pair passed is not marked as `Is Scheduleable` in Canvas, you will get a 422 error status with error message `Note type: {name} is not scheduleable`.
Click to view child attributes
coding
array[json]
The type of appointment
Click to view child attributes
system
string
The system of the appointment. On create and update, only `http://snomed.info/sct` and `INTERNAL` are accepted; other systems will be rejected.
**Value Options Supported:**
  - http://snomed.info/sct
  - INTERNAL
code
string
The code of the appointment.   
This needs to match a coding in the Event and Note Types Canvas Settings and be deemed as Is Scheduleable.
reasonCode
array[json]
Coded reason this appointment is scheduled.   
Canvas supports two ways to specify the reason for vist (RFV): [structured](/sdk/data-reason-for-visit/#reasonforvisitsettingcoding) and unstructured. Both the `coding` and `text` attributes are used for Structured RFVs, whereas unstructured RFVs only leverage the `text` attribute.
On an update, if the reasonCode has changed from what is already saved in Canvas, it will create a new RFV command on that appointment. The old reason for visit will be marked as entered-in-error, and the text will no longer display. Below is an example of what an appointment's note will look like after changing the description multiple times. The originator and entered-in-error will be set to Canvas Bot, which can be seen if you click on the crossed off "Reason for Visit".  
![api-update-rfv](/assets/images/api-update-rfv.png)  
If this field is omitted (along with the deprecated `description` field), the RFV command in the appointment note will stay as it currently is.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
code
string
The code of the reason for visit.
text
string
description
string
Shown on a subject line in a meeting request, or appointment list.  
This description attribute is useful for Scheduled Events in Canvas that do no have a corresponding timeline entry.  
For appointments associated with a patient timeline entry, we strongly suggest using the `reasonCode` field to map to the Reason For Visit command in a Canvas Note. However, this descrition will match the reasonCode.text attribute in a Read/Search
supportingInformation
array[json] required
Additional information to support the appointment. Currently, Canvas supports the ability to write 2 different types of references:   
  1. `Location`: A reference to a Location captures what Practice Location in Canvas the appointment will take place at.  
  2. `Meeting Link`: For appointments that are telehealth in Canvas, there can be a reference to an endpoint in this list. The reference attribute will need to match an `id` in the `Appointment.contained` attribute list, but will need to have a `#` in front of the reference string. See examples for help. For telehealth appointments where no meeting link reference is supplied, it will default to the practitioner's personal meeting room link as defined in Canvas Settings.
Click to view child attributes
reference
string required
The reference string of the supporting information.
If the entry is for a Location the format will be `"Location/9d3a079f-22c0-4918-96d7-72eb567563ec"`. You can retrieve this information for a [Location Search](/api/location#search).  
If the entry is for a virtual meeting link, the reference should be `#appointment-meeting-endpoint-0`.
type
string
Type the reference refers to (e.g. "Location", "Endpoint", "Encounter", "Appointment").
start
datetime required
When appointment is to take place.
The `start` attribute determines the start timestamp of the appointment. It is written in [instant format for FHIR](https://www.hl7.org/fhir/datatypes.html#instant). Seconds and milliseconds can be omitted, but YYYY-MM-DDTHH:MM are required.
end
datetime required
When appointment is to conclude.
participant
array[json] required
Participants involved in appointment. At least one object needs to be supplied that corresponds to the practitioner, there will always be a practitioner involved in every appointment type. An optional 2nd object corresponding to the patient reference will be accepted if the `appointmentType` allows/requires a patient participant.
Click to view child attributes
actor
json required
Reference to person involved in appointment.
Click to view child attributes
reference
string required
The reference string of the practitioner or patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
While the patient is a required attribute, if you try to change the patient from what is already in Canvas, you will get the error message "Cannot change patient for an existing appointment. Please cancel this appointment and create a new one for the new patient."
**Value Options Supported:**
  - Practitioner/id
  - Patient/id
type
string
Type the reference refers to (e.g. "Patient", "Practitioner").
**Value Options Supported:**
  - Practitioner
  - Patient
status
enum [ accepted ] required
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Appointment
#### Appointment search
Search for an Appointment
### Query Parameters
****
_id
string
A Canvas-issued unique identifier for the Appointment.
appointment-type
string
Filters by the code and/or system under `appointmentType.coding` attribute. You can search by just the code value or you can search by the system and code in the format `system|code` (e.g `http://snomed.info/sct|308335008`).
identifier
string
Filters appointments by their external identifiers. You can search by just the identifier value or by using the format `system|value` (e.g. `NIST-MPI-1|171122`).
location
string
The location of the appointment in the format `Location/9d3a079f-22c0-4918-96d7-72eb567563ec`.
patient
string
The patient the appointment is for in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
practitioner
string
The practitioner involoved in the appointment in the format `Practitioner/3a9cafb9d1b445be95a2e2548e12a787`.
date
string
Filter by start time. See [Date Filtering](/api/date-filtering) for more information.
status
string
The status of the appointment. Accepts one value per request, so a comma-separated list of statuses is not supported. To retrieve appointments across several statuses, make one request per status and combine the results.
**Search Values Supported:**
  - proposed
  - pending
  - booked
  - arrived
  - checked-in
  - fulfilled
  - noshow
  - cancelled
_sort
string
Triggers sorting of the results by a specific criteria. Adding a `-` will sort in descending order while the default sorts in ascending order.
**Search Values Supported:**
  - date
  - patient
  - practitioner
  - -date
  - -patient
  - -practitioner
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the appointment.
contained
array[json]
Contained, inline Resources. Used to store links for telehealth appointments.
There will be a reference in the `supportingInformation` attribute with a `type` of `Endpoint` and a reference` of `#appointment-meeting-endpoint-0` that will match the `contained[0].id`.
Click to view child attributes
resourceType
enum [ Endpoint ]
id
string
The `id` of the contained entry. This needs to be `appointment-meeting-endpoint-0` and the SupportingInformation.reference will be `#appointment-meeting-endpoint-0`.
status
enum [ active ]
connectionType
json
Click to view child attributes
code
string
Protocol/Profile/Standard to be used with this endpoint connection
payloadType
array[json]
Click to view child attributes
coding
array[json]
Click to view child attributes
code
enum [ video-call ]
address
string
The technical base address for connecting to this endpoint.
extension
array[json]
Canvas supports a note identifier extension on this resource for read and search interactions. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
identifier
array[json]
External Ids for this item.   
The identifier list defines additional identifiers that are able to be stored for an appointment.  
These identifiers will not be surfaced on the Patient's chart, but they may help you identify the patient in your system by associating your identifier with the resource's `id`.
Click to view child attributes
id
string
Unique id for inter-element referencing
use
enum [ usual | official | temp | secondary | old ]
The purpose of this identifier. If this is omitted, it will default to `usual`.
system
string
The namespace for the identifier value.
value
string
The value that is unique
period
json
Time period when id is/was valid for use.
Click to view child attributes
start
datetime
Starting time with inclusive boundary. If omitted this will default to `1970-01-01`.
end
datetime
End time with inclusive boundary, if not ongoing. If ommitted this will default to `2100-12-31`.
status
enum [ arrived | booked | cancelled | checked-in | fulfilled | noshow | pending | proposed ]
The status of the appointment. The status `entered-in-error` may also be returned on read but is not accepted on create or update.   
This table shows the mappings of statuses/states an appointment is in within Canvas to the FHIR status attribute.   
FHIR Status| Canvas Status  
---|---  
proposed| unconfirmed  
pending| attempted  
booked| confirmed  
arrived| arrived  
checked-in| roomed  
fulfilled| exited  
noshow| noshowed  
cancelled| cancelled  
entered-in-error| deleted  
The first 7 statuses come from the dropdown on the Appointment Card in the Schedule view. A `cancelled` status comes from a patient appointment or an other event being cancelled. The `deleted/entered-in-error` status is when a checked-in appointment note has been deleted in Canvas.
appointmentType
json
The style of appointment or patient that has been booked in the slot (not service type). Canvas supports configurable [event and note types](https://canvas-medical.help.usepylon.com/articles/6785045644-appointment-event-note-types).
Click to view child attributes
coding
array[json]
The type of appointment
Click to view child attributes
system
string
The system of the appointment
**Value Options Supported:**
  - http://snomed.info/sct
  - INTERNAL
code
string
The code of the appointment.   
This needs to match a coding in the Event and Note Types Canvas Settings and be deemed as Is Scheduleable.
display
string
The display of the appointment
reasonCode
array[json]
Coded reason this appointment is scheduled.   
Canvas supports two ways to specify the reason for vist (RFV): [structured](/sdk/data-reason-for-visit/#reasonforvisitsettingcoding) and unstructured. Both the `coding` and `text` attributes are used for Structured RFVs, whereas unstructured RFVs only leverage the `text` attribute.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system of the coding.
code
string
The code of the reason for visit.
display
string
The display name of the coding.
userSelected
boolean
If this coding was chosen directly by the user. In Canvas this indicates if the coding is currently active or not.
text
string
description
string
Shown on a subject line in a meeting request, or appointment list.  
This description attribute is useful for Scheduled Events in Canvas that do no have a corresponding timeline entry.  
For appointments associated with a patient timeline entry, we strongly suggest using the `reasonCode` field to map to the Reason For Visit command in a Canvas Note. However, this descrition will match the reasonCode.text attribute in a Read/Search
supportingInformation
array[json]
Additional information to support the appointment. Currently, Canvas supports different types of references in this list:   
  1. `Location`: A reference to a Location captures what Practice Location in Canvas the appointment will take place at.  
  2. `Meeting Link`: For appointments that are telehealth in Canvas, there will be a reference to an endpoint in this list. The reference attribute will match an `id` in the `Appointment.contained` attribute list. That element will display the url address of the virtual meeting link.   
  3. `Appointment`: If an appointment has been rescheduled, this list could display an associated Appointment reference. If you see a display of `Previously Rescheduled Appointment`, it means that the appointment you are currently looking at was created after rescheduling the appointment in that Reference. If you see a display of `Rescheduled Replacement Appointment`, it means that the appointment you are currently looking at is now outdated by a new appointment. If you see a display of `Co-scheduled Appointment`, it means that the appointment you are currently looking at was scheduled with other additional associated appointments for which the appointment reference ID is noted.   
  4. `Encounter`: If there is any encounter associated with the appointment made in Canvas, the reference will appear in this list.
Click to view child attributes
reference
string
The reference string of the supporting information.
type
string
Type the reference refers to (e.g. "Location", "Endpoint", "Encounter", "Appointment").
display
string
Display name of the reference
**Value Options Supported:**
  - Previously Rescheduled Appointment
  - Rescheduled Replacement Appointment
  - Co-scheduled Appointment
start
datetime
When appointment is to take place.
end
datetime
When appointment is to conclude.
participant
array[json]
Participants involved in appointment. There will be at least one entry for a practitioner. An optional 2nd entry will display if the appointment involves a specific patient. This will be dictated by the `appointmentType` and if it relates to a generic event or a patient's appointment.
Click to view child attributes
actor
json
Reference to person involved in appointment.
Click to view child attributes
reference
string
The reference string of the practitioner or patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
**Value Options Supported:**
  - Practitioner/id
  - Patient/id
type
string
Type the reference refers to (e.g. "Patient", "Practitioner").
**Value Options Supported:**
  - Practitioner
  - Patient
status
enum [ accepted ]
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Appointment/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Appointment/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Appointment",
            "id": "621a66fc-9d5c-4de0-97fb-935d611ac176",
            "contained":
            [
                {
                    "resourceType": "Endpoint",
                    "id": "appointment-meeting-endpoint-0",
                    "status": "active",
                    "connectionType":
                    {
                        "code": "https"
                    },
                    "payloadType":
                    [
                        {
                            "coding":
                            [
                                {
                                    "code": "video-call"
                                }
                            ]
                        }
                    ],
                    "address": "https://url-for-video-chat.example.com?meeting=abc123"
                }
            ],
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "identifier": [
                {
                    "id": "97b28298-f618-4972-9a6b-d095785587d6",
                    "use": "usual",
                    "system": "AssigningSystem",
                    "value": "test123",
                    "period": {
                        "start": "2024-01-01",
                        "end": "2024-12-31"
                    }
                }
            ],
            "status": "proposed",
            "appointmentType":
            {
                "coding":
                [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "448337001",
                        "display": "Telemedicine"
                    }
                ]
            },
            "reasonCode":
            [
                {
                    "coding":
                    [
                        {
                            "system": "INTERNAL",
                            "code": "INIV",
                            "display": "Initial Visit",
                            "userSelected": false
                        }
                    ],
                    "text": "Initial 30 Minute Visit"
                }
            ],
            "description": "Initial 30 Minute Visit",
            "supportingInformation":
            [
                {
                    "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060",
                    "type": "Location"
                },
                {
                    "reference": "#appointment-meeting-endpoint-0",
                    "type": "Endpoint"
                },
                {
                    "reference": "Encounter/23668e1a-e914-4eac-885c-1a2a27244ab7",
                    "type": "Encounter"
                },
                {
                    "reference": "Appointment/7fa2874e-73c8-418d-bb25-eea0ccac651c",
                    "type": "Appointment",
                    "display": "Co-scheduled appointment"
                }
            ],
            "start": "2023-10-24T13:30:00+00:00",
            "end": "2023-10-24T14:00:00+00:00",
            "participant":
            [
                {
                    "actor":
                    {
                        "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                        "type": "Practitioner"
                    },
                    "status": "accepted"
                },
                {
                    "actor":
                    {
                        "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d",
                        "type": "Patient"
                    },
                    "status": "accepted"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Appointment resource 'a47c7b0ebbb442cdbc4adf259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Appointment?patient=Patient/a031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner/4150cd20de8a470aa570a852859ac87e' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Appointment?patient=Patient/a031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner/4150cd20de8a470aa570a852859ac87e"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link":
            [
                {
                    "relation": "self",
                    "url": "/Appointment?patient=Patient%2Fa031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner%2F4150cd20de8a470aa570a852859ac87e&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Appointment?patient=Patient%2Fa031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner%2F4150cd20de8a470aa570a852859ac87e&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Appointment?patient=Patient%2Fa031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner%2F4150cd20de8a470aa570a852859ac87e&_count=10&_offset=0"
                }
            ],
            "entry":
            [
                {
                    "resource":
                    {
                        "resourceType": "Appointment",
                        "id": "f7bb6d7e-1cab-42cd-b3d2-40229e1bede7",
                        "contained":
                        [
                            {
                                "resourceType": "Endpoint",
                                "id": "appointment-meeting-endpoint-0",
                                "status": "active",
                                "connectionType":
                                {
                                    "code": "https"
                                },
                                "payloadType":
                                [
                                    {
                                        "coding":
                                        [
                                            {
                                                "code": "video-call"
                                            }
                                        ]
                                    }
                                ],
                                "address": "https://url-for-video-chat.example.com?meeting=abc123"
                            }
                        ],
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                                "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                            }
                        ],
                        "identifier": [
                          {
                              "id": "97b28298-f618-4972-9a6b-d095785587d6",
                              "use": "usual",
                              "system": "AssigningSystem",
                              "value": "test123",
                              "period": {
                                  "start": "2024-01-01",
                                  "end": "2024-12-31"
                              }
                          }
                        ],
                        "status": "proposed",
                        "appointmentType":
                        {
                            "coding":
                            [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "448337001",
                                    "display": "Telemedicine"
                                }
                            ]
                        },
                        "reasonCode":
                        [
                            {
                                "coding":
                                [
                                    {
                                        "system": "INTERNAL",
                                        "code": "INIV",
                                        "display": "Initial Visit",
                                        "userSelected": false
                                    }
                                ],
                                "text": "Initial 30 Minute Visit"
                            }
                        ],
                        "description": "Initial 30 Minute Visit",
                        "supportingInformation":
                        [
                            {
                                "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060",
                                "type": "Location"
                            },
                            {
                                "reference": "#appointment-meeting-endpoint-0",
                                "type": "Endpoint"
                            },
                            {
                                "reference": "Encounter/797ccaae-2939-4e8a-9d91-5e9574a11a4e",
                                "type": "Encounter"
                            }
                        ],
                        "start": "2023-10-24T13:30:00+00:00",
                        "end": "2023-10-24T14:00:00+00:00",
                        "participant":
                        [
                            {
                                "actor":
                                {
                                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                    "type": "Practitioner"
                                },
                                "status": "accepted"
                            },
                            {
                                "actor":
                                {
                                    "reference": "Patient/a031d1ba40d74aebb8ed716716da05c2",
                                    "type": "Patient"
                                },
                                "status": "accepted"
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Appointment' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Appointment",
            "contained":
            [
                {
                    "resourceType": "Endpoint",
                    "id": "appointment-meeting-endpoint",
                    "status": "active",
                    "connectionType":
                    {
                        "code": "https"
                    },
                    "payloadType":
                    [
                        {
                            "coding":
                            [
                                {
                                    "code": "video-call"
                                }
                            ]
                        }
                    ],
                    "address": "https://url-for-video-chat.example.com?meeting=abc123"
                }
            ],
            "identifier": [
                {
                    "use": "usual",
                    "system": "AssigningSystem",
                    "value": "test123",
                    "period": {
                        "start": "2024-01-01",
                        "end": "2024-12-31"
                    }
                }
            ],
            "status": "proposed",
            "appointmentType":
            {
                "coding":
                [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "448337001",
                        "display": "Telemedicine consultation with patient (procedure)"
                    }
                ]
            },
            "reasonCode":
            [
                {
                    "coding":
                    [
                        {
                            "system": "INTERNAL",
                            "code": "INIV",
                            "display": "Initial Visit",
                            "userSelected": false
                        }
                    ],
                    "text": "Initial 30 Minute Visit"
                }
            ],
            "supportingInformation":
            [
                {
                    "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060"
                },
                {
                    "reference": "#appointment-meeting-endpoint",
                    "type": "Endpoint"
                }
            ],
            "start": "2023-10-24T13:30:00.000Z",
            "end": "2023-10-24T14:00:00.000Z",
            "participant":
            [
                {
                    "actor":
                    {
                        "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d"
                    },
                    "status": "accepted"
                },
                {
                    "actor":
                    {
                        "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e"
                    },
                    "status": "accepted"
                }
            ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Appointment"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Appointment",
            "contained":
            [
                {
                    "resourceType": "Endpoint",
                    "id": "appointment-meeting-endpoint",
                    "status": "active",
                    "connectionType":
                    {
                        "code": "https"
                    },
                    "payloadType":
                    [
                        {
                            "coding":
                            [
                                {
                                    "code": "video-call"
                                }
                            ]
                        }
                    ],
                    "address": "https://url-for-video-chat.example.com?meeting=abc123"
                }
            ],
            "identifier": [
              {
                  "use": "usual",
                  "system": "AssigningSystem",
                  "value": "test123",
                  "period": {
                      "start": "2024-01-01",
                      "end": "2024-12-31"
                  }
              }
            ],
            "status": "proposed",
            "appointmentType":
            {
                "coding":
                [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "448337001",
                        "display": "Telemedicine consultation with patient (procedure)"
                    }
                ]
            },
            "reasonCode":
            [
                {
                    "coding":
                    [
                        {
                            "system": "INTERNAL",
                            "code": "INIV",
                            "display": "Initial Visit",
                            "userSelected": False
                        }
                    ],
                    "text": "Initial 30 Minute Visit"
                }
            ],
            "supportingInformation":
            [
                {
                    "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060"
                },
                {
                    "reference": "#appointment-meeting-endpoint",
                    "type": "Endpoint"
                }
            ],
            "start": "2023-10-24T13:30:00.000Z",
            "end": "2023-10-24T14:00:00.000Z",
            "participant":
            [
                {
                    "actor":
                    {
                        "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d"
                    },
                    "status": "accepted"
                },
                {
                    "actor":
                    {
                        "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e"
                    },
                    "status": "accepted"
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/Appointment/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Appointment",
            "contained":
            [
                {
                    "resourceType": "Endpoint",
                    "id": "appointment-meeting-endpoint",
                    "status": "active",
                    "connectionType":
                    {
                        "code": "https"
                    },
                    "payloadType":
                    [
                        {
                            "coding":
                            [
                                {
                                    "code": "video-call"
                                }
                            ]
                        }
                    ],
                    "address": "https://url-for-video-chat.example.com?meeting=abc123"
                }
            ],
            "identifier": [
              {
                  "id": "97b28298-f618-4972-9a6b-d095785587d6",
                  "use": "usual",
                  "system": "AssigningSystem",
                  "value": "test123",
                  "period": {
                      "start": "2024-01-01",
                      "end": "2024-12-31"
                  }
              }
            ],
            "status": "cancelled",
            "appointmentType":
            {
                "coding":
                [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "448337001",
                        "display": "Telemedicine consultation with patient (procedure)"
                    }
                ]
            },
            "reasonCode":
            [
                {
                    "coding":
                    [
                        {
                            "system": "INTERNAL",
                            "code": "INIV",
                            "display": "Initial Visit",
                            "userSelected": false
                        }
                    ],
                    "text": "Initial 30 Minute Visit"
                }
            ],
            "supportingInformation":
            [
                {
                    "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060"
                },
                {
                    "reference": "#appointment-meeting-endpoint",
                    "type": "Endpoint"
                }
            ],
            "start": "2023-10-24T13:30:00.000Z",
            "end": "2023-10-24T14:00:00.000Z",
            "participant":
            [
                {
                    "actor":
                    {
                        "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d"
                    },
                    "status": "accepted"
                },
                {
                    "actor":
                    {
                        "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e"
                    },
                    "status": "accepted"
                }
            ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Appointment/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Appointment",
            "contained":
            [
                {
                    "resourceType": "Endpoint",
                    "id": "appointment-meeting-endpoint",
                    "status": "active",
                    "connectionType":
                    {
                        "code": "https"
                    },
                    "payloadType":
                    [
                        {
                            "coding":
                            [
                                {
                                    "code": "video-call"
                                }
                            ]
                        }
                    ],
                    "address": "https://url-for-video-chat.example.com?meeting=abc123"
                }
            ],
            "identifier": [
              {
                  "id": "97b28298-f618-4972-9a6b-d095785587d6",
                  "use": "usual",
                  "system": "AssigningSystem",
                  "value": "test123",
                  "period": {
                      "start": "2024-01-01",
                      "end": "2024-12-31"
                  }
              }
            ],
            "status": "cancelled",
            "appointmentType":
            {
                "coding":
                [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "448337001",
                        "display": "Telemedicine consultation with patient (procedure)"
                    }
                ]
            },
            "reasonCode":
            [
                {
                    "coding":
                    [
                        {
                            "system": "INTERNAL",
                            "code": "INIV",
                            "display": "Initial Visit",
                            "userSelected": False
                        }
                    ],
                    "text": "Initial 30 Minute Visit"
                }
            ],
            "supportingInformation":
            [
                {
                    "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060"
                },
                {
                    "reference": "#appointment-meeting-endpoint",
                    "type": "Endpoint"
                }
            ],
            "start": "2023-10-24T13:30:00.000Z",
            "end": "2023-10-24T14:00:00.000Z",
            "participant":
            [
                {
                    "actor":
                    {
                        "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d"
                    },
                    "status": "accepted"
                },
                {
                    "actor":
                    {
                        "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e"
                    },
                    "status": "accepted"
                }
            ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Appointment resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```

---

# Authentication - Best Practices

Source: https://docs.canvasmedical.com/api/authentication-best-practices/

##  Introduction 
The OAuth 2.0 authentication/authorization flow differs from the traditional username/password flow still heavily used in healthcare interoperability. To help users new to writing applications using OAuth, here are some best practices recommended by Canvas.
###  The Access Token: Don't lose it, reuse it 
####  Instead of this 
For some connections requiring a username and password, it may be necessary to use those credentials every time a message is sent to that system. In that type of flow, you might need to write something like:
    ```python
    import requests
    token = get_new_auth_token()
    patient = get_patient(token, patient_id)
    updated_patient_body = update_patient(patient, name="Frank")
    token = get_new_auth_token()
    update_patient(token, updated_patient_body)
    token = get_new_auth_token()
    schedule_appointment(token, patient=patient, type="telehealth")
    ...
    ```
Repeated, unnecessary calls to a token request function double the number of requests this script generates.
####  Do this 
Regardless of the authentication method used, a successful request includes `"expires_in": ` in the response body. The corresponding value will be an integer for the number of seconds until the token will be expired in Canvas. By reusing the token and eliminating redundant token requests, there is a **performance** gain from reducing the overall number of requests. The system is also more **secure** \- having fewer tokens reduces the overall surface area for illegitimate access
**General Guidelines:**
  - store the access token as securely as the client id and secret
  - depending on your use case, it may be best to store a token just for that session or to reuse it until it nears expiration
  - store the expiration datetime as well and check it before requesting a new token
  - use a refresh token if you provided in the authentication response for the authentication flow being used
There's any number of ways to do this in your language of choice. In Python, your code may look more like:
    ```python
    import os
    import requests
    from datetime import datetime, timedelta
    from urllib.parse import urlencode
    # we should get these from environment variables or a secure location at runtime, not in the code
    CLIENT_ID = os.getenv("CANVAS_API_CLIENT_ID")
    CLIENT_SECRET = os.getenv("CANVAS_API_CLIENT_SECRET")
    FUMAGE_BASE_URL = os.getenv("FUMAGE_BASE_URL")
    def get_new_auth_token():
        # Auth tokens are requested from the EMR instance, not the FHIR API.
        url = FUMAGE_BASE_URL.replace("fumage-", "")
        payload = urlencode(
            {
                "grant_type": "client_credentials",
                "client_id": f"{CLIENT_ID}",
                "client_secret": f"{CLIENT_SECRET}"
            }
        )
        headers = { "Content-Type": "application/x-www-form-urlencoded", }
        response = requests.post(f"{url}/auth/token/", headers=headers, data=payload)
        if response.status_code == 200:
            access_token = response.json()["access_token"]
            expiration_date = datetime.now() + timedelta(seconds=response.json()["expires_in"])
            os.environ["CANVAS_API_ACCESS_TOKEN"] = access_token
            os.environ["CANVAS_ACCESS_TOKEN_EXPIRATION_DATE"] = expiration_date.strftime("%m/%d/%y %H:%M:%S")
            return response.json()["access_token"]
        else:
            raise Exception(f"Could not acquire new auth token: {response.text}")
    if __name__ == '__main__':
        access_token = os.getenv("CANVAS_API_ACCESS_TOKEN")
        if expiration_date := os.getenv("CANVAS_ACCESS_TOKEN_EXPIRATION_DATE"):
            expiration_date = datetime.strptime(expiration_date, "%m/%d/%y %H:%M:%S")
        else:
            expiration_date = datetime.now()
         # only request a new token when we do not have a token or the one we have has expired
        if not access_token or expiration_date <= datetime.now():
            access_token = get_new_auth_token()
        headers = { "Authorization": f"Bearer {access_token}" }
        response = requests.get(f"{FUMAGE_BASE_URL}/Patient?name=Briddle", headers=headers)
        if response.status_code == 401:
            # attempt to acquire a new token 1 time if we get a 401 - maybe it was manually expired or
            # we have the wrong expiration date
            access_token = get_new_auth_token()
            headers = { "Authorization": f"Bearer {access_token}" }
            response = requests.get(f"{FUMAGE_BASE_URL}/Patient?name=Briddle", headers=headers)
            if response.status_code == 401:
                # limit retries but throw a specific exception for authentication related issues
                raise Exception(f"Cannot authenticate to Canvas after 1 retry: {response.text}")
            elif response.status_code != 200:
                # capture other issues as well
                raise Exception(f"{response.text}")
        patients = response.json()["entry"]
        for patient in patients:
            patient_id = patient["resource"]["id"]
            response = requests.get(f"{FUMAGE_BASE_URL}/Appointment?patient=Patient/{patient_id}", headers=headers)
            # do something with the appointments - save locally, modify and update, etc.
    ```
####  Takeaway 
  - **Safely stored access tokens can and should be reused!**  
  - Additional reading:
    - [Token Best Practices from Auth0](https://auth0.com/docs/secure/tokens/token-best-practices)
###  Keep access tokens and client secrets out of browser code 
If your application has a browser front end, never put your Canvas client ID and secret, or any access token, in client-side code. Anyone who can view the page source or watch its network traffic can read them, and a leaked client secret lets anyone request new tokens as your application. Canvas applications are registered as confidential clients, so the secret belongs on your server.
Keep the secret and tokens on your application's server, have the browser call your server, and have your server call the FHIR API.
Request tokens from `/auth/token/` on your server, using the flow that matches who the calls are for:
  - [Client credentials](/api/customer-authentication/#client-credentials), for calls your application makes on its own behalf.
  - [Authorization code](/api/customer-authentication/#authorization-code), for calls on behalf of a specific Canvas user. Store each user's refresh token in your backend, as in the [recommended pattern for external applications](/api/customer-authentication/#recommended-pattern-for-external-applications).
  - [Patient scoped tokens](/api/customer-authentication/#patient-scoped-tokens), for a patient-facing application, so that each token can read and write only one patient's records.
Reuse each access token until it expires rather than requesting a new one for every call, as described in The Access Token: Don't lose it, reuse it.
###  Resolving `access_denied` on the authorization code flow 
If the OAuth 2.0 authorization code flow returns `?error=access_denied` to your redirect URI even though login and scope selection succeed, the authorization server may be looking for a launch context (such as a patient) and not finding one. When no launch context exists, append `&launch=e30K` to your call to `/auth/authorize`. `e30K` is the base64 encoding of `{}` (an empty JSON object), which supplies an empty launch context and avoids the `access_denied` error.

---

# CarePlan

Source: https://docs.canvasmedical.com/api/careplan/

### 
Describes the intention of how one or more practitioners intend to deliver care for a particular patient, group or community for a period of time, possibly limited to care for a specific condition or set of conditions.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-careplan.html>  
A CarePlan in Canvas translates to the [Integrated Care Plan PDF](https://canvas-medical.help.usepylon.com/articles/8547508751-administrative-menu-integrated-care-plan) you can print on the patient's chart. This endpoint will return either one or zero care plans for each patient. If no care plan was returned for a given patient, then that patient has never had a Goal command committed on their chart.
### Endpoints
get/CarePlan/{id} get/CarePlan
get
/CarePlan/{id}
#### CarePlan read
Read a CarePlan resource.
### Path Parameters
id required
string
The unique identifier for the CarePlan   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the CarePlan.
text
json
Text summary of the resource, for human interpretation.
Click to view child attributes
status
All resources returned from this endpoint will show a status of `generated` since this resource is generated by Canvas.
div
Limited xhtml content that contains the human readable text of the resource.
status
enum [active]
Indicates whether the plan is currently being acted upon, represents future intentions or is now a historical record. Currently, this value will always return `active`.
intent
enum [plan]
Indicates the level of authority/intentionality associated with the care plan and where the care plan fits into the workflow chain. Currently, this value will always return `plan`.
category
array[json]
Type of plan.
Click to view child attributes
coding
array[json]
A CodeableConcept combination of one or more coding elements.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/CodeSystem/careplan-category
  - http://snomed.info/sct
code
string
The code of the category.
display
string
The display name of the coding.
subject
json
Who the care plan is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/CarePlan
#### CarePlan search
Search for CarePlan resources.
### Query Parameters
****
_id
string
The unique Canvas identifier of the CarePlan.
category
string
A category code in the format `system|code`.
**Search Values Supported:**
  - http://hl7.org/fhir/us/core/CodeSystem/careplan-category|assess-plan
  - http://snomed.info/sct|734163000
patient
string
The patient reference for who this care plan is for, in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
_revinclude
string
Standard FHIR `_revinclude` parameter.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the CarePlan.
text
json
Text summary of the resource, for human interpretation.
Click to view child attributes
status
All resources returned from this endpoint will show a status of `generated` since this resource is generated by Canvas.
div
Limited xhtml content that contains the human readable text of the resource.
status
enum [active]
Indicates whether the plan is currently being acted upon, represents future intentions or is now a historical record. Currently, this value will always return `active`.
intent
enum [plan]
Indicates the level of authority/intentionality associated with the care plan and where the care plan fits into the workflow chain. Currently, this value will always return `plan`.
category
array[json]
Type of plan.
Click to view child attributes
coding
array[json]
A CodeableConcept combination of one or more coding elements.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/CodeSystem/careplan-category
  - http://snomed.info/sct
code
string
The code of the category.
display
string
The display name of the coding.
subject
json
Who the care plan is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/CarePlan/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/CarePlan/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "CarePlan",
            "id": "b4190e86-1a63-4010-85fe-5c42b607d2f9",
            "text": {
                "status": "generated",
                "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><div class=\"hapiHeaderText\">CarePlan</div><table class=\"hapiPropertyTable\"><tbody><tr><td>Coding</td><td>{'system': 'http://snomed.info/sct', 'code': '734163000', 'display': 'Care plan'}</td></tr><tr><td>For Patient Name</td><td><span>Cube, Rubik N. (Nick Name)</span></td></tr></tbody></table></div>"
            },
            "status": "active",
            "intent": "plan",
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://hl7.org/fhir/us/core/CodeSystem/careplan-category",
                            "code": "assess-plan"
                        }
                    ]
                },
                {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "734163000",
                            "display": "Care plan"
                        }
                    ]
                }
            ],
            "subject": {
                "reference": "Patient/a1197fa9e65b4a5195af15e0234f61c2",
                "type": "Patient"
            }
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
            "resourceType": "OperationOutcome",
            "issue": [
                {
                    "severity": "error",
                    "code": "not-found",
                    "details": {
                        "text": "Unknown CarePlan resource '7d1ce256fcd7408193b0459650937a07'"
                    }
                }
            ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/CarePlan?patient=Patient/11430ad243f84ad2a47b1267d33ce9b8&category=http://hl7.org/fhir/us/core/CodeSystem/careplan-category|assess-plan' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/CarePlan?patient=Patient/11430ad243f84ad2a47b1267d33ce9b8&category=http://hl7.org/fhir/us/core/CodeSystem/careplan-category|assess-plan"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/CarePlan?patient=Patient/a1197fa9e65b4a5195af15e0234f61c2&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/CarePlan?patient=Patient/a1197fa9e65b4a5195af15e0234f61c2&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/CarePlan?patient=Patient/a1197fa9e65b4a5195af15e0234f61c2&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "CarePlan",
                        "id": "b4190e86-1a63-4010-85fe-5c42b607d2f9",
                        "text": {
                            "status": "generated",
                            "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><div class=\"hapiHeaderText\">CarePlan</div><table class=\"hapiPropertyTable\"><tbody><tr><td>Coding</td><td>{'system': 'http://snomed.info/sct', 'code': '734163000', 'display': 'Care plan'}</td></tr><tr><td>For Patient Name</td><td><span>Cube, Rubik N. (Nick Name)</span></td></tr></tbody></table></div>"
                        },
                        "status": "active",
                        "intent": "plan",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://hl7.org/fhir/us/core/CodeSystem/careplan-category",
                                        "code": "assess-plan"
                                    }
                                ]
                            },
                            {
                                "coding": [
                                    {
                                        "system": "http://snomed.info/sct",
                                        "code": "734163000",
                                        "display": "Care plan"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/a1197fa9e65b4a5195af15e0234f61c2",
                            "type": "Patient"
                        }
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# CareTeam

Source: https://docs.canvasmedical.com/api/careteam/

### 
The Care Team includes all the people and organizations who plan to participate in the coordination and delivery of care for a patient.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-careteam.html>  
All patients in Canvas have a CareTeam by default. The identifier for the CareTeam resource for a patient is the same as the patient identifier.   
See our [article](https://help.canvasmedical.com/articles/5628604712-manage-care-teams) for information about setting up Care Teams and Care Team Roles in Canvas.
### Endpoints
get/CareTeam/{id} put/CareTeam/{id} get/CareTeam
get
/CareTeam/{id}
#### CareTeam read
Read a CareTeam resource.
### Path Parameters
id required
string
The unique identifier for the CareTeam   
The default behavior is to return all active care team participants for the patient. To return care team participants of a different status, add `.status` at the end of the ID (e.g `CareTeam/3e72c07b5aac4dc5929948f82c9afdfd.inactive`).
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the CareTeam.
status
string
The current state of the care team.
**Value Options Supported:**
  - proposed
  - active
  - suspended
  - inactive
  - entered-in-error
name
string
Name of the team.   
This will always be set to `Care Team for <patient_last_name>, <patient_first_name>`
subject
json
Who care team is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
display
string
Display name of patient in the format `<patient_last_name>, <patient_first_name>`
participant
array[json]
Members of the team.  
Canvas allows either internal practitioners or external organizations to be members of a patient CareTeam. A practitioner can only have one role on a CareTeam, and only one practitioner can have a given role on a CareTeam. Organizations cannot be the lead of a CareTeam.   
Click to view child attributes
extension
array[json]
Canvas uses an extension to display whether a specific participant in a care team is the lead or not.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/careteam-lead
valueBoolean
boolean
Value of extension. If the value is set to `True`, it indicates the specific participant as the lead for this care team. Only one active participant can be the lead of a care team. Only practitioners can be designated as the lead.
role
array[json]
Type of involvement. Required for Practitioner participants; not present (and ignored) for Organization participants.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.   
Needs to match a Care Team Role that is defined in the Settings of the Canvas instance.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the care team role.
display
string
The display name of the coding.
member
json
Who is involved.
Click to view child attributes
reference
string
The reference string of the member in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"` or `"Organization/8ab7cc3c-86f5-4723-ba26-7baf1f906ec7"`.
type
string
Type the reference refers to (e.g. "Practitioner", "Organization").
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/CareTeam/{id}
#### CareTeam update
Update a CareTeam resource.  
The CareTeam update endpoint acts as an upsert, so there is no CareTeam `create` endpoint. Any participants included in the payload will be the patient's active care team participants. While any participants no longer included in the payload will be marked as `inactive`.   
**If-Unmodified-Since Header** :  
Due to a legacy design detail with the CareTeam implementation, there is a specific condition under which inclusion of this header will not produce expected results. In the case where all participants of a CareTeam are removed through the Canvas user interface (i.e. not through the FHIR API), the last modified date for the CareTeam will be equal to the last modified date of the patient record until another participant is added to the CareTeam.  
More information about the If-Unmodified-Since header can be found in the [Conditional Requests documentation](/api/conditional-requests/).
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The identifier of the CareTeam.
subject
json
Who care team is for.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
participant
array[json]
Members of the team.  
Canvas allows either internal practitioners or external organizations to be members of a patient CareTeam. A practitioner can only have one role on a CareTeam, and only one practitioner can have a given role on a CareTeam. Organizations cannot be the lead of a CareTeam.   
If `participant` is omitted or sent as an empty list, Canvas will inactivate any care team participants it finds for the given subject.
Click to view child attributes
extension
array[json]
Canvas supports the ability to mark a participant of a care team as the lead using a specific extension.   
If this extension is omitted, any current care team lead designated in Canvas will stay as the lead.
Click to view child attributes
url
string required
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/careteam-lead
valueBoolean
boolean required
Value of extension. If the value is set to `True`, it indicates the specific participant as the lead for this care team. Only one active participant can be the lead of a care team. Only practitioners can be designated as the lead.
role
array[json] required
Type of involvement. Required for Practitioner participants; not present (and ignored) for Organization participants.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.   
Needs to match a Care Team Role that is defined in the Settings of the Canvas instance.
Click to view child attributes
system
string required
The system url of the coding.
code
string required
The code of the care team role.
display
string required
The display name of the coding.
member
json required
Who is involved.
Click to view child attributes
reference
string required
The reference string of the member in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"` or `"Organization/8ab7cc3c-86f5-4723-ba26-7baf1f906ec7"`.
type
string
Type the reference refers to (e.g. "Practitioner", "Organization").
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/CareTeam
#### CareTeam search
Search for CareTeam resources.
### Query Parameters
****
participant
string
Who is involved.   
Search to find all patient care teams that with a specific Practitioner or Organization member. Use the format `"Practitioner/ed1e304acdb847148338c6b0596d93fd"` or `"Organization/8ab7cc3c-86f5-4723-ba26-7baf1f906ec7"`
patient
string
Search for a specific patient's care team in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
status
string
Search for care team participants of a patient by a specific status. If a status is not specified to search by, note the `id` in the response batch will end in `.status` for all care teams that are not active statuses.
**Search Values Supported:**
  - proposed
  - active
  - suspended
  - inactive
  - entered-in-error
_revinclude
string
Standard FHIR `_revinclude` parameter.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the CareTeam.
status
string
The current state of the care team.
**Value Options Supported:**
  - proposed
  - active
  - suspended
  - inactive
  - entered-in-error
name
string
Name of the team.   
This will always be set to `Care Team for <patient_last_name>, <patient_first_name>`
subject
json
Who care team is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
display
string
Display name of patient in the format `<patient_last_name>, <patient_first_name>`
participant
array[json]
Members of the team.  
Canvas allows either internal practitioners or external organizations to be members of a patient CareTeam. A practitioner can only have one role on a CareTeam, and only one practitioner can have a given role on a CareTeam. Organizations cannot be the lead of a CareTeam.   
Click to view child attributes
extension
array[json]
Canvas uses an extension to display whether a specific participant in a care team is the lead or not.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/careteam-lead
valueBoolean
boolean
Value of extension. If the value is set to `True`, it indicates the specific participant as the lead for this care team. Only one active participant can be the lead of a care team. Only practitioners can be designated as the lead.
role
array[json]
Type of involvement. Required for Practitioner participants; not present (and ignored) for Organization participants.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.   
Needs to match a Care Team Role that is defined in the Settings of the Canvas instance.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the care team role.
display
string
The display name of the coding.
member
json
Who is involved.
Click to view child attributes
reference
string
The reference string of the member in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"` or `"Organization/8ab7cc3c-86f5-4723-ba26-7baf1f906ec7"`.
type
string
Type the reference refers to (e.g. "Practitioner", "Organization").
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/CareTeam/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/CareTeam/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "CareTeam",
            "id": "8ab7cc3c86f54723ba267baf1f906ec7",
            "status": "active",
            "name": "Care Team for Amy V. Shaw",
            "subject": {
                "reference": "Patient/example",
                "type": "Patient",
                "display": "Amy V. Shaw"
            },
            "participant": [
                {
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                            "valueBoolean": true
                        }
                    ],
                    "role": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "17561000",
                                    "display": "Cardiologist"
                                }
                            ]
                        }
                    ],
                    "member": {
                        "reference": "Practitioner/c2ff4546548e46ab8959af887b563eab",
                        "display": "Ronald Bone, MD"
                    }
                },
                {
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                            "valueBoolean": false
                        }
                    ],
                    "role": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "453231000124104",
                                    "display": "Primary care provider"
                                }
                            ]
                        }
                    ],
                    "member": {
                        "reference": "Practitioner/fc87cbb2525f4c5eb50294f620c7a15e",
                        "display": "Kathy Fielding, MD"
                    }
                },
              {
                    "extension": [
                        {
                           "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                           "valueBoolean": false
                        }
                    ],
                    "member": {
                        "reference": "Organization/8ab7cc3c-86f5-4723-ba26-7baf1f906ec7",
                        "display": "Example Organization"
                    }
              }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown CareTeam resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/CareTeam/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "CareTeam",
            "id": "8ab7cc3c86f54723ba267baf1f906ec7",
            "status": "active",
            "name": "Care Team for Amy V. Shaw",
            "subject": {
                "reference": "Patient/8ab7cc3c86f54723ba267baf1f906ec7",
                "type": "Patient",
                "display": "Amy V. Shaw"
            },
            "participant": [
                {
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                            "valueBoolean": true
                        }
                    ],
                    "role": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "17561000",
                                    "display": "Cardiologist"
                                }
                            ]
                        }
                    ],
                    "member": {
                        "reference": "Practitioner/c2ff4546548e46ab8959af887b563eab",
                        "display": "Ronald Bone, MD"
                    }
                },
                {
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                            "valueBoolean": false
                        }
                    ],
                    "role": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "453231000124104",
                                    "display": "Primary care provider"
                                }
                            ]
                        }
                    ],
                    "member": {
                        "reference": "Practitioner/fc87cbb2525f4c5eb50294f620c7a15e",
                        "display": "Kathy Fielding, MD"
                    }
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/CareTeam/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "CareTeam",
            "id": "8ab7cc3c86f54723ba267baf1f906ec7",
            "status": "active",
            "name": "Care Team for Amy V. Shaw",
            "subject": {
                "reference": "Patient/8ab7cc3c86f54723ba267baf1f906ec7",
                "type": "Patient",
                "display": "Amy V. Shaw"
            },
            "participant": [
                {
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                            "valueBoolean": True
                        }
                    ],
                    "role": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "17561000",
                                    "display": "Cardiologist"
                                }
                            ]
                        }
                    ],
                    "member": {
                        "reference": "Practitioner/c2ff4546548e46ab8959af887b563eab",
                        "display": "Ronald Bone, MD"
                    }
                },
                {
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                            "valueBoolean": False
                        }
                    ],
                    "role": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "453231000124104",
                                    "display": "Primary care provider"
                                }
                            ]
                        }
                    ],
                    "member": {
                        "reference": "Practitioner/fc87cbb2525f4c5eb50294f620c7a15e",
                        "display": "Kathy Fielding, MD"
                    }
                }
            ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown CareTeam resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/CareTeam?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/CareTeam?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/CareTeam?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/CareTeam?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/CareTeam?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "CareTeam",
                        "id": "8ab7cc3c86f54723ba267baf1f906ec7",
                        "status": "active",
                        "name": "Care Team for Amy V. Shaw",
                        "subject": {
                            "reference": "Patient/8ab7cc3c86f54723ba267baf1f906ec7",
                            "type": "Patient",
                            "display": "Amy V. Shaw"
                        },
                        "participant": [
                            {
                                "extension": [
                                    {
                                        "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                                        "valueBoolean": true
                                    }
                                ],
                                "role": [
                                    {
                                        "coding": [
                                            {
                                                "system": "http://snomed.info/sct",
                                                "code": "17561000",
                                                "display": "Cardiologist"
                                            }
                                        ]
                                    }
                                ],
                                "member": {
                                    "reference": "Practitioner/c2ff4546548e46ab8959af887b563eab",
                                    "display": "Ronald Bone, MD"
                                }
                            },
                            {
                                "extension": [
                                    {
                                        "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                                        "valueBoolean": false
                                    }
                                ],
                                "role": [
                                    {
                                        "coding": [
                                            {
                                                "system": "http://snomed.info/sct",
                                                "code": "453231000124104",
                                                "display": "Primary care provider"
                                            }
                                        ]
                                    }
                                ],
                                "member": {
                                    "reference": "Practitioner/fc87cbb2525f4c5eb50294f620c7a15e",
                                    "display": "Kathy Fielding, MD"
                                }
                            },
                            {
                                  "extension": [
                                      {
                                         "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                                         "valueBoolean": false
                                      }
                                  ],
                                  "member": {
                                      "reference": "Organization/8ab7cc3c-86f5-4723-ba26-7baf1f906ec7",
                                      "display": "Example Organization"
                                  }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "CareTeam",
                        "id": "8ab7cc3c86f54723ba267baf1f906ec7.inactive",
                        "status": "inactive",
                        "name": "Care Team for Amy V. Shaw",
                        "subject": {
                            "reference": "Patient/8ab7cc3c86f54723ba267baf1f906ec7",
                            "type": "Patient",
                            "display": "Amy V. Shaw"
                        },
                        "participant": [
                            {
                                "extension": [
                                    {
                                        "url": "http://schemas.canvasmedical.com/fhir/extensions/careteam-lead",
                                        "valueBoolean": false
                                    }
                                ],
                                "role": [
                                    {
                                        "coding": [
                                            {
                                                "system": "http://snomed.info/sct",
                                                "code": "17561000",
                                                "display": "Cardiologist"
                                            }
                                        ]
                                    }
                                ],
                                "member": {
                                    "reference": "Practitioner/390769eb976546ceaefe2507effcc665",
                                    "type": "Practitioner",
                                    "display": "Pat Byrnes"
                                }
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Retrieving C-CDA via API

Source: https://docs.canvasmedical.com/api/ccda/

##  Software Requirements 
Software requirements for retrieving C-CDA via API calls can be found [here](/api/software-requirements)
##  Authentication 
If you have a Canvas Production instance, you will need to request a token and refresh it periodically. You can refer to our [Authentication Documentation](/api/customer-authentication) to get you set up.
If you use a [client credentials](/api/customer-authentication/#client-credentials) token, request it with the `system/*.*` scope. Canvas refuses a client credentials token with narrower scopes on this endpoint with `403 Forbidden`.
##  Request and Parameters 
In order to generate a CCDA for a known patient id, you'll need to do a GET request to the endpoint `{YOUR_EHR_INSTANCE}/api/data-export/ccda/{patient_id}?document={document_type}`, where `document_type` can be either `continuity` or `referral`. You can check all parameters in the table below.
Parameter Name| Description| Requirement  
---|---|---  
document| Document type to be generated.  
Should be either `continuity` or `referral`| Mandatory  
start_date| Filter for the start date of the sections within the document.  
Format should be `YYYY-MM-DD`| Optional  
end_date| Filter for the end date of the sections within the document.  
Format should be `YYYY-MM-DD`| Optional  
generation_date| Overrides the generation date of the document.  
Format should be `YYYY-MM-DDTHH:mm:ss`, in UTC timezone| Optional  
##  Filtering 
`start_date` and `end_date` filter can be used to:
  - filter by a range of dates by inputing both parameters;
  - filter by a single date in the past by making `start_date` and `end_date` the same;
  - filter starting at a date in the past up until present time by only setting `start_date`;
  - filter from the beginning of time up to any date by only setting `end_date`;
##  Example and Response 
Here's a cURL example of a request for a continuity of care document, filtered for 2020-01-01 to 2020-12-31, and with a generation date of 2022-01-01, at 16:30 UTC:
    ```shell
    curl --request GET --header "Authorization: Bearer <token>" "<practice_subdomain>.canvasmedical.com/api/data-export/ccda/{PATIENT_ID}?document=continuity&start_date=2024-01-01&end_date=2024-12-31&generation_date=2025-07-31T16:30:00"
    ```
A valid request will always return XML with the requested document as the response. If the `document` param is omitted, an empty XML will be returned.
##  Errors 
Canvas uses conventional HTTP response codes to indicate success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a request wasn't found, etc.). Codes in the 5xx range indicate an error with Canvas' server.
Error| Description  
---|---  
200 - OK| Everything worked as expected.  
403 - Forbidden| No valid Bearer token provided.  
404 - Not Found| The requested resource doesn't exist.  
500 - Server Error| Something went wrong on Canvas's end.

---

# Claim Operations

Source: https://docs.canvasmedical.com/api/claim-operations/

##  add-activity-log-item 
Add an activity log item to a Claim.  
This endpoint is a [FHIR operation](https://hl7.org/fhir/R4/operations.html), so it accepts a [Parameters](https://hl7.org/fhir/R4/parameters.html) resource in the request body. It will accept one and only one parameter, which must have the name **comment**. The comment that will be added is provided as a `valueString`. See the request example for more detail.
The bearer token included in requests send to this endpoint must have one of the following scopes:
  - `system/Claim.add-activity-log-item`
  - `user/Claim.add-activity-log-item`
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Claim/<id>/$add-activity-log-item' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Parameters",
            "parameter": [
                {
                    "name": "comment",
                    "valueString": "Test comment"
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Claim/<id>/$add-activity-log-item"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Parameters",
            "parameter": [
                {
                    "name": "comment",
                    "valueString": "Test comment"
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```

---

# Claim

Source: https://docs.canvasmedical.com/api/claim/

### 
A provider issued list of professional services and products which have been provided, or are to be provided, to a patient which is sent to an insurer for reimbursement.  
<http://hl7.org/fhir/R4/claim.html>
### Endpoints
post/Claim get/Claim/{id} put/Claim/{id} get/Claim
post
/Claim
#### Claim create
Create a Claim resource.
### Attributes
resourceType
string
The FHIR Resource name.
extension
array[json]
Canvas supports a current queue extension representing the current queue the given claim is in on the Canvas instance. Learn more about navigating claim queues [here](https://canvas-medical.help.usepylon.com/articles/3240845520-queues).  
**Canvas Built-in Claim Queues**
display| code  
---|---  
Adjudicated| AdjudicatedOpenBalance  
Appointment| Appointment  
Clinician| NeedsClinicianReview  
Coding| NeedsCodingReview  
Filed| FiledAwaitingResponse  
History| ZeroBalance  
Patient| PatientBalance  
Rejected| RejectedNeedsReview  
Submission| QueuedForSubmission  
Trash| Trash  
It is possible to create custom queues in Canvas and utilize in the FHIR API.
By default, a claim is created in the **NeedsCodingReview** queue in Canvas.  
Sending a different value in this extension updates the claim to be in that queue.
Click to view child attributes
url
string required
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/claim-queue
valueCoding
json required
Value of extension.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://canvasmedical.com
code
string required
**Value Options Supported:**
  - NeedsClinicianReview
  - NeedsCodingReview
  - QueuedForSubmission
  - FiledAwaitingResponse
  - RejectedNeedsReview
  - AdjudicatedOpenBalance
  - PatientBalance
  - ZeroBalance
  - Trash
  - Appointment
display
string
The display name of the coding.
**Value Options Supported:**
  - Adjudicated
  - Appointment
  - Clinician
  - Coding
  - Filed
  - History
  - Patient
  - Rejected
  - Submission
  - Trash
status
enum [ active ] required
The status of the resource instance.
type
json required
The category of claim.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/claim-type
  - http://hl7.org/fhir/ValueSet/claim-type
code
string required
The code.
**Value Options Supported:**
  - professional
display
string
The display name of the coding.
**Value Options Supported:**
  - Professional
use
enum [ claim ] required
A code to indicate the nature of the request.
patient
json required
The Canvas patient resource for the claim.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
datetime [ YYYY-MM-DDTHH:mm:ssZZ | YYYY-MM-DD ] required
The date this resource was created. If only a date is specified, it will default to midnight UTC. If a timezone is not supplied, it will default to use UTC.  
This maps to the date of service for note in Canvas the claims is associated with.
provider
json required
Party responsible for the claim. This will be a reference to a Practitioner.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Practitioner/bb24f084e1fa46c7931663259540266d"`.
type
string
Type the reference refers to (e.g. "Practitioner").
priority
json required
The provider-required urgency of processing the request.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/process-priority
  - http://terminology.hl7.org/CodeSystem/processpriority
code
string required
The code.
**Value Options Supported:**
  - normal
display
string
The display name of the coding.
**Value Options Supported:**
  - Normal
supportingInfo
array[json]
Additional information about the Claim.  
Canvas supports a single iteration for a reason for visit - the text in the `valueString` will be the note's RFV the claim is associated with.
Click to view child attributes
sequence
positive integer required
Information instance identifier. Most likely will be `1` since Canvas currently only accepts one SupportingInfo object.
category
json required
Classification of the supplied information.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/claim-informationcategory
  - http://terminology.hl7.org/CodeSystem/claiminformationcategory
code
string required
The code.
**Value Options Supported:**
  - patientreasonforvisit
display
string
The display name of the coding.
**Value Options Supported:**
  - Patient Reason for Visit
valueString
string
Data to be provided.  
Canvas supports free text to be passed as the reason for visit associated with the claim.
diagnosis
array[json] required
Information about diagnoses relevant to the claim items.
These diagnoses will create Assessments in Canvas. At least one diagnosis element is required.
Click to view child attributes
sequence
positive integer required
Diagnosis instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
diagnosisCodeableConcept
json required
Nature of illness or problem.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/icd-10
  - http://hl7.org/fhir/sid/icd-10-cm
code
string required
The ICD10 code. Canvas will automatically add the `.` when displaying in the UI (e.g the code 'H9190' is for the ICD10 H91.90 for unspecified hearing loss in an unspecified ear)
display
string
The display name of the coding.
insurance
array[json] required
Patient insurance information. Contains the list of coverage's associated with the claim in Canvas.
If the claim should be a self paying claim, pass the insurance list as
    ```json
      "insurance": [
          {
              "sequence": 1,
              "focal": false,
              "coverage": {
                  "display": "No Coverage"
              }
          }
      ]
    ```
Click to view child attributes
focal
boolean required
Coverage to be used for adjudication.
Canvas will ignore any elements that are set to False. For a self-pay claim, send a single `"No Coverage"` entry with no `coverage.reference` and `focal` set to `false`. If that entry has `focal` set to `true`, the claim is not created.
sequence
positive integer required
Insurance instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
coverage
json required
Insurance Information
Click to view child attributes
reference
string
The reference string of the coverage in the format of `"Coverage/05274c93-341c-4d23-9e46-718f6743609f"`.
display
string
A display of `"No Coverage"` are for claims that are self pay.
**Value Options Supported:**
  - No Coverage
item
array[json] required
List of service charges to be used in the claim.
Click to view child attributes
sequence
positive integer required
Item instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
diagnosisSequence
array[positive integer] required
Applicable diagnoses. This list of integers corresponds one or more diagnoses in the `Claim.diagnosis` list that this service charge is associated with.
productOrService
json required
Billing, service, product, or drug code.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/ValueSet/us-core-procedure-code
  - http://www.ama-assn.org/go/cpt
code
string required
The code.
display
string required
The display name of the coding.
quantity
json required
Count of products or services.
Click to view child attributes
value
integer
Numerical value.
unitPrice
json required
Fee, charge or cost per item.
Click to view child attributes
value
integer
Numerical value (with implicit precision)
modifier
array[json]
Product or service billing modifiers.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/carin-bb/ValueSet/AMACPTCMSHCPCSModifiers
  - https://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets
code
string required
The code.
display
string
The display name of the coding.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Claim/{id}
#### Claim read
Read a Claim resource.
### Path Parameters
id required
string
The unique identifier for the Claim   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Claim.
extension
array[json]
Canvas supports a current queue extension representing the current queue the given claim is in on the Canvas instance. Learn more about navigating claim queues [here](https://canvas-medical.help.usepylon.com/articles/3240845520-queues).  
**Canvas Built-in Claim Queues**
display| code  
---|---  
Adjudicated| AdjudicatedOpenBalance  
Appointment| Appointment  
Clinician| NeedsClinicianReview  
Coding| NeedsCodingReview  
Filed| FiledAwaitingResponse  
History| ZeroBalance  
Patient| PatientBalance  
Rejected| RejectedNeedsReview  
Submission| QueuedForSubmission  
Trash| Trash  
It is possible to create custom queues in Canvas and utilize in the FHIR API.
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note)   
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/claim-queue
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueCoding
json
Value of extension.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://canvasmedical.com
code
string
**Value Options Supported:**
  - NeedsClinicianReview
  - NeedsCodingReview
  - QueuedForSubmission
  - FiledAwaitingResponse
  - RejectedNeedsReview
  - AdjudicatedOpenBalance
  - PatientBalance
  - ZeroBalance
  - Trash
  - Appointment
display
string
The display name of the coding.
**Value Options Supported:**
  - Adjudicated
  - Appointment
  - Clinician
  - Coding
  - Filed
  - History
  - Patient
  - Rejected
  - Submission
  - Trash
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
status
enum [ active ]
The status of the resource instance.
type
json
The category of claim.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/claim-type
  - http://hl7.org/fhir/ValueSet/claim-type
code
string
The code.
**Value Options Supported:**
  - professional
display
string
The display name of the coding.
**Value Options Supported:**
  - Professional
use
enum [ claim ]
A code to indicate the nature of the request.
patient
json
The Canvas patient resource for the claim.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
datetime [ YYYY-MM-DDTHH:mm:ssZZ | YYYY-MM-DD ]
The date this resource was created. If only a date is specified, it will default to midnight UTC. If a timezone is not supplied, it will default to use UTC.  
This maps to the date of service for note in Canvas the claims is associated with.
provider
json
Party responsible for the claim. This will be a reference to a Practitioner.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Practitioner/bb24f084e1fa46c7931663259540266d"`.
type
string
Type the reference refers to (e.g. "Practitioner").
priority
json
The provider-required urgency of processing the request.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/process-priority
  - http://terminology.hl7.org/CodeSystem/processpriority
code
string
The code.
**Value Options Supported:**
  - normal
display
string
The display name of the coding.
**Value Options Supported:**
  - Normal
supportingInfo
array[json]
Additional information about the Claim.  
Canvas supports a single iteration for a reason for visit - the text in the `valueString` will be the note's RFV the claim is associated with.
Click to view child attributes
sequence
positive integer
Information instance identifier. Most likely will be `1` since Canvas currently only accepts one SupportingInfo object.
category
json
Classification of the supplied information.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/claim-informationcategory
  - http://terminology.hl7.org/CodeSystem/claiminformationcategory
code
string
The code.
**Value Options Supported:**
  - patientreasonforvisit
display
string
The display name of the coding.
**Value Options Supported:**
  - Patient Reason for Visit
valueString
string
Data to be provided.  
Canvas supports free text to be passed as the reason for visit associated with the claim.
diagnosis
array[json]
Information about diagnoses relevant to the claim items.
Click to view child attributes
sequence
positive integer
Diagnosis instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
diagnosisCodeableConcept
json
Nature of illness or problem.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/icd-10
  - http://hl7.org/fhir/sid/icd-10-cm
code
string
The ICD10 code. Canvas will automatically add the `.` when displaying in the UI (e.g the code 'H9190' is for the ICD10 H91.90 for unspecified hearing loss in an unspecified ear)
display
string
The display name of the coding.
insurance
array[json]
Patient insurance information. Contains the list of coverage's associated with the claim in Canvas.
Click to view child attributes
focal
boolean
Coverage to be used for adjudication.
Only insurance objects with `focal` as True will be returned in a Search/Read.
sequence
positive integer
Insurance instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
coverage
json
Insurance Information
Click to view child attributes
reference
string
The reference string of the coverage in the format of `"Coverage/05274c93-341c-4d23-9e46-718f6743609f"`.
display
string
A display of `"No Coverage"` are for claims that are self pay.
**Value Options Supported:**
  - No Coverage
item
array[json]
List of service charges to be used in the claim.
Click to view child attributes
sequence
positive integer
Item instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
diagnosisSequence
array[positive integer]
Applicable diagnoses. This list of integers corresponds one or more diagnoses in the `Claim.diagnosis` list that this service charge is associated with.
productOrService
json
Billing, service, product, or drug code.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/ValueSet/us-core-procedure-code
  - http://www.ama-assn.org/go/cpt
code
string
The code.
display
string
The display name of the coding.
quantity
json
Count of products or services.
Click to view child attributes
value
integer
Numerical value.
unitPrice
json
Fee, charge or cost per item.
Click to view child attributes
value
integer
Numerical value (with implicit precision)
encounter
array[json]
Encounters related to this billed item.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/879b35fd-3bc2-4ccd-98d7-954dd9b6d0a9"`.
type
string
Type the reference refers to (e.g. "Encounter").
modifier
array[json]
Product or service billing modifiers.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/carin-bb/ValueSet/AMACPTCMSHCPCSModifiers
  - https://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets
code
string
The code.
display
string
The display name of the coding.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Claim/{id}
#### Claim update
Update a Claim resource.  
**The only Claim update supported by Canvas is to change an existing Claim's queue. Changes to other fields will be ignored, but required fields must still be valued.**
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The identifier of the Claim.
extension
array[json]
Canvas supports a current queue extension representing the current queue the given claim is in on the Canvas instance. Learn more about navigating claim queues [here](https://canvas-medical.help.usepylon.com/articles/3240845520-queues).  
**Canvas Built-in Claim Queues**
display| code  
---|---  
Adjudicated| AdjudicatedOpenBalance  
Appointment| Appointment  
Clinician| NeedsClinicianReview  
Coding| NeedsCodingReview  
Filed| FiledAwaitingResponse  
History| ZeroBalance  
Patient| PatientBalance  
Rejected| RejectedNeedsReview  
Submission| QueuedForSubmission  
Trash| Trash  
It is possible to create custom queues in Canvas and utilize in the FHIR API.
By default, a claim is created in the **NeedsCodingReview** queue in Canvas.  
Sending a different value in this extension updates the claim to be in that queue.
Click to view child attributes
url
string required
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/claim-queue
valueCoding
json required
Value of extension.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://canvasmedical.com
code
string required
**Value Options Supported:**
  - NeedsClinicianReview
  - NeedsCodingReview
  - QueuedForSubmission
  - FiledAwaitingResponse
  - RejectedNeedsReview
  - AdjudicatedOpenBalance
  - PatientBalance
  - ZeroBalance
  - Trash
  - Appointment
display
string
The display name of the coding.
**Value Options Supported:**
  - Adjudicated
  - Appointment
  - Clinician
  - Coding
  - Filed
  - History
  - Patient
  - Rejected
  - Submission
  - Trash
status
enum [ active ] required
The status of the resource instance.
type
json required
The category of claim.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/claim-type
  - http://hl7.org/fhir/ValueSet/claim-type
code
string required
The code.
**Value Options Supported:**
  - professional
display
string
The display name of the coding.
**Value Options Supported:**
  - Professional
use
enum [ claim ] required
A code to indicate the nature of the request.
patient
json required
The Canvas patient resource for the claim.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
datetime [ YYYY-MM-DDTHH:mm:ssZZ | YYYY-MM-DD ] required
The date this resource was created. If only a date is specified, it will default to midnight UTC. If a timezone is not supplied, it will default to use UTC.  
This maps to the date of service for note in Canvas the claims is associated with.
provider
json required
Party responsible for the claim. This will be a reference to a Practitioner.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Practitioner/bb24f084e1fa46c7931663259540266d"`.
type
string
Type the reference refers to (e.g. "Practitioner").
priority
json required
The provider-required urgency of processing the request.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/process-priority
  - http://terminology.hl7.org/CodeSystem/processpriority
code
string required
The code.
**Value Options Supported:**
  - normal
display
string
The display name of the coding.
**Value Options Supported:**
  - Normal
supportingInfo
array[json]
Additional information about the Claim.  
Canvas supports a single iteration for a reason for visit - the text in the `valueString` will be the note's RFV the claim is associated with.
Click to view child attributes
sequence
positive integer required
Information instance identifier. Most likely will be `1` since Canvas currently only accepts one SupportingInfo object.
category
json required
Classification of the supplied information.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/claim-informationcategory
  - http://terminology.hl7.org/CodeSystem/claiminformationcategory
code
string required
The code.
**Value Options Supported:**
  - patientreasonforvisit
display
string
The display name of the coding.
**Value Options Supported:**
  - Patient Reason for Visit
valueString
string
Data to be provided.  
Canvas supports free text to be passed as the reason for visit associated with the claim.
diagnosis
array[json]
Information about diagnoses relevant to the claim items.
These diagnoses will create Assessments in Canvas. At least one diagnosis element is required.
Click to view child attributes
sequence
positive integer
Diagnosis instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
diagnosisCodeableConcept
json
Nature of illness or problem.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/icd-10
  - http://hl7.org/fhir/sid/icd-10-cm
code
string
The ICD10 code. Canvas will automatically add the `.` when displaying in the UI (e.g the code 'H9190' is for the ICD10 H91.90 for unspecified hearing loss in an unspecified ear)
display
string
The display name of the coding.
insurance
array[json] required
Patient insurance information. Contains the list of coverage's associated with the claim in Canvas.
If the claim should be a self paying claim, pass the insurance list as
    ```json
      "insurance": [
          {
              "sequence": 1,
              "focal": false,
              "coverage": {
                  "display": "No Coverage"
              }
          }
      ]
    ```
Click to view child attributes
focal
boolean required
Coverage to be used for adjudication.
Canvas will ignore any elements that are set to False. For a self-pay claim, send a single `"No Coverage"` entry with no `coverage.reference` and `focal` set to `false`. If that entry has `focal` set to `true`, the claim is not created.
sequence
positive integer required
Insurance instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
coverage
json required
Insurance Information
Click to view child attributes
reference
string
The reference string of the coverage in the format of `"Coverage/05274c93-341c-4d23-9e46-718f6743609f"`.
display
string
A display of `"No Coverage"` are for claims that are self pay.
**Value Options Supported:**
  - No Coverage
item
array[json]
List of service charges to be used in the claim.
Click to view child attributes
sequence
positive integer required
Item instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
diagnosisSequence
array[positive integer]
Applicable diagnoses. This list of integers corresponds one or more diagnoses in the `Claim.diagnosis` list that this service charge is associated with.
productOrService
json required
Billing, service, product, or drug code.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/ValueSet/us-core-procedure-code
  - http://www.ama-assn.org/go/cpt
code
string required
The code.
display
string required
The display name of the coding.
quantity
json
Count of products or services.
Click to view child attributes
value
integer
Numerical value.
unitPrice
json
Fee, charge or cost per item.
Click to view child attributes
value
integer
Numerical value (with implicit precision)
modifier
array[json]
Product or service billing modifiers.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/carin-bb/ValueSet/AMACPTCMSHCPCSModifiers
  - https://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets
code
string required
The code.
display
string
The display name of the coding.
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Claim
#### Claim search
Search for Claim resources.
### Query Parameters
****
_id
string
The Canvas resource identifier of the Claim
created
date
Filter by `created`, which is the date of service of the note the claim is associated with. Use this parameter to retrieve only claims within a date range, such as claims added since your last sync. See [Date Filtering](/api/date-filtering) for more information.
patient
string
The patient reference associated to the Claim in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Claim.
extension
array[json]
Canvas supports a current queue extension representing the current queue the given claim is in on the Canvas instance. Learn more about navigating claim queues [here](https://canvas-medical.help.usepylon.com/articles/3240845520-queues).  
**Canvas Built-in Claim Queues**
display| code  
---|---  
Adjudicated| AdjudicatedOpenBalance  
Appointment| Appointment  
Clinician| NeedsClinicianReview  
Coding| NeedsCodingReview  
Filed| FiledAwaitingResponse  
History| ZeroBalance  
Patient| PatientBalance  
Rejected| RejectedNeedsReview  
Submission| QueuedForSubmission  
Trash| Trash  
It is possible to create custom queues in Canvas and utilize in the FHIR API.
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note)   
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/claim-queue
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueCoding
json
Value of extension.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://canvasmedical.com
code
string
**Value Options Supported:**
  - NeedsClinicianReview
  - NeedsCodingReview
  - QueuedForSubmission
  - FiledAwaitingResponse
  - RejectedNeedsReview
  - AdjudicatedOpenBalance
  - PatientBalance
  - ZeroBalance
  - Trash
  - Appointment
display
string
The display name of the coding.
**Value Options Supported:**
  - Adjudicated
  - Appointment
  - Clinician
  - Coding
  - Filed
  - History
  - Patient
  - Rejected
  - Submission
  - Trash
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
status
enum [ active ]
The status of the resource instance.
type
json
The category of claim.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/claim-type
  - http://hl7.org/fhir/ValueSet/claim-type
code
string
The code.
**Value Options Supported:**
  - professional
display
string
The display name of the coding.
**Value Options Supported:**
  - Professional
use
enum [ claim ]
A code to indicate the nature of the request.
patient
json
The Canvas patient resource for the claim.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
datetime [ YYYY-MM-DDTHH:mm:ssZZ | YYYY-MM-DD ]
The date this resource was created. If only a date is specified, it will default to midnight UTC. If a timezone is not supplied, it will default to use UTC.  
This maps to the date of service for note in Canvas the claims is associated with.
provider
json
Party responsible for the claim. This will be a reference to a Practitioner.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Practitioner/bb24f084e1fa46c7931663259540266d"`.
type
string
Type the reference refers to (e.g. "Practitioner").
priority
json
The provider-required urgency of processing the request.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/process-priority
  - http://terminology.hl7.org/CodeSystem/processpriority
code
string
The code.
**Value Options Supported:**
  - normal
display
string
The display name of the coding.
**Value Options Supported:**
  - Normal
supportingInfo
array[json]
Additional information about the Claim.  
Canvas supports a single iteration for a reason for visit - the text in the `valueString` will be the note's RFV the claim is associated with.
Click to view child attributes
sequence
positive integer
Information instance identifier. Most likely will be `1` since Canvas currently only accepts one SupportingInfo object.
category
json
Classification of the supplied information.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/claim-informationcategory
  - http://terminology.hl7.org/CodeSystem/claiminformationcategory
code
string
The code.
**Value Options Supported:**
  - patientreasonforvisit
display
string
The display name of the coding.
**Value Options Supported:**
  - Patient Reason for Visit
valueString
string
Data to be provided.  
Canvas supports free text to be passed as the reason for visit associated with the claim.
diagnosis
array[json]
Information about diagnoses relevant to the claim items.
Click to view child attributes
sequence
positive integer
Diagnosis instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
diagnosisCodeableConcept
json
Nature of illness or problem.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/ValueSet/icd-10
  - http://hl7.org/fhir/sid/icd-10-cm
code
string
The ICD10 code. Canvas will automatically add the `.` when displaying in the UI (e.g the code 'H9190' is for the ICD10 H91.90 for unspecified hearing loss in an unspecified ear)
display
string
The display name of the coding.
insurance
array[json]
Patient insurance information. Contains the list of coverage's associated with the claim in Canvas.
Click to view child attributes
focal
boolean
Coverage to be used for adjudication.
Only insurance objects with `focal` as True will be returned in a Search/Read.
sequence
positive integer
Insurance instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
coverage
json
Insurance Information
Click to view child attributes
reference
string
The reference string of the coverage in the format of `"Coverage/05274c93-341c-4d23-9e46-718f6743609f"`.
display
string
A display of `"No Coverage"` are for claims that are self pay.
**Value Options Supported:**
  - No Coverage
item
array[json]
List of service charges to be used in the claim.
Click to view child attributes
sequence
positive integer
Item instance identifier.  
The `sequence` should be unique within the Claim message, usually starting at 1 and incrementing as needed.
diagnosisSequence
array[positive integer]
Applicable diagnoses. This list of integers corresponds one or more diagnoses in the `Claim.diagnosis` list that this service charge is associated with.
productOrService
json
Billing, service, product, or drug code.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/ValueSet/us-core-procedure-code
  - http://www.ama-assn.org/go/cpt
code
string
The code.
display
string
The display name of the coding.
quantity
json
Count of products or services.
Click to view child attributes
value
integer
Numerical value.
unitPrice
json
Fee, charge or cost per item.
Click to view child attributes
value
integer
Numerical value (with implicit precision)
encounter
array[json]
Encounters related to this billed item.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/879b35fd-3bc2-4ccd-98d7-954dd9b6d0a9"`.
type
string
Type the reference refers to (e.g. "Encounter").
modifier
array[json]
Product or service billing modifiers.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/us/carin-bb/ValueSet/AMACPTCMSHCPCSModifiers
  - https://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets
code
string
The code.
display
string
The display name of the coding.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
            --url 'https://fumage-example.canvasmedical.com/Claim' \
            --header 'Authorization: Bearer <token>' \
            --header 'accept: application/json' \
            --header 'content-type: application/json' \
            --data '
        {
          "resourceType": "Claim",
          "extension": [
            {
              "url": "http://schemas.canvasmedical.com/fhir/extensions/claim-queue",
              "valueCoding": {
                  "system": "http://canvasmedical.com",
                  "code": "NeedsClinicianReview",
                  "display": "Clinician"
              }
            }
          ],
          "status": "active",
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/claim-type",
                "code": "professional"
              }
            ]
          },
          "use": "claim",
          "patient": {
            "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
            "type": "Patient"
          },
          "created": "2021-08-16",
          "provider": {
            "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
            "type": "Practitioner"
          },
          "priority": {
            "coding": [
              {
                "code": "normal",
                "system": "http://terminology.hl7.org/CodeSystem/processpriority"
              }
            ]
          },
          "supportingInfo": [
            {
              "sequence": 1,
              "category": {
                "coding": [
                  {
                    "code": "patientreasonforvisit",
                    "system": "http://terminology.hl7.org/CodeSystem/claiminformationcategory",
                    "display": "Patient Reason for Visit"
                  }
                ]
              },
              "valueString": "This is only...a test"
            }
          ],
          "diagnosis": [
            {
              "sequence": 1,
              "diagnosisCodeableConcept": {
                "coding": [
                  {
                    "code": "F41.1",
                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                    "display": "Generalized anxiety"
                  }
                ]
              }
            }
          ],
          "insurance": [
            {
              "sequence": 1,
              "focal": true,
              "coverage": {
                "reference": "Coverage/02d4f77a-ebaf-47d5-b162-6313244aed5f"
              }
            }
          ],
          "item": [
            {
              "sequence": 1,
              "diagnosisSequence": [
                1
              ],
              "productOrService": {
                "coding": [
                  {
                    "system": "http://www.ama-assn.org/go/cpt",
                    "code": "exam",
                    "display": "Office visit"
                  }
                ]
              },
              "modifier": [
                {
                  "coding": [
                    {
                      "system": "https://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
                      "code": "21"
                    }
                  ]
                }
              ],
              "quantity": {
                "value": 1
              },
              "unitPrice": {
                "value": 75
              }
            }
          ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Claim"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
          "resourceType": "Claim",
          "extension": [
            {
              "url": "http://schemas.canvasmedical.com/fhir/extensions/claim-queue",
              "valueCoding": {
                  "system": "http://canvasmedical.com",
                  "code": "NeedsClinicianReview",
                  "display": "Clinician"
              }
            }
          ],
          "status": "active",
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/claim-type",
                "code": "professional"
              }
            ]
          },
          "use": "claim",
          "patient": {
            "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
            "type": "Patient"
          },
          "created": "2021-08-16",
          "provider": {
            "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
            "type": "Practitioner"
          },
          "priority": {
            "coding": [
              {
                "code": "normal",
                "system": "http://terminology.hl7.org/CodeSystem/processpriority"
              }
            ]
          },
          "supportingInfo": [
            {
              "sequence": 1,
              "category": {
                "coding": [
                  {
                    "code": "patientreasonforvisit",
                    "system": "http://terminology.hl7.org/CodeSystem/claiminformationcategory",
                    "display": "Patient Reason for Visit"
                  }
                ]
              },
              "valueString": "This is only...a test"
            }
          ],
          "diagnosis": [
            {
              "sequence": 1,
              "diagnosisCodeableConcept": {
                "coding": [
                  {
                    "code": "F41.1",
                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                    "display": "Generalized anxiety"
                  }
                ]
              }
            }
          ],
          "insurance": [
            {
              "sequence": 1,
              "focal": True,
              "coverage": {
                "reference": "Coverage/02d4f77a-ebaf-47d5-b162-6313244aed5f"
              }
            }
          ],
          "item": [
            {
              "sequence": 1,
              "diagnosisSequence": [
                1
              ],
              "productOrService": {
                "coding": [
                  {
                    "system": "http://www.ama-assn.org/go/cpt",
                    "code": "exam",
                    "display": "Office visit"
                  }
                ]
              },
              "modifier": [
                {
                  "coding": [
                    {
                      "system": "https://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
                      "code": "21"
                    }
                  ]
                }
              ],
              "quantity": {
                "value": 1
              },
              "unitPrice": {
                "value": 75
              }
            }
          ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Claim/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Claim/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Claim",
            "id": "e4df0a15-d98c-400e-ad46-54eeb13f2753",
            "extension": [
              {
                "url": "http://schemas.canvasmedical.com/fhir/extensions/claim-queue",
                "valueCoding": {
                    "system": "http://canvasmedical.com",
                    "code": "NeedsClinicianReview",
                    "display": "Clinician"
                }
              },
              {
                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                "valueId": "d4a09e6c-bcfb-4d7f-bcc6-aa6cc77eaff3"
              }
            ],
            "status": "active",
            "type": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
                        "code": "professional"
                    }
                ]
            },
            "use": "claim",
            "patient": {
                "reference": "Patient/4dc9d97b71924de58b54a9a91a8250dd",
                "type": "Patient"
            },
            "created": "2023-11-16",
            "provider": {
                "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                "type": "Practitioner"
            },
            "priority": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/processpriority",
                        "code": "normal"
                    }
                ]
            },
            "diagnosis": [
                {
                    "sequence": 1,
                    "diagnosisCodeableConcept": {
                        "coding": [
                            {
                                "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                "code": "J940",
                                "display": "Chylous effusion"
                            }
                        ]
                    }
                },
                {
                    "sequence": 2,
                    "diagnosisCodeableConcept": {
                        "coding": [
                            {
                                "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                "code": "L639",
                                "display": "Alopecia areata, unspecified"
                            }
                        ]
                    }
                }
            ],
            "insurance": [
                {
                    "sequence": 1,
                    "focal": true,
                    "coverage": {
                        "reference": "Coverage/39f37e33-bb0b-4e6b-88ca-56ea94629974",
                        "type": "Coverage"
                    }
                }
            ],
            "item": [
                {
                    "sequence": 1,
                    "diagnosisSequence": [
                        1,
                        2
                    ],
                    "productOrService": {
                        "coding": [
                            {
                                "system": "http://www.ama-assn.org/go/cpt",
                                "code": "99211",
                                "display": "Office outpatient visit 5 minutes"
                            }
                        ]
                    },
                    "quantity": {
                        "value": 1
                    },
                    "unitPrice": {
                        "value": 50.0
                    },
                    "net": {
                        "value": 50.0
                    }
                },
                {
                    "sequence": 2,
                    "diagnosisSequence": [
                        1
                    ],
                    "productOrService": {
                        "coding": [
                            {
                                "system": "http://www.ama-assn.org/go/cpt",
                                "code": "77012",
                                "display": "Ct guidance needle placement"
                            }
                        ]
                    },
                    "quantity": {
                        "value": 1
                    },
                    "unitPrice": {
                        "value": 200.0
                    },
                    "net": {
                        "value": 200.0
                    }
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Claim resource 'a47c7b0ebbb442cdbc4adf259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/Claim/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
          "resourceType": "Claim",
          "extension": [
            {
              "url": "http://schemas.canvasmedical.com/fhir/extensions/claim-queue",
              "valueCoding": {
                  "system": "http://canvasmedical.com",
                  "code": "AdjudicatedOpenBalance",
                  "display": "Adjudicated"
              }
            }
          ],
          "status": "active",
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/claim-type",
                "code": "professional"
              }
            ]
          },
          "use": "claim",
          "patient": {
            "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
            "type": "Patient"
          },
          "created": "2021-08-16",
          "provider": {
            "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
            "type": "Practitioner"
          },
          "priority": {
            "coding": [
              {
                "code": "normal",
                "system": "http://terminology.hl7.org/CodeSystem/processpriority"
              }
            ]
          },
          "supportingInfo": [
            {
              "sequence": 1,
              "category": {
                "coding": [
                  {
                    "code": "patientreasonforvisit",
                    "system": "http://terminology.hl7.org/CodeSystem/claiminformationcategory",
                    "display": "Patient Reason for Visit"
                  }
                ]
              },
              "valueString": "This is only...a test"
            }
          ],
          "diagnosis": [
            {
              "sequence": 1,
              "diagnosisCodeableConcept": {
                "coding": [
                  {
                    "code": "F41.1",
                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                    "display": "Generalized anxiety"
                  }
                ]
              }
            }
          ],
          "insurance": [
            {
              "sequence": 1,
              "focal": true,
              "coverage": {
                "reference": "Coverage/02d4f77a-ebaf-47d5-b162-6313244aed5f"
              }
            }
          ],
          "item": [
            {
              "sequence": 1,
              "diagnosisSequence": [
                1
              ],
              "productOrService": {
                "coding": [
                  {
                    "system": "http://www.ama-assn.org/go/cpt",
                    "code": "exam",
                    "display": "Office visit"
                  }
                ]
              },
              "modifier": [
                {
                  "coding": [
                    {
                      "system": "https://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
                      "code": "21"
                    }
                  ]
                }
              ],
              "quantity": {
                "value": 1
              },
              "unitPrice": {
                "value": 75
              }
            }
          ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Claim/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
          "resourceType": "Claim",
          "extension": [
            {
              "url": "http://schemas.canvasmedical.com/fhir/extensions/claim-queue",
              "valueCoding": {
                  "system": "http://canvasmedical.com",
                  "code": "AdjudicatedOpenBalance",
                  "display": "Adjudicated"
              }
            }
          ],
          "status": "active",
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/claim-type",
                "code": "professional"
              }
            ]
          },
          "use": "claim",
          "patient": {
            "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
            "type": "Patient"
          },
          "created": "2021-08-16",
          "provider": {
            "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
            "type": "Practitioner"
          },
          "priority": {
            "coding": [
              {
                "code": "normal",
                "system": "http://terminology.hl7.org/CodeSystem/processpriority"
              }
            ]
          },
          "supportingInfo": [
            {
              "sequence": 1,
              "category": {
                "coding": [
                  {
                    "code": "patientreasonforvisit",
                    "system": "http://terminology.hl7.org/CodeSystem/claiminformationcategory",
                    "display": "Patient Reason for Visit"
                  }
                ]
              },
              "valueString": "This is only...a test"
            }
          ],
          "diagnosis": [
            {
              "sequence": 1,
              "diagnosisCodeableConcept": {
                "coding": [
                  {
                    "code": "F41.1",
                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                    "display": "Generalized anxiety"
                  }
                ]
              }
            }
          ],
          "insurance": [
            {
              "sequence": 1,
              "focal": True,
              "coverage": {
                "reference": "Coverage/02d4f77a-ebaf-47d5-b162-6313244aed5f"
              }
            }
          ],
          "item": [
            {
              "sequence": 1,
              "diagnosisSequence": [
                1
              ],
              "productOrService": {
                "coding": [
                  {
                    "system": "http://www.ama-assn.org/go/cpt",
                    "code": "exam",
                    "display": "Office visit"
                  }
                ]
              },
              "modifier": [
                {
                  "coding": [
                    {
                      "system": "https://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
                      "code": "21"
                    }
                  ]
                }
              ],
              "quantity": {
                "value": 1
              },
              "unitPrice": {
                "value": 75
              }
            }
          ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Claim resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Claim?patient=Patient/4dc9d97b71924de58b54a9a91a8250dd' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Claim?patient=Patient/4dc9d97b71924de58b54a9a91a8250dd"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Claim?patient=4dc9d97b71924de58b54a9a91a8250dd&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Claim?patient=4dc9d97b71924de58b54a9a91a8250dd&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Claim?patient=4dc9d97b71924de58b54a9a91a8250dd&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Claim",
                        "id": "e4df0a15-d98c-400e-ad46-54eeb13f2753",
                        "extension": [
                          {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/claim-queue",
                            "valueCoding": {
                                "system": "http://canvasmedical.com",
                                "code": "AdjudicatedOpenBalance",
                                "display": "Adjudicated"
                            }
                          }
                        ],
                        "status": "active",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/claim-type",
                                    "code": "professional"
                                }
                            ]
                        },
                        "use": "claim",
                        "patient": {
                            "reference": "Patient/4dc9d97b71924de58b54a9a91a8250dd",
                            "type": "Patient"
                        },
                        "created": "2023-11-16",
                        "provider": {
                            "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                            "type": "Practitioner"
                        },
                        "priority": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/processpriority",
                                    "code": "normal"
                                }
                            ]
                        },
                        "diagnosis": [
                            {
                                "sequence": 1,
                                "diagnosisCodeableConcept": {
                                    "coding": [
                                        {
                                            "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                            "code": "J940",
                                            "display": "Chylous effusion"
                                        }
                                    ]
                                }
                            },
                            {
                                "sequence": 2,
                                "diagnosisCodeableConcept": {
                                    "coding": [
                                        {
                                            "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                            "code": "L639",
                                            "display": "Alopecia areata, unspecified"
                                        }
                                    ]
                                }
                            }
                        ],
                        "insurance": [
                            {
                                "sequence": 1,
                                "focal": true,
                                "coverage": {
                                    "reference": "Coverage/39f37e33-bb0b-4e6b-88ca-56ea94629974",
                                    "type": "Coverage"
                                }
                            }
                        ],
                        "item": [
                            {
                                "sequence": 1,
                                "diagnosisSequence": [
                                    1,
                                    2
                                ],
                                "productOrService": {
                                    "coding": [
                                        {
                                            "system": "http://www.ama-assn.org/go/cpt",
                                            "code": "99211",
                                            "display": "Office outpatient visit 5 minutes"
                                        }
                                    ]
                                },
                                "quantity": {
                                    "value": 1
                                },
                                "unitPrice": {
                                    "value": 50.0
                                },
                                "net": {
                                    "value": 50.0
                                }
                            },
                            {
                                "sequence": 2,
                                "diagnosisSequence": [
                                    1
                                ],
                                "productOrService": {
                                    "coding": [
                                        {
                                            "system": "http://www.ama-assn.org/go/cpt",
                                            "code": "77012",
                                            "display": "Ct guidance needle placement"
                                        }
                                    ]
                                },
                                "quantity": {
                                    "value": 1
                                },
                                "unitPrice": {
                                    "value": 200.0
                                },
                                "net": {
                                    "value": 200.0
                                }
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Communication

Source: https://docs.canvasmedical.com/api/communication/

### 
An occurrence of information being transmitted; e.g. a message that was sent to a responsible provider  
<https://hl7.org/fhir/R4/communication.html>  
The Communication resource maps to messages in Canvas between a patient and practitioner. Click [here](https://canvas-medical.help.usepylon.com/articles/6255444430-patient-message-inbox) to learn more.  
**Additional HTML formatting**  
With the release of Advanced Letter Templates, Messages are now saved in the database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. **Messages sent before this update (10/26/2022 @ 17:00 PST) will remain in plain text format.**  
### Endpoints
post/Communication get/Communication/{id} get/Communication
post
/Communication
#### Communication create
Messages created through this endpoint will be added to the patient's timeline and in the patient app based on the ingestion date into Canvas.
### Attributes
resourceType
string
The FHIR Resource name.
status
string required
The status of the transmission.
While status is a required attribute, all communication messages will be created with a `completed` status regardless of what is supplied in the payload.
**Value Options Supported:**
  - completed
  - in-progress
  - preparation
  - unknown
sent
datetime
When sent  
**ISO 8601 format**
If not supplied on creation, it will default to the current timestamp.
received
datetime
When received  
**ISO 8601 format**
If no `received` datetime is supplied when the recipient of the message is a Practitioner, the message will appear on the subject's timeline as unread, indicated by a blue circle on the message icon. The practitioner will have the ability to mark the communication message as read in the Canvas UI which will update this attribute.
recipient
array[json] required
Message recipient.  
Supported reference types are a single **Patient** or **Practitioner**.
Between the sender and recipient, one must be a practitioner while the other must be a patient.
Click to view child attributes
reference
string required
The reference string of the sender in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Patient" or "Practitioner").
sender
json required
Message sender.  
Supported reference types are a single **Patient** or **Practitioner**.
Between the sender and recipient, one must be a practitioner while the other must be a patient.
Click to view child attributes
reference
string required
The reference string of the sender in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Patient" or "Practitioner").
payload
array[json] required
Message payload.  
Messages are now saved in the Canvas database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before 10/26/2022 @ 17:00 PST will remain in plain text format.
Click to view child attributes
contentString
string required
Message part content.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Communication/{id}
#### Communication read
Read a Communication resource.
### Path Parameters
id required
string
The unique identifier for the Communication   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the communication.
status
string
The status of the transmission.
A communication message in Canvas that was sent, received, delivered, or relayed will all appear in FHIR as `completed`. For draft messages in Canvas, they will appear in FHIR as `preparation`. While a FHIR status of `in-progress` are Canvas messages that are scheduled to be delivered at a later time.
**Value Options Supported:**
  - completed
  - in-progress
  - preparation
  - unknown
subject
json
Focus of the message. Always a **Patient** reference.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
sent
datetime
When sent  
**ISO 8601 format**
received
datetime
When received  
**ISO 8601 format**
Messages sent via Canvas UI to a patient will not have a `received` timestamp.   
If the received timestamp is not added via API to messages sent to practitioners, it can still be updated if the practitioner manually marks the message as read in the UI.
recipient
array[json]
Message recipient.  
Supported reference types are a single **Patient** or **Practitioner**.
Click to view child attributes
reference
string
The reference string of the sender in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Patient" or "Practitioner").
sender
json
Message sender.  
Supported reference types are a single **Patient** or **Practitioner**.
Click to view child attributes
reference
string
The reference string of the sender in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Patient" or "Practitioner").
payload
array[json]
Message payload.  
Messages are now saved in the Canvas database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before 10/26/2022 @ 17:00 PST will remain in plain text format.
Click to view child attributes
contentString
string
Message part content.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Communication
#### Communication search
Communication search will only return messages between a practitioner and patient, not between two practitioners.  
### Query Parameters
****
_id
string
The unique Canvas identifier of the Communication.
patient
string
The patient reference that is the subject of the communication in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
recipient
string
Message recipient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
sender
string
Message sender in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the communication.
status
string
The status of the transmission.
A communication message in Canvas that was sent, received, delivered, or relayed will all appear in FHIR as `completed`. For draft messages in Canvas, they will appear in FHIR as `preparation`. While a FHIR status of `in-progress` are Canvas messages that are scheduled to be delivered at a later time.
**Value Options Supported:**
  - completed
  - in-progress
  - preparation
  - unknown
subject
json
Focus of the message. Always a **Patient** reference.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
sent
datetime
When sent  
**ISO 8601 format**
received
datetime
When received  
**ISO 8601 format**
Messages sent via Canvas UI to a patient will not have a `received` timestamp.   
If the received timestamp is not added via API to messages sent to practitioners, it can still be updated if the practitioner manually marks the message as read in the UI.
recipient
array[json]
Message recipient.  
Supported reference types are a single **Patient** or **Practitioner**.
Click to view child attributes
reference
string
The reference string of the sender in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Patient" or "Practitioner").
sender
json
Message sender.  
Supported reference types are a single **Patient** or **Practitioner**.
Click to view child attributes
reference
string
The reference string of the sender in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Patient" or "Practitioner").
payload
array[json]
Message payload.  
Messages are now saved in the Canvas database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before 10/26/2022 @ 17:00 PST will remain in plain text format.
Click to view child attributes
contentString
string
Message part content.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Communication' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
          "resourceType": "Communication",
          "status": "unknown",
          "sent": "2022-04-29T13:30:00.000Z",
          "received": "2022-04-29T13:30:00.000Z",
          "recipient": [
            {
              "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd"
            }
          ],
          "sender": {
            "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14"
          },
          "payload": [
            {
              "contentString": "Upcoming appointment"
            }
          ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Communication"
        payload = {
            "resourceType": "Communication",
            "sent": "2022-04-29T13:30:00.000Z",
            "received": "2022-04-29T13:30:00.000Z",
            "recipient": [{ "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd" }],
            "sender": { "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14" },
            "payload": [{ "contentString": "Upcoming appointment" }]
        }
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Communication?recipient=Patient/b3084f7e884e4af2b7e23b1dca494abd' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Communication?recipient=Patient/b3084f7e884e4af2b7e23b1dca494abd"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Bundle",
          "type": "searchset",
          "total": 1,
          "link": [
            {
              "relation": "self",
              "url": "/Communication?_id=7433b4b2-0d18-45ca-bb12-71105c80386b&_count=10&_offset=0"
            },
            {
              "relation": "first",
              "url": "/Communication?_id=7433b4b2-0d18-45ca-bb12-71105c80386b&_count=10&_offset=0"
            },
            {
              "relation": "last",
              "url": "/Communication?_id=7433b4b2-0d18-45ca-bb12-71105c80386b&_count=10&_offset=0"
            }
          ],
          "entry": [
            {
              "resource": {
                "resourceType": "Communication",
                "id": "7433b4b2-0d18-45ca-bb12-71105c80386b",
                "status": "completed",
                "sent": "2021-03-21T10:46:17+00:00",
                "received": "2022-03-14T12:03:58.958000+00:00",
                "subject": {
                  "reference": "Patient/4c21512185184e579b09bfac16dfdd2f",
                  "type": "Patient"
                },
                "recipient": [
                  {
                    "reference": "Patient/4c21512185184e579b09bfac16dfdd2f",
                    "type": "Patient"
                  }
                ],
                "sender": {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                    "type": "Practitioner"
                },
                "payload": [
                  {
                    "contentString": "Similique amet at est necessitatibus repellendus eius."
                  }
                ]
              }
            }
          ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "id": "101",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Communication/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Communication/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Communication",
            "id": "17b7d61e-4b0e-4940-bd37-b64f5c2ae29d",
            "status": "completed",
            "sent": "2023-10-23T21:19:22.865089+00:00",
            "received": "2023-10-23T21:21:00.000000+00:00",
            "subject": {
                "reference": "Patient/43f1418bae9c41919203e0006761067c",
                "type": "Patient"
            },
            "recipient": [
                {
                    "reference": "Practitioner/3640cd20de8a470aa570a852859ac87e",
                    "type": "Practitioner"
                }
            ],
            "sender": {
                "reference": "Patient/43f1418bae9c41919203e0006761067c",
                "type": "Patient"
            },
            "payload": [
                {
                    "contentString": "What's up doc?"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Condition

Source: https://docs.canvasmedical.com/api/condition/

### 
A clinical condition, problem, diagnosis, or other event, situation, issue, or clinical concept that has risen to a level of concern.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition-encounter-diagnosis.html>  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition-problems-health-concerns.html>
### Endpoints
post/Condition get/Condition/{id} put/Condition/{id} get/Condition
post
/Condition
#### Condition create
Create a Condition resource.  
This endpoint does not prevent duplicates in the record. **Canvas recommends performing a search prior to adding a new condition** to confirm whether the condition has already been created for the patient.  
If `clinicalStatus` is **active** , the Condition will be added as a `Diagnose` command. If it is not **active** , the Condition will be added as a `Past Medical History` command.  
If an `encounter` or a note ID in the `extension` is provided, the Condition will be added to the existing encounter (note). If it is not provided, a new data import note will be created.
### Attributes
resourceType
string
The FHIR Resource name.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Canvas recommends sending the note identifier extension or the Encounter reference, but not both. If both are supplied, they must both refer to the same note. If neither is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
clinicalStatus
json required
The clinical status of the condition.
If clinicalStatus is active, the Condition will be added as a Diagnose command. If it is not active, the Condition will be added as a Past Medical History command.
Click to view child attributes
coding
array[json] required
Identifies where the definition of the code comes from.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-clinical
code
string required
The code of the clinical status.
**Value Options Supported:**
  - active
  - resolved
category
array[json] required
A category assigned to the condition.
Click to view child attributes
coding
array[json] required
Identifies where the definition of the code comes from.  
The codes `encounter-diagnosis` and `problem-list-item` are paired with the system `http://terminology.hl7.org/CodeSystem/condition-category`.  
The code `health-concern` is paired with the system `http://hl7.org/fhir/us/core/CodeSystem/condition-category`.  
The codes `sdoh`, `functional-status`, `disability-status`, and `cognitive-status` are paired with the system `http://hl7.org/fhir/us/core/CodeSystem/us-core-category`. Please note that these codings are only optionally included as a secondary codeable concept for problem list items or health concerns.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-category
  - http://hl7.org/fhir/us/core/CodeSystem/condition-category
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-category
code
string required
The category code.
**Value Options Supported:**
  - encounter-diagnosis
  - problem-list-item
  - health-concern
  - sdoh
  - functional-status
  - disability-status
  - cognitive-status
code
json required
Identification of the condition, problem or diagnosis.
Canvas will not validate the coding supplied in the payload, instead Canvas will just save the system, code, and display as provided. We highly recommend supplying a coding with the `system` of `http://hl7.org/fhir/sid/icd-10-cm`.
Click to view child attributes
coding
array[json] required
Identifies where the definition of the code comes from.
Click to view child attributes
system
string required
The system url of the coding.
code
string required
The code of the clinical status.
subject
json required
Who has the condition.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter created as part of
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/f7663d7b-13bd-4236-843e-086306aea125"`.
type
string
Type the reference refers to (e.g. "Encounter").
onsetDateTime
date
Estimated or actual date.
abatementDateTime
date
When in resolution/remission.
recordedDate
datetime
Date-time record was first recorded.
If ommitted it will default to the timestamp of ingestion into Canvas.
recorder
json
If ommitted, this will default to Canvas Bot.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Practitioner").
note
array[json]
Additional information about the Condition. This note only appears in the Canvas UI for resolved conditions.
Click to view child attributes
text
string
The annotation - text content.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Condition/{id}
#### Condition read
Read a Condition resource.
### Path Parameters
id required
string
The unique identifier for the Condition   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Condition.
text
json
Text summary of the Condition, for human interpretation.
Click to view child attributes
status
enum [ generated ]
The status of the narrative.
div
string
Limited xhtml content that contains the human readable text of the Condition.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
clinicalStatus
json
The clinical status of the condition.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-clinical
code
string
The code of the clinical status.
**Value Options Supported:**
  - active
  - resolved
  - relapse
  - remission
display
string
The display name of the coding.
**Value Options Supported:**
  - Active
  - Resolved
  - Relapse
  - Remission
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Active
  - Resolved
  - Relapse
  - Remission
verificationStatus
json
The verification status to support the clinical status of the condition.
A `confirmed` status corresponds to committed conditions from a Diagnose or Past Medical History command. An `entered-in-error` status means the Diagnose or Past Medical History command was entered-in-error. A `provisional` condition means it was added as an `indication` to either Image, Refer, POC Lab Test, or a Lab Order command.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-ver-status
code
string
The code of the clinical status.
**Value Options Supported:**
  - confirmed
  - entered-in-error
  - provisional
display
string
The display name of the coding.
**Value Options Supported:**
  - Confirmed
  - Entered in Error
  - Provisional
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Confirmed
  - Entered in Error
  - Provisional
category
array[json]
A category assigned to the condition.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.  
The codes `encounter-diagnosis` and `problem-list-item` are paired with the system `http://terminology.hl7.org/CodeSystem/condition-category`.  
The code `health-concern` is paired with the system `http://hl7.org/fhir/us/core/CodeSystem/condition-category`.  
The codes `sdoh`, `functional-status`, `disability-status`, and `cognitive-status` are paired with the system `http://hl7.org/fhir/us/core/CodeSystem/us-core-category`. Please note that these codings are only optionally included as a secondary codeable concept for problem list items or health concerns.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-category
  - http://hl7.org/fhir/us/core/CodeSystem/condition-category
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-category
code
string
The category code.
**Value Options Supported:**
  - encounter-diagnosis
  - problem-list-item
  - health-concern
  - sdoh
  - functional-status
  - disability-status
  - cognitive-status
display
string
The display name of the coding.
**Value Options Supported:**
  - Encounter Diagnosis
  - Problem List Item
  - Health Concern
  - SDOH
  - Functional Status
  - Disability Status
  - Cognitive Status
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Encounter Diagnosis
  - Problem List Item
  - Health Concern
  - SDOH
  - Functional Status
  - Disability Status
  - Cognitive Status
code
json
Identification of the condition, problem or diagnosis.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the clinical status.
display
string
The display name of the coding.
subject
json
Who has the condition.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter created as part of
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/f7663d7b-13bd-4236-843e-086306aea125"`.
type
string
Type the reference refers to (e.g. "Encounter").
onsetDateTime
date
Estimated or actual date.
abatementDateTime
date
When in resolution/remission.
recordedDate
datetime
Date-time record was first recorded.
recorder
json
Who recorded the condition.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Practitioner").
note
array[json]
Additional information about the Condition. This note only appears in the Canvas UI for resolved conditions.
Click to view child attributes
text
string
The annotation - text content.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Condition/{id}
#### Condition update
Update a Condition resource.  
The only type of Condition update interaction that is supported by Canvas is to mark an existing Condition as **entered-in-error**. No changes to other fields will be processed. All required fields must still be provided, but out FHIR Update will assume a call to the FHIR Condition Update is an intention to mark the condition as entered-in-error.
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The identifier of the Condition.
clinicalStatus
json required
The clinical status of the condition.
Click to view child attributes
coding
array[json] required
Identifies where the definition of the code comes from.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-clinical
code
string required
The code of the clinical status.
**Value Options Supported:**
  - active
  - resolved
category
array[json] required
A category assigned to the condition.
Click to view child attributes
coding
array[json] required
Identifies where the definition of the code comes from.  
The codes `encounter-diagnosis` and `problem-list-item` are paired with the system `http://terminology.hl7.org/CodeSystem/condition-category`.  
The code `health-concern` is paired with the system `http://hl7.org/fhir/us/core/CodeSystem/condition-category`.  
The codes `sdoh`, `functional-status`, `disability-status`, and `cognitive-status` are paired with the system `http://hl7.org/fhir/us/core/CodeSystem/us-core-category`. Please note that these codings are only optionally included as a secondary codeable concept for problem list items or health concerns.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-category
  - http://hl7.org/fhir/us/core/CodeSystem/condition-category
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-category
code
string required
The category code.
**Value Options Supported:**
  - encounter-diagnosis
  - problem-list-item
  - health-concern
  - sdoh
  - functional-status
  - disability-status
  - cognitive-status
code
json required
Identification of the condition, problem or diagnosis.
Click to view child attributes
coding
array[json] required
Identifies where the definition of the code comes from.
Click to view child attributes
system
string required
The system url of the coding.
code
string required
The code of the clinical status.
subject
json required
Who has the condition.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
recorder
json
On an Update this Practitioner will become the user in Canvas who marked the Condition as entered-in-error. If ommitted, it will default to Canvas Bot.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Practitioner").
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Condition
#### Condition search
Search for Condition resources.
### Query Parameters
****
_id
string
The identifier of the Condition.
clinical-status
string
The clinical status of the condition.
**Search Values Supported:**
  - active
  - resolved
patient
string
The patient reference associated to the Condition in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
verification-status
string
The verification status to support the clinical status of the condition.
**Search Values Supported:**
  - confirmed
  - entered-in-error
  - provisional
category
string
The category of the condition. Filters by the code and/or system under `category.coding` attribute. You can search by just the code value or you can search by the system and code in the format `system|code` (e.g. `http://terminology.hl7.org/CodeSystem/condition-category|health-concern`).
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Condition.
text
json
Text summary of the Condition, for human interpretation.
Click to view child attributes
status
enum [ generated ]
The status of the narrative.
div
string
Limited xhtml content that contains the human readable text of the Condition.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
clinicalStatus
json
The clinical status of the condition.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-clinical
code
string
The code of the clinical status.
**Value Options Supported:**
  - active
  - resolved
  - relapse
  - remission
display
string
The display name of the coding.
**Value Options Supported:**
  - Active
  - Resolved
  - Relapse
  - Remission
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Active
  - Resolved
  - Relapse
  - Remission
verificationStatus
json
The verification status to support the clinical status of the condition.
A `confirmed` status corresponds to committed conditions from a Diagnose or Past Medical History command. An `entered-in-error` status means the Diagnose or Past Medical History command was entered-in-error. A `provisional` condition means it was added as an `indication` to either Image, Refer, POC Lab Test, or a Lab Order command.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-ver-status
code
string
The code of the clinical status.
**Value Options Supported:**
  - confirmed
  - entered-in-error
  - provisional
display
string
The display name of the coding.
**Value Options Supported:**
  - Confirmed
  - Entered in Error
  - Provisional
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Confirmed
  - Entered in Error
  - Provisional
category
array[json]
A category assigned to the condition.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.  
The codes `encounter-diagnosis` and `problem-list-item` are paired with the system `http://terminology.hl7.org/CodeSystem/condition-category`.  
The code `health-concern` is paired with the system `http://hl7.org/fhir/us/core/CodeSystem/condition-category`.  
The codes `sdoh`, `functional-status`, `disability-status`, and `cognitive-status` are paired with the system `http://hl7.org/fhir/us/core/CodeSystem/us-core-category`. Please note that these codings are only optionally included as a secondary codeable concept for problem list items or health concerns.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/condition-category
  - http://hl7.org/fhir/us/core/CodeSystem/condition-category
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-category
code
string
The category code.
**Value Options Supported:**
  - encounter-diagnosis
  - problem-list-item
  - health-concern
  - sdoh
  - functional-status
  - disability-status
  - cognitive-status
display
string
The display name of the coding.
**Value Options Supported:**
  - Encounter Diagnosis
  - Problem List Item
  - Health Concern
  - SDOH
  - Functional Status
  - Disability Status
  - Cognitive Status
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Encounter Diagnosis
  - Problem List Item
  - Health Concern
  - SDOH
  - Functional Status
  - Disability Status
  - Cognitive Status
code
json
Identification of the condition, problem or diagnosis.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the clinical status.
display
string
The display name of the coding.
subject
json
Who has the condition.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter created as part of
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/f7663d7b-13bd-4236-843e-086306aea125"`.
type
string
Type the reference refers to (e.g. "Encounter").
onsetDateTime
date
Estimated or actual date.
abatementDateTime
date
When in resolution/remission.
recordedDate
datetime
Date-time record was first recorded.
recorder
json
Who recorded the condition.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Practitioner").
note
array[json]
Additional information about the Condition. This note only appears in the Canvas UI for resolved conditions.
Click to view child attributes
text
string
The annotation - text content.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Condition' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Condition",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                        "code": "resolved",
                        "display": "Resolved"
                    }
                ],
                "text": "Resolved"
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                        "code": "confirmed",
                        "display": "Confirmed"
                    }
                ],
                "text": "Confirmed"
            },
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-category",
                            "code": "problem-list-item",
                            "display": "Problem List Item"
                        }
                    ],
                    "text": "Problem List Item"
                }
            ],
            "code": {
                "coding": [
                    {
                        "system": "http://hl7.org/fhir/sid/icd-10-cm",
                        "code": "V97.21XS",
                        "display": "Parachutist entangled in object, sequela"
                    }
                ],
                "text": "Parachutist entangled in object, sequela"
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "abatementDateTime": "2023-06-17",
            "recordedDate": "2023-06-18T15:00:00-04:00",
            "recorder": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "note": [
                {
                    "text": "Condition note"
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Condition"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Condition",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                        "code": "resolved",
                        "display": "Resolved"
                    }
                ],
                "text": "Resolved"
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                        "code": "confirmed",
                        "display": "Confirmed"
                    }
                ],
                "text": "Confirmed"
            },
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-category",
                            "code": "problem-list-item",
                            "display": "Problem List Item"
                        }
                    ],
                    "text": "Problem List Item"
                }
            ],
            "code": {
                "coding": [
                    {
                        "system": "http://hl7.org/fhir/sid/icd-10-cm",
                        "code": "V97.21XS",
                        "display": "Parachutist entangled in object, sequela"
                    }
                ],
                "text": "Parachutist entangled in object, sequela"
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "abatementDateTime": "2023-06-17",
            "recordedDate": "2023-06-18T15:00:00-04:00",
            "recorder": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "note": [
                {
                    "text": "Condition note"
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Condition/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Condition/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Condition",
            "id": "3340c331-d446-4700-9c23-7959bd393f26",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus":
            {
                "coding":
                [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                        "code": "resolved",
                        "display": "Resolved"
                    }
                ],
                "text": "Resolved"
            },
            "verificationStatus":
            {
                "coding":
                [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                        "code": "confirmed",
                        "display": "Confirmed"
                    }
                ],
                "text": "Confirmed"
            },
            "category":
            [
                {
                    "coding":
                    [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-category",
                            "code": "problem-list-item",
                            "display": "Problem List Item"
                        }
                    ],
                    "text": "Problem List Item"
                }
            ],
            "code":
            {
                "coding":
                [
                    {
                        "system": "http://hl7.org/fhir/sid/icd-10-cm",
                        "code": "V97.21XS",
                        "display": "Parachutist entangled in object, sequela"
                    }
                ],
                "text": "Parachutist entangled in object, sequela"
            },
            "subject":
            {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter":
            {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "abatementDateTime": "2023-06-17",
            "recordedDate": "2023-06-18T15:00:00-04:00",
            "recorder":
            {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "note":
            [
                {
                    "text": "Condition note"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Condition resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/Condition/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Condition",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                        "code": "resolved",
                        "display": "Resolved"
                    }
                ],
                "text": "Resolved"
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                        "code": "entered-in-error",
                        "display": "Entered in Error"
                    }
                ],
                "text": "Entered in Error"
            },
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-category",
                            "code": "problem-list-item",
                            "display": "Problem List Item"
                        }
                    ],
                    "text": "Problem List Item"
                }
            ],
            "code": {
                "coding": [
                    {
                        "system": "http://hl7.org/fhir/sid/icd-10-cm",
                        "code": "V97.21XS",
                        "display": "Parachutist entangled in object, sequela"
                    }
                ],
                "text": "Parachutist entangled in object, sequela"
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "abatementDateTime": "2023-06-17",
            "recordedDate": "2023-06-18T15:00:00-04:00",
            "recorder": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "note": [
                {
                    "text": "Condition note"
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Condition/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Condition",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "clinicalStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                        "code": "resolved",
                        "display": "Resolved"
                    }
                ],
                "text": "Resolved"
            },
            "verificationStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                        "code": "entered-in-error",
                        "display": "Entered in Error"
                    }
                ],
                "text": "Entered in Error"
            },
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-category",
                            "code": "problem-list-item",
                            "display": "Problem List Item"
                        }
                    ],
                    "text": "Problem List Item"
                }
            ],
            "code": {
                "coding": [
                    {
                        "system": "http://hl7.org/fhir/sid/icd-10-cm",
                        "code": "V97.21XS",
                        "display": "Parachutist entangled in object, sequela"
                    }
                ],
                "text": "Parachutist entangled in object, sequela"
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "onsetDateTime": "2023-06-15",
            "abatementDateTime": "2023-06-17",
            "recordedDate": "2023-06-18T15:00:00-04:00",
            "recorder": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "note": [
                {
                    "text": "Condition note"
                }
            ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Condition resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Condition?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0&category=http://terminology.hl7.org/CodeSystem/condition-category|health-concern' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Condition?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0&category=http://terminology.hl7.org/CodeSystem/condition-category|health-concern"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Condition?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Condition?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Condition?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Condition",
                        "id": "3340c331-d446-4700-9c23-7959bd393f26",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                                "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                            }
                        ],
                        "clinicalStatus": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                                    "code": "resolved",
                                    "display": "Resolved"
                                }
                            ],
                            "text": "Resolved"
                        },
                        "verificationStatus": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                                    "code": "confirmed",
                                    "display": "Confirmed"
                                }
                            ],
                            "text": "Confirmed"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/condition-category",
                                        "code": "problem-list-item",
                                        "display": "Problem List Item"
                                    }
                                ],
                                "text": "Problem List Item"
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                    "code": "V97.21XS",
                                    "display": "Parachutist entangled in object, sequela"
                                }
                            ],
                            "text": "Parachutist entangled in object, sequela"
                        },
                        "subject": {
                            "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
                        },
                        "encounter": {
                            "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
                        },
                        "onsetDateTime": "2023-06-15",
                        "abatementDateTime": "2023-06-17",
                        "recordedDate": "2023-06-18T15:00:00-04:00",
                        "recorder": {
                            "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
                        },
                        "note": [
                            {
                                "text": "Condition note"
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Conditional Requests

Source: https://docs.canvasmedical.com/api/conditional-requests/

##  If-Unmodified-Since 
Endpoints that perform update operations support the conditional header [If-Unmodified-Since](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Unmodified-Since).
If a request includes this header, then updates will be rejected if the stored resource has been modified since the date specified in the header, and a 412 Precondition Failed response will be returned.
The date should be in the format specified by [RFC 2616](https://www.rfc-editor.org/rfc/rfc2616).
    ```plaintext
    If-Unmodified-Since: Wed, 21 Oct 2015 07:28:00 GMT
    ```

---

# Consent

Source: https://docs.canvasmedical.com/api/consent/

### 
A record of a healthcare consumer's choices, which permits or denies identified recipient(s) or recipient role(s) to perform one or more actions within a given policy context, for specific purposes and periods of time.  
<https://hl7.org/fhir/R4/consent.html>   
For more information on consents in canvas, see this [article](https://help.canvasmedical.com/articles/8144965836-manging-patient-consents).
### Endpoints
post/Consent get/Consent/{id} get/Consent
post
/Consent
#### Consent create
Before creating a consent via the API, Patient Consent Codings **must** be [configured in Canvas](https://help.canvasmedical.com/articles/8144965836-Managing-Consents).  
**Updating existing patient consent objects**  
A patient consent is uniquely distinguished by its patient and consent coding  
This Create endpoint also acts as an Update endpoint. If the patient already has an existing patient consent with the same consent coding, the endpoint updates that consent in place and the id returned in the response will not be changed.
### Attributes
resourceType
string
The FHIR Resource name.
status
string required
Indicates the current state of this consent.
**Value Options Supported:**
  - active
  - rejected
scope
json required
For create interactions, this field is required by FHIR but ignored by Canvas, so {} is an accepted value.
Click to view child attributes
text
string
Plain text representation of the concept
**Value Options Supported:**
  - Unknown
category
array[json] required
A `system/code` or a `system/display` is required to be able to identify the consent category being created/updated.
Click to view child attributes
coding
array[json] required
Identifies where the definition of the code comes from.
Click to view child attributes
system
string required
The system url of the coding.
code
string
The code of the medication.
display
string
The display name of the coding.
patient
json required
Who the consent applies to
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
sourceAttachment
json required
The source on which this consent statement is based.
The source on which this consent is based.  
For create interactions, `sourceAttachment.title`, `sourceAttachment.contentType`, and `sourceAttachment.data` are required.
Click to view child attributes
title
string required
Label to display in place of the data.
contentType
string required
Mime type of the content, with charset etc.
**Value Options Supported:**
  - application/pdf
data
string required
Data inline, base64ed.
provision
json required
Constraints to the base Consent.  
Canvas uses `period.start` and `period.end` to define the start and end dates of the consent.
For create interactions, `period.start` is required with a **YYYY-MM-DD** format.  
A `period.end` with a past date will mark the consent as Expired in the UI.
Click to view child attributes
period
json required
Timeframe for this rule
Click to view child attributes
start
date required
Starting time with inclusive boundary
end
date
End time with inclusive boundary, if not ongoing.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Consent/{id}
#### Consent read
Read a Consent resource
### Path Parameters
id required
string
The unique identifier for the Consent   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Consent.
status
string
Indicates the current state of this consent. Read interactions may also return `inactive` for consents whose `period.end` has passed.
**Value Options Supported:**
  - active
  - rejected
  - inactive
scope
json
Type of consent being presented (e.g. ADR, Privacy, Treatment, Research).
Click to view child attributes
text
string
Plain text representation of the concept
**Value Options Supported:**
  - Unknown
category
array[json]
A classification of the type of consents found in the statement.  
The category.coding needs to match a patient consent coding record defined in the Canvas Admin Settings page.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the medication.
display
string
The display name of the coding.
patient
json
Who the consent applies to
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
dateTime
datetime
When this Consent was issued / created / indexed.  
This value will be the Consent's datetime of ingestion in Canvas.
sourceAttachment
json
The source on which this consent statement is based.
Canvas returns the `sourceAttachment.url` for the document associated with the consent that has the latest period.start date.
Click to view child attributes
url
url
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
provision
json
Constraints to the base Consent.  
Canvas uses `period.start` and `period.end` to define the start and end dates of the consent.
Click to view child attributes
period
json
Timeframe for this rule
Click to view child attributes
start
date
Starting time with inclusive boundary
end
date
End time with inclusive boundary, if not ongoing.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Consent
#### Consent search
Search for Consent resources
### Query Parameters
****
_id
string
The Canvas-issued unique identifier of the Consent.
patient
string
Who the consent applies to in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`
period
date
Search by the period.start. See [Date Filtering](/api/date-filtering) for more information.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Consent.
status
string
Indicates the current state of this consent. Read interactions may also return `inactive` for consents whose `period.end` has passed.
**Value Options Supported:**
  - active
  - rejected
  - inactive
scope
json
Type of consent being presented (e.g. ADR, Privacy, Treatment, Research).
Click to view child attributes
text
string
Plain text representation of the concept
**Value Options Supported:**
  - Unknown
category
array[json]
A classification of the type of consents found in the statement.  
The category.coding needs to match a patient consent coding record defined in the Canvas Admin Settings page.
Click to view child attributes
coding
array[json]
Identifies where the definition of the code comes from.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the medication.
display
string
The display name of the coding.
patient
json
Who the consent applies to
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
dateTime
datetime
When this Consent was issued / created / indexed.  
This value will be the Consent's datetime of ingestion in Canvas.
sourceAttachment
json
The source on which this consent statement is based.
Canvas returns the `sourceAttachment.url` for the document associated with the consent that has the latest period.start date.
Click to view child attributes
url
url
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
provision
json
Constraints to the base Consent.  
Canvas uses `period.start` and `period.end` to define the start and end dates of the consent.
Click to view child attributes
period
json
Timeframe for this rule
Click to view child attributes
start
date
Starting time with inclusive boundary
end
date
End time with inclusive boundary, if not ongoing.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```sh
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Consent' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
          "resourceType": "Consent",
          "status": "active",
          "scope": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/consentscope",
                "code": "patient-privacy"
              }
            ]
          },
          "category": [
            {
              "coding": [
                {
                  "system": "ConsentCoding_System_ConfigureInAdmin",
                  "code": "ConsentCoding_Code_ConfigureInAdmin",
                  "display": "ConsentCoding_Display_ConfigureInAdmin"
                }
              ]
            }
          ],
          "patient": {
            "reference": "Patient/5350cd20de8a470aa570a852859ac87e"
          },
          "sourceAttachment": {
            "contentType": "application/pdf",
            "data": "JVBERi0xLjYKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCXKuwqEQAxG4T5P8dcLxiS6MyMMUwha2AkBi8VuL52gja+/gpzia46w4qQdAmGxhKDKXVTE7vb40PLAdh9Xx496p2fghGgtB/gb9ahQg39fWbSElMWKZmlKZVnasvpEg9NMM/7+cxdrCmVuZHN0cmVhbQplbmRvYmoKCjMgMCBvYmoKMTA2CmVuZG9iagoKNSAwIG9iago8PC9MZW5ndGggNiAwIFIvRmlsdGVyL0ZsYXRlRGVjb2RlL0xlbmd0aDEgODE4ND4+CnN0cmVhbQp4nOU5fXATV36/tyvZ8geW7NjCILCe2NhgbEv+AMKXsbAt2cYGy19EMgRrLa0tBVtSJdkEcpn42iZhRCgcuSYlYSbpTC+T3KTDOk5b5yYNzl3T9nq9S9I0c5NLaJi5u2lnCgPNJWnncuD+3tuVMYSQaaf/deW3+/v+fk9aSCenFCiEGRDBHZqUE6VGgwAA/whASkLTadrcW7YD4UsAwj+NJcYnn/2rg58BGF4DyH1tfOLo2Or+l9MAhREA8d2IIodPNW6rAbBsRRtbIkjovnE0F/EE4vdGJtMPXSSLJYh/F/HSiXhIpuIoQfwlxAsn5YcSDsN29G9B+0Bj8qTyX+d+FEb8nwEKUol4Cn2JyFrTyfiJpJLoeXb0bcSZ/9NII/hhVyGCOQwXRAP8f76MJ6EMOo3NYIYEv99yia/AKjgLsHiZYTfvN3oWf/t/GYVJe/wJvAivwUn4EB7QGV7wQRSmkLL8egveQyq7fDAM34fM15h9BeaRr8kF4RTL5I6XD56BOfi7W7z4YBIexlj+Aj4kDfBjHJU4fEpM8G14G61+irS9dzIlFOFtjINjy6gfwXPCCdgj/AqRs4wjuAQL/A2cI4fQchrzPLmU8c6vGH0CHsH7AERgGmF+GZt/9wvIW/wNZvUI7IHfh90wsUzjDfK8mI/9G4TnsaZvcZory8ztFB8U/lIQrj+FyHdgHJdMMHfhpLj7ayr0P77EIVhBqsVKyLsTV9gE5hu/FRoXPxPvhXwYWryWpS12L/5GlG/EDCOGNcZmw0/u5iPnO4ZJ1IbFX994+EbYuM/4InYLTwp3x4HhgH9ocKC/z9e7b29P956uzg6vp72tdbe7ZVfzzh3bt229b8vmhnqXs652w/qqynuldQ57eWmxxVy0oiA/z5SbYzSIAoFaqpKgRxUrabFXljyS3FlXSz3lkfa6Wo/kDapUpio+DFVSZycnSbJKg1Stwoe8jBxU3Sg5dpukW5N0L0kSC90JO5kLiao/bZfoPBnu8yN8sl0KUPUKh/dy2FDFkRWIOByowaNi0VKP6p2OZDxBjJHMFuS3SW1Kfl0tzOYXIFiAkLpBSsySDbsIB4QNnu2zAphWMLeYqUcOq74+v6fd5nAE6mq71CKpnbOgjZtUc9rUXG6SRlnocILO1i5knpy3wGiwpjAsheWDflWUUTcjejKZJ9TiGrVaalerj/2qHDNX1Fqp3aPWMKvd/Ut+um+6JKqx0iLRzOeA6UhXLt9KkXVKTqXlc2CgKrSppN/vYJfNi7XOZLwS9WaCGXl+cWZUohYpM1tYmEl4sNzg86OJ+cUfnLCp3icDqiUYIdsDeure/m71nr4DflWo9NKIjBT8a5EcW22O4iUZ39exAcuCxcEKOxysDCfm3TCKiDrT59dwCqO2V8HtqgmoQpBxFrKcsiHGmclyltSDEva2e8CfUQ2VXWHJgxU/IaszozhdD7LGSBa16AubQ8qUFNNtrgCXpRhVVzhKVWMVFgm1livg3DCVjIUjRV9ojys2dFBVXEK3SWiG2fFInqD+Nx0pRwMUC91Zow3CoF91tyPglvWOeWbrXaghB7Fh0XbeTNUlJdRSqXWpuywsT3TAz1V0NbW0TYVgSNdSXR6+r6gnE2zXQmC2pD7/69C0eGl2E7XNNcEmCLQzYWsbTlmVJ+MPj6n2oC2M+26M+m0O1R3ADgckvxJgY4cVqr5k48MR4LMy6O8ekLr7hv1b9UA0BjNnqPTcZkby2zQzOICqqdJE/YJNDKCgBQnUi4DUuhPvam6lCZcFC86pbHBbd1I/sUFWGsNQq6lHadflGH6LUSMbp7bOrLUchqKdtk6bI+DQrrpaAdlUd4waJlbUziwLjylkmHA+2zo5idWynA099UuKFJAiVHX7/Cw3Vh5eZb0YvOZ6rwZvwZYVC8sEDmRnEVZM1VtjW15ctYPjS2jnbeyuLJtmTFL3QIYZl3SDgJF3qcBG2L212MbPArahJTx7qQW3NN/QmVm3m23myHZmROoKZ6QB/04ujefJI7ZjzFcJdJPuwda6WjzaWmclcrxv1k2ODwz7X7fg78Ljg/5XBSK0BVsDs/ciz/86xS8NThUYlREZQhnCLPUjYuLyttfdADOca+AEjofmCXCaKUsjEJoXNJpFc1TFHblBQI5B47iz0gakmTTaDKfxaxZYydz5RrfJnecuFFYItlnCSK8i5Qf4OzaPwFwhWUFss6jVz8nzZGY2z23TJGZQwq1FeHzopuuhYf9cIX472/gdHbWyC8elPILNxq8VDw2zQflWIJIJBthmAyu2Bv+ISqRd2CZpFwaSU6jmS0qrWiC1MnoLo7do9BxGz8URJVaC6jPYe59K2AQc8DtwS9LVP7ZlLFdYpwJ4qGQsv67DilXie8Nb+Bu0lOx0XywRCgSTWGYtBBPJE02mvGIxTwwG8sQSAYSRAJS0WInZSi5ZyQUrOWUlj1rJiJUgkXL64WtW8o6VvMB5CSvptRI7Z2h01Uqe56w4V3NbST0XACv5hHNnOL2eU3Yscj+a2inO6OW8a5yuZn1oCpTrXOOGFribGc7F0FxZHw8sXb+XvZL6deg2+lc4jActNcXQVM7vxU3lrpFDDzQVl5CV24qbGuodm+8rltaZiVTsKJbWO0kNKV5ZRnZ80HT9AVub4Vy7reIfHmr4YLPN8Ezpe2THjbffyy348rBtM/9ZBr7Fy6JXfBvfCdbASffwKkLMq01l5rK1FavAFzCvsq8SCsVVqwpLSqy+QIml0NgXKLQuVBC1grxQQU5XkJkKkqggwQriqyBQQXbhw11B6isIrSCWCnKNy6FQNrGlrB7ApIClVALbeEYIkW2YEWbI0iJlpRWkqXHLfWVFRFpXVbxpSxMtLiPrcsocm6qIofnR8S3fra//3v6PfvKzCyR645lInJw5SD4syZz1lRRstTsvE+MXn94Y6yfnXvqzubPsTXBw8bLwPua6AQLuTY7c0tUroBSqN65wiCtXVvgCtpUWscAXyBWtMxtJYiMJbiS+jYRuJOc3kpGNpHcjyfYJWppY6E089m03w2ZRl+ZgsOs3N620NjVu3uQiTmEzRt64skxaXyVh8KXWlRWi8P7sn3tfrq9r6H7oh2cDysHGl0+PP+fauDnZN7R331PDLRIxPXl6bcm//kH7i8c2rXW0h7zfOmX/6aTL175t3+pGZ9t+YPmUYj51hm+DFTrc6/OLinLvEcWV5YbCgkJfIC+3wFwKUNwXAOvz5UQtJy3lxFXOUkhmp6mpic8Thl+yrbGR1dy4rmpzsbS5hTSVNZVJxaWYAys/2RccefgRpeXnP99Rv31A+sPS5LjwVN36Dz4YvP7o7lbL7nI7jwfnadXZ8O/mb4yYd34Odu0d7+/b3/3ZzV/wi5f5jmcvgIJOQr1cxw0P3L8kRG772W/M2YYnxS+hUjwJPnEtDArbsHHs+iHZSl4g/8Y1jFCt2xTAgu8+BxH4kfi3IHJuBYkt2d2/5IOg5H4dFiAX39M0WAQbvg1qsAFljuuwEVbgO6sG5+C78/d0OBeO4XusBpvwPHPqcB4UkVYdzicx4tPhAlgjvLn0LxNO4Rc6vAI2iyYdLoLVYjOL3sDeqF4R79dhAtQg6rAARQZJh0XYYmjQYQPKjOuwEVYbntDhHKgw/KkO58Jnhgs6bIINxjkdzoM1xo90OF/42PifOlwAW03v63AhHMwr0OEV8GBe1lcRbMp7rz06Hk1HjylhGpbTMg3FE0eT0fFImm4IVdPG+oZ62hGPj08otC2eTMSTcjoajznz224Xa6T9aKJTTtfSrljI2RMdVTRZOqAko2P9yvjUhJzcnQopsbCSpHX0donb8f1KMsWQRmeDc9NN5u2y0RS+5aWTcliZlJOHaXzs1jhoUhmPptJKEonRGB1yDjipT04rsTSVY2E6uKTYOzYWDSmcGFKSaRmF4+kIRvrgVDKaCkdDzFvKuZTAsmoMpJVphe6V02klFY+1yin0hZENRmPxVC09EomGIvSInKJhJRUdjyFz9Ci9VYciV8ZcYrH4NJqcVmox7rGkkopEY+M0xVLWtWk6IqdZ0pNKOhkNyRMTR7FlkwnUGsUeHYmmI+h4UknRfcoR2h+flGPfd2qhYG3GsKY0OplIxqd5jHWpUFJRYuhMDsuj0YloGq1F5KQcwoph2aKhFK8IFoIm5FidZyoZTygY6f0dPTcFMUCtmqn4xDR6ZtIxRQkzjxj2tDKBSuh4Ih4/zPIZiycx0HA6Urcs8rF4LI2qcSqHw5g4VisemppkfcIyp7PByaFkHHmJCTmNViZTzkg6ndjuch05csQp660JYWecaNl1N176aELR+5FkViYnerD9Mda6Kd5flsRAVw/tTWB9vBgc1QVqaXYyG5wNugssYzSRTjlT0QlnPDnu6vX2QDtEYRxXGtcxUCAMFJeMuIxQCOKQgKOQ5FIRpFL8ogvhoUihEeqhAReFDpSKI38C9Sm0IZxELXaXud04xMAJ+Zxzd2uNCPXrUXRy7VqEulA/hBZ6UG8UucvtUhjglCges0xzHKYwDhkpuyGFWgrKhLkEhTpc32Tjm/j7OZRa4jRiXA24Nt1R85vsRtES5ZVOcw6LdJJHfxhpcdS7Wz0oyim8eynkKBwLc6vM9hBKDHApH9dklUhzbzEuNXgHj73ocQz1Q7yTWckQt80mQrMcRzii1/RBrHeSRxDmetncUuj5qx2482wM8Oimuc+9nM7wFOe1Ip7S89JqNsijiCOV1eIIRsL8Rjgs83qGuTabsZiuOYpTR+/qh+q6st6XGPcxrUfJdGr1eo/xe4r7jaEPyuPTunyrb8rrJPOqa52eRG6ay4aQPoGfo/oum8SqaL5G9X10hO/KiJ7xJLdLYR8+j/CpiPO+xRzreI9vVkWbmzF9TinXTSAc51lk61jHe8MyUXikDJL5zh9FjQnuW4stwqdD5r1V9F6neQbZeoX1TFnUCU6pAw+fC7bfFb2m9+M50XNHi1oFl88m68kEjze1zHaMRxteylGrNpOa0D1pGU/w8+jwUn/G+LxpFQ1za3VfU/MxXpu07jXOIwrjR+u4Nltx1J3i/dD2kzbN6a9UTub1jet6CX4qpfVYJvn+iPAJTMB2/GHpwujYx8nncPmuCel7xqnH7Ppf67G4EryCy/dHcimWSYyxR9/9saVdN7Vs/2Y7MYBnUA8/LxL6/Hj1ytHbLLBdc/uZ2cDPzFuz0KYxiniax5PitXTyHMaR34seerT/lrvLNZvn2z1KFCAkQsbhHrCTIOwjIzBEdkMzcePTjbxWfLYhzp5O0gwzKNeM9F2I70T6Djw77XhvwdWL6xQuAy5Noh4lXPh06Xgd4rWo8Q7eCV+M2oJU9tyDeCc+O/SnF+kefHp0vAtxfEKQ5OKP8BZ+v0AM7jly6Tp55zqh18mjXxLfl2Tm09OfCv9xrdp+/tqFa0Lv1ZGr56+K9VeJ+SoxwRXLFd+V4JXElReu5OSbL5NC+HdS/MtLW+2fNF8c+pfmj4fgImZ2sf6i7+LMRfWi8SIRhz4WrXbLAl2oX0gszCy8u3Bp4dqCaebN028Kf/2Gy25+w/6GYJ/rnXt0Tgy+RMwv2V8SfM8FnxNOnyPmc/ZzrnPis2ed9rMdFfZnnl5vv/T0taeF+cWFuadXFHvfIL2kB5qxhvvmxEX7+d1lZC+mZca7HZcLVy+uOK5TuPCdB8XtuFykx71VHPljUnDGdqbmzMNnTpwxJh6fefz04+LMY6cfE85PX5gWUr5qezxWY491bLSvaiofym0Sh3LQDXp3d41WbvAGR9z2ERQ6MFxvH+6ott/TVDJkxIQNKGgW7WKL2CvGxVPiBTHX1O+rsPfhuuS75hPcvrxCr7nX3uvqFecXL7mVbgda25PYM7NH7PJW2zs7ttrNHfYOV8c7HZ90XO3IGekgz+Of97z3gld0e6tdXre3wuFd02kbsjaVDRUT85ClyTwkEGx0Ewy5zItmwWweMT9qFs3QAsKMlRjJPDk9OzhQU9M9n7vY362afAdUclytHGB3d9+wmnNchaHhA/5ZQv4o8NjJk9C6tlttHPCrwbWBbjWMgJsBMwhY1s5aoTWQSqVr+EVqahCewjvUTNUg8VBKo8ISH2pSJIVHVIorkRomoOEE7zWMhwSmR1D7UArYjTFrNCWmndLNcWXtxoHyQ/8NHT4cpAplbmRzdHJlYW0KZW5kb2JqCgo2IDAgb2JqCjQ2MjgKZW5kb2JqCgo3IDAgb2JqCjw8L1R5cGUvRm9udERlc2NyaXB0b3IvRm9udE5hbWUvQkFBQUFBK0xpYmVyYXRpb25TZXJpZgovRmxhZ3MgNAovRm9udEJCb3hbLTU0MyAtMzAzIDEyNzggOTgyXS9JdGFsaWNBbmdsZSAwCi9Bc2NlbnQgODkxCi9EZXNjZW50IC0yMTYKL0NhcEhlaWdodCA5ODEKL1N0ZW1WIDgwCi9Gb250RmlsZTIgNSAwIFIKPj4KZW5kb2JqCgo4IDAgb2JqCjw8L0xlbmd0aCAyNDAvRmlsdGVyL0ZsYXRlRGVjb2RlPj4Kc3RyZWFtCnicXVDLasMwELzrK/aYHIJsx2kvRhASAj70Qd1+gCytXUEtCVk++O+7ktMWepCYYXaG2eWX9tpaE/lrcKrDCIOxOuDslqAQehyNZWUF2qh4Z/lXk/SMk7db54hTawfXNIy/kTbHsMLurF2Pe8ZfgsZg7Ai7j0tHvFu8/8IJbYSCCQEaB8p5kv5ZTsiz69Bqkk1cD2T5G3hfPUKVeblVUU7j7KXCIO2IrCkKAc3tJhha/U+rN0c/qE8ZaLKkyaI41YJwlfHDKeFjxo/HhOsN1znv7kzJafWfxqCWEKhtvk+umQoai78n9M4nV37ft5d0YgplbmRzdHJlYW0KZW5kb2JqCgo5IDAgb2JqCjw8L1R5cGUvRm9udC9TdWJ0eXBlL1RydWVUeXBlL0Jhc2VGb250L0JBQUFBQStMaWJlcmF0aW9uU2VyaWYKL0ZpcnN0Q2hhciAwCi9MYXN0Q2hhciA0Ci9XaWR0aHNbNzc3IDYxMCA0NDMgMzg5IDI3NyBdCi9Gb250RGVzY3JpcHRvciA3IDAgUgovVG9Vbmljb2RlIDggMCBSCj4+CmVuZG9iagoKMTAgMCBvYmoKPDwvRjEgOSAwIFIKPj4KZW5kb2JqCgoxMSAwIG9iago8PC9Gb250IDEwIDAgUgovUHJvY1NldFsvUERGL1RleHRdCj4+CmVuZG9iagoKMSAwIG9iago8PC9UeXBlL1BhZ2UvUGFyZW50IDQgMCBSL1Jlc291cmNlcyAxMSAwIFIvTWVkaWFCb3hbMCAwIDYxMiA3OTJdL0dyb3VwPDwvUy9UcmFuc3BhcmVuY3kvQ1MvRGV2aWNlUkdCL0kgdHJ1ZT4+L0NvbnRlbnRzIDIgMCBSPj4KZW5kb2JqCgo0IDAgb2JqCjw8L1R5cGUvUGFnZXMKL1Jlc291cmNlcyAxMSAwIFIKL01lZGlhQm94WyAwIDAgNjEyIDc5MiBdCi9LaWRzWyAxIDAgUiBdCi9Db3VudCAxPj4KZW5kb2JqCgoxMiAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgNCAwIFIKL09wZW5BY3Rpb25bMSAwIFIgL1hZWiBudWxsIG51bGwgMF0KL0xhbmcoZW4tVVMpCj4+CmVuZG9iagoKMTMgMCBvYmoKPDwvQ3JlYXRvcjxGRUZGMDA1NzAwNzIwMDY5MDA3NDAwNjUwMDcyPgovUHJvZHVjZXI8RkVGRjAwNEMwMDY5MDA2MjAwNzIwMDY1MDA0RjAwNjYwMDY2MDA2OTAwNjMwMDY1MDAyMDAwMzcwMDJFMDAzMj4KL0NyZWF0aW9uRGF0ZShEOjIwMjIwNTIzMDczODM3LTA3JzAwJyk+PgplbmRvYmoKCnhyZWYKMCAxNAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDU3MTUgMDAwMDAgbiAKMDAwMDAwMDAxOSAwMDAwMCBuIAowMDAwMDAwMTk2IDAwMDAwIG4gCjAwMDAwMDU4NTggMDAwMDAgbiAKMDAwMDAwMDIxNiAwMDAwMCBuIAowMDAwMDA0OTI4IDAwMDAwIG4gCjAwMDAwMDQ5NDkgMDAwMDAgbiAKMDAwMDAwNTE0NCAwMDAwMCBuIAowMDAwMDA1NDUzIDAwMDAwIG4gCjAwMDAwMDU2MjggMDAwMDAgbiAKMDAwMDAwNTY2MCAwMDAwMCBuIAowMDAwMDA1OTU3IDAwMDAwIG4gCjAwMDAwMDYwNTQgMDAwMDAgbiAKdHJhaWxlcgo8PC9TaXplIDE0L1Jvb3QgMTIgMCBSCi9JbmZvIDEzIDAgUgovSUQgWyA8ODREQjY2QjEwREU5OTRGNzA1ODlCQTNCRjUzODE4RDg+Cjw4NERCNjZCMTBERTk5NEY3MDU4OUJBM0JGNTM4MThEOD4gXQovRG9jQ2hlY2tzdW0gLzg3MTVEQTJGQzEyOEM2RUY4NzlFREY4RUZGMjRBQTc0Cj4+CnN0YXJ0eHJlZgo2MjI5CiUlRU9GCg==",
            "title": "UploadTest.pdf"
          },
          "provision": {
            "period": {
              "start": "2022-05-15",
              "end": "2022-10-10"
            }
          }
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Consent"
        payload = {
          "resourceType": "Consent",
          "status": "active",
          "scope": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/consentscope",
                  "code": "patient-privacy"
                }
            ]
          },
          "category": [
            {
              "coding": [
                {
                  "system": "ConsentCoding_System_ConfigureInAdmin",
                  "code": "ConsentCoding_Code_ConfigureInAdmin",
                  "display": "ConsentCoding_Display_ConfigureInAdmin"
                }
              ]
            }
          ],
          "patient": {
              "reference": "Patient/5350cd20de8a470aa570a852859ac87e",
              "type": "Patient"
          },
          "sourceAttachment": {
              "contentType": "application/pdf",
              "data": "JVBERi0xLjYKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nCXKuwqEQAxG4T5P8dcLxiS6MyMMUwha2AkBi8VuL52gja+/gpzia46w4qQdAmGxhKDKXVTE7vb40PLAdh9Xx496p2fghGgtB/gb9ahQg39fWbSElMWKZmlKZVnasvpEg9NMM/7+cxdrCmVuZHN0cmVhbQplbmRvYmoKCjMgMCBvYmoKMTA2CmVuZG9iagoKNSAwIG9iago8PC9MZW5ndGggNiAwIFIvRmlsdGVyL0ZsYXRlRGVjb2RlL0xlbmd0aDEgODE4ND4+CnN0cmVhbQp4nOU5fXATV36/tyvZ8geW7NjCILCe2NhgbEv+AMKXsbAt2cYGy19EMgRrLa0tBVtSJdkEcpn42iZhRCgcuSYlYSbpTC+T3KTDOk5b5yYNzl3T9nq9S9I0c5NLaJi5u2lnCgPNJWnncuD+3tuVMYSQaaf/deW3+/v+fk9aSCenFCiEGRDBHZqUE6VGgwAA/whASkLTadrcW7YD4UsAwj+NJcYnn/2rg58BGF4DyH1tfOLo2Or+l9MAhREA8d2IIodPNW6rAbBsRRtbIkjovnE0F/EE4vdGJtMPXSSLJYh/F/HSiXhIpuIoQfwlxAsn5YcSDsN29G9B+0Bj8qTyX+d+FEb8nwEKUol4Cn2JyFrTyfiJpJLoeXb0bcSZ/9NII/hhVyGCOQwXRAP8f76MJ6EMOo3NYIYEv99yia/AKjgLsHiZYTfvN3oWf/t/GYVJe/wJvAivwUn4EB7QGV7wQRSmkLL8egveQyq7fDAM34fM15h9BeaRr8kF4RTL5I6XD56BOfi7W7z4YBIexlj+Aj4kDfBjHJU4fEpM8G14G61+irS9dzIlFOFtjINjy6gfwXPCCdgj/AqRs4wjuAQL/A2cI4fQchrzPLmU8c6vGH0CHsH7AERgGmF+GZt/9wvIW/wNZvUI7IHfh90wsUzjDfK8mI/9G4TnsaZvcZory8ztFB8U/lIQrj+FyHdgHJdMMHfhpLj7ayr0P77EIVhBqsVKyLsTV9gE5hu/FRoXPxPvhXwYWryWpS12L/5GlG/EDCOGNcZmw0/u5iPnO4ZJ1IbFX994+EbYuM/4InYLTwp3x4HhgH9ocKC/z9e7b29P956uzg6vp72tdbe7ZVfzzh3bt229b8vmhnqXs652w/qqynuldQ57eWmxxVy0oiA/z5SbYzSIAoFaqpKgRxUrabFXljyS3FlXSz3lkfa6Wo/kDapUpio+DFVSZycnSbJKg1Stwoe8jBxU3Sg5dpukW5N0L0kSC90JO5kLiao/bZfoPBnu8yN8sl0KUPUKh/dy2FDFkRWIOByowaNi0VKP6p2OZDxBjJHMFuS3SW1Kfl0tzOYXIFiAkLpBSsySDbsIB4QNnu2zAphWMLeYqUcOq74+v6fd5nAE6mq71CKpnbOgjZtUc9rUXG6SRlnocILO1i5knpy3wGiwpjAsheWDflWUUTcjejKZJ9TiGrVaalerj/2qHDNX1Fqp3aPWMKvd/Ut+um+6JKqx0iLRzOeA6UhXLt9KkXVKTqXlc2CgKrSppN/vYJfNi7XOZLwS9WaCGXl+cWZUohYpM1tYmEl4sNzg86OJ+cUfnLCp3icDqiUYIdsDeure/m71nr4DflWo9NKIjBT8a5EcW22O4iUZ39exAcuCxcEKOxysDCfm3TCKiDrT59dwCqO2V8HtqgmoQpBxFrKcsiHGmclyltSDEva2e8CfUQ2VXWHJgxU/IaszozhdD7LGSBa16AubQ8qUFNNtrgCXpRhVVzhKVWMVFgm1livg3DCVjIUjRV9ojys2dFBVXEK3SWiG2fFInqD+Nx0pRwMUC91Zow3CoF91tyPglvWOeWbrXaghB7Fh0XbeTNUlJdRSqXWpuywsT3TAz1V0NbW0TYVgSNdSXR6+r6gnE2zXQmC2pD7/69C0eGl2E7XNNcEmCLQzYWsbTlmVJ+MPj6n2oC2M+26M+m0O1R3ADgckvxJgY4cVqr5k48MR4LMy6O8ekLr7hv1b9UA0BjNnqPTcZkby2zQzOICqqdJE/YJNDKCgBQnUi4DUuhPvam6lCZcFC86pbHBbd1I/sUFWGsNQq6lHadflGH6LUSMbp7bOrLUchqKdtk6bI+DQrrpaAdlUd4waJlbUziwLjylkmHA+2zo5idWynA099UuKFJAiVHX7/Cw3Vh5eZb0YvOZ6rwZvwZYVC8sEDmRnEVZM1VtjW15ctYPjS2jnbeyuLJtmTFL3QIYZl3SDgJF3qcBG2L212MbPArahJTx7qQW3NN/QmVm3m23myHZmROoKZ6QB/04ujefJI7ZjzFcJdJPuwda6WjzaWmclcrxv1k2ODwz7X7fg78Ljg/5XBSK0BVsDs/ciz/86xS8NThUYlREZQhnCLPUjYuLyttfdADOca+AEjofmCXCaKUsjEJoXNJpFc1TFHblBQI5B47iz0gakmTTaDKfxaxZYydz5RrfJnecuFFYItlnCSK8i5Qf4OzaPwFwhWUFss6jVz8nzZGY2z23TJGZQwq1FeHzopuuhYf9cIX472/gdHbWyC8elPILNxq8VDw2zQflWIJIJBthmAyu2Bv+ISqRd2CZpFwaSU6jmS0qrWiC1MnoLo7do9BxGz8URJVaC6jPYe59K2AQc8DtwS9LVP7ZlLFdYpwJ4qGQsv67DilXie8Nb+Bu0lOx0XywRCgSTWGYtBBPJE02mvGIxTwwG8sQSAYSRAJS0WInZSi5ZyQUrOWUlj1rJiJUgkXL64WtW8o6VvMB5CSvptRI7Z2h01Uqe56w4V3NbST0XACv5hHNnOL2eU3Yscj+a2inO6OW8a5yuZn1oCpTrXOOGFribGc7F0FxZHw8sXb+XvZL6deg2+lc4jActNcXQVM7vxU3lrpFDDzQVl5CV24qbGuodm+8rltaZiVTsKJbWO0kNKV5ZRnZ80HT9AVub4Vy7reIfHmr4YLPN8Ezpe2THjbffyy348rBtM/9ZBr7Fy6JXfBvfCdbASffwKkLMq01l5rK1FavAFzCvsq8SCsVVqwpLSqy+QIml0NgXKLQuVBC1grxQQU5XkJkKkqggwQriqyBQQXbhw11B6isIrSCWCnKNy6FQNrGlrB7ApIClVALbeEYIkW2YEWbI0iJlpRWkqXHLfWVFRFpXVbxpSxMtLiPrcsocm6qIofnR8S3fra//3v6PfvKzCyR645lInJw5SD4syZz1lRRstTsvE+MXn94Y6yfnXvqzubPsTXBw8bLwPua6AQLuTY7c0tUroBSqN65wiCtXVvgCtpUWscAXyBWtMxtJYiMJbiS+jYRuJOc3kpGNpHcjyfYJWppY6E089m03w2ZRl+ZgsOs3N620NjVu3uQiTmEzRt64skxaXyVh8KXWlRWi8P7sn3tfrq9r6H7oh2cDysHGl0+PP+fauDnZN7R331PDLRIxPXl6bcm//kH7i8c2rXW0h7zfOmX/6aTL175t3+pGZ9t+YPmUYj51hm+DFTrc6/OLinLvEcWV5YbCgkJfIC+3wFwKUNwXAOvz5UQtJy3lxFXOUkhmp6mpic8Thl+yrbGR1dy4rmpzsbS5hTSVNZVJxaWYAys/2RccefgRpeXnP99Rv31A+sPS5LjwVN36Dz4YvP7o7lbL7nI7jwfnadXZ8O/mb4yYd34Odu0d7+/b3/3ZzV/wi5f5jmcvgIJOQr1cxw0P3L8kRG772W/M2YYnxS+hUjwJPnEtDArbsHHs+iHZSl4g/8Y1jFCt2xTAgu8+BxH4kfi3IHJuBYkt2d2/5IOg5H4dFiAX39M0WAQbvg1qsAFljuuwEVbgO6sG5+C78/d0OBeO4XusBpvwPHPqcB4UkVYdzicx4tPhAlgjvLn0LxNO4Rc6vAI2iyYdLoLVYjOL3sDeqF4R79dhAtQg6rAARQZJh0XYYmjQYQPKjOuwEVYbntDhHKgw/KkO58Jnhgs6bIINxjkdzoM1xo90OF/42PifOlwAW03v63AhHMwr0OEV8GBe1lcRbMp7rz06Hk1HjylhGpbTMg3FE0eT0fFImm4IVdPG+oZ62hGPj08otC2eTMSTcjoajznz224Xa6T9aKJTTtfSrljI2RMdVTRZOqAko2P9yvjUhJzcnQopsbCSpHX0donb8f1KMsWQRmeDc9NN5u2y0RS+5aWTcliZlJOHaXzs1jhoUhmPptJKEonRGB1yDjipT04rsTSVY2E6uKTYOzYWDSmcGFKSaRmF4+kIRvrgVDKaCkdDzFvKuZTAsmoMpJVphe6V02klFY+1yin0hZENRmPxVC09EomGIvSInKJhJRUdjyFz9Ci9VYciV8ZcYrH4NJqcVmox7rGkkopEY+M0xVLWtWk6IqdZ0pNKOhkNyRMTR7FlkwnUGsUeHYmmI+h4UknRfcoR2h+flGPfd2qhYG3GsKY0OplIxqd5jHWpUFJRYuhMDsuj0YloGq1F5KQcwoph2aKhFK8IFoIm5FidZyoZTygY6f0dPTcFMUCtmqn4xDR6ZtIxRQkzjxj2tDKBSuh4Ih4/zPIZiycx0HA6Urcs8rF4LI2qcSqHw5g4VisemppkfcIyp7PByaFkHHmJCTmNViZTzkg6ndjuch05csQp660JYWecaNl1N176aELR+5FkViYnerD9Mda6Kd5flsRAVw/tTWB9vBgc1QVqaXYyG5wNugssYzSRTjlT0QlnPDnu6vX2QDtEYRxXGtcxUCAMFJeMuIxQCOKQgKOQ5FIRpFL8ogvhoUihEeqhAReFDpSKI38C9Sm0IZxELXaXud04xMAJ+Zxzd2uNCPXrUXRy7VqEulA/hBZ6UG8UucvtUhjglCges0xzHKYwDhkpuyGFWgrKhLkEhTpc32Tjm/j7OZRa4jRiXA24Nt1R85vsRtES5ZVOcw6LdJJHfxhpcdS7Wz0oyim8eynkKBwLc6vM9hBKDHApH9dklUhzbzEuNXgHj73ocQz1Q7yTWckQt80mQrMcRzii1/RBrHeSRxDmetncUuj5qx2482wM8Oimuc+9nM7wFOe1Ip7S89JqNsijiCOV1eIIRsL8Rjgs83qGuTabsZiuOYpTR+/qh+q6st6XGPcxrUfJdGr1eo/xe4r7jaEPyuPTunyrb8rrJPOqa52eRG6ay4aQPoGfo/oum8SqaL5G9X10hO/KiJ7xJLdLYR8+j/CpiPO+xRzreI9vVkWbmzF9TinXTSAc51lk61jHe8MyUXikDJL5zh9FjQnuW4stwqdD5r1V9F6neQbZeoX1TFnUCU6pAw+fC7bfFb2m9+M50XNHi1oFl88m68kEjze1zHaMRxteylGrNpOa0D1pGU/w8+jwUn/G+LxpFQ1za3VfU/MxXpu07jXOIwrjR+u4Nltx1J3i/dD2kzbN6a9UTub1jet6CX4qpfVYJvn+iPAJTMB2/GHpwujYx8nncPmuCel7xqnH7Ppf67G4EryCy/dHcimWSYyxR9/9saVdN7Vs/2Y7MYBnUA8/LxL6/Hj1ytHbLLBdc/uZ2cDPzFuz0KYxiniax5PitXTyHMaR34seerT/lrvLNZvn2z1KFCAkQsbhHrCTIOwjIzBEdkMzcePTjbxWfLYhzp5O0gwzKNeM9F2I70T6Djw77XhvwdWL6xQuAy5Noh4lXPh06Xgd4rWo8Q7eCV+M2oJU9tyDeCc+O/SnF+kefHp0vAtxfEKQ5OKP8BZ+v0AM7jly6Tp55zqh18mjXxLfl2Tm09OfCv9xrdp+/tqFa0Lv1ZGr56+K9VeJ+SoxwRXLFd+V4JXElReu5OSbL5NC+HdS/MtLW+2fNF8c+pfmj4fgImZ2sf6i7+LMRfWi8SIRhz4WrXbLAl2oX0gszCy8u3Bp4dqCaebN028Kf/2Gy25+w/6GYJ/rnXt0Tgy+RMwv2V8SfM8FnxNOnyPmc/ZzrnPis2ed9rMdFfZnnl5vv/T0taeF+cWFuadXFHvfIL2kB5qxhvvmxEX7+d1lZC+mZca7HZcLVy+uOK5TuPCdB8XtuFykx71VHPljUnDGdqbmzMNnTpwxJh6fefz04+LMY6cfE85PX5gWUr5qezxWY491bLSvaiofym0Sh3LQDXp3d41WbvAGR9z2ERQ6MFxvH+6ott/TVDJkxIQNKGgW7WKL2CvGxVPiBTHX1O+rsPfhuuS75hPcvrxCr7nX3uvqFecXL7mVbgda25PYM7NH7PJW2zs7ttrNHfYOV8c7HZ90XO3IGekgz+Of97z3gld0e6tdXre3wuFd02kbsjaVDRUT85ClyTwkEGx0Ewy5zItmwWweMT9qFs3QAsKMlRjJPDk9OzhQU9M9n7vY362afAdUclytHGB3d9+wmnNchaHhA/5ZQv4o8NjJk9C6tlttHPCrwbWBbjWMgJsBMwhY1s5aoTWQSqVr+EVqahCewjvUTNUg8VBKo8ISH2pSJIVHVIorkRomoOEE7zWMhwSmR1D7UArYjTFrNCWmndLNcWXtxoHyQ/8NHT4cpAplbmRzdHJlYW0KZW5kb2JqCgo2IDAgb2JqCjQ2MjgKZW5kb2JqCgo3IDAgb2JqCjw8L1R5cGUvRm9udERlc2NyaXB0b3IvRm9udE5hbWUvQkFBQUFBK0xpYmVyYXRpb25TZXJpZgovRmxhZ3MgNAovRm9udEJCb3hbLTU0MyAtMzAzIDEyNzggOTgyXS9JdGFsaWNBbmdsZSAwCi9Bc2NlbnQgODkxCi9EZXNjZW50IC0yMTYKL0NhcEhlaWdodCA5ODEKL1N0ZW1WIDgwCi9Gb250RmlsZTIgNSAwIFIKPj4KZW5kb2JqCgo4IDAgb2JqCjw8L0xlbmd0aCAyNDAvRmlsdGVyL0ZsYXRlRGVjb2RlPj4Kc3RyZWFtCnicXVDLasMwELzrK/aYHIJsx2kvRhASAj70Qd1+gCytXUEtCVk++O+7ktMWepCYYXaG2eWX9tpaE/lrcKrDCIOxOuDslqAQehyNZWUF2qh4Z/lXk/SMk7db54hTawfXNIy/kTbHsMLurF2Pe8ZfgsZg7Ai7j0tHvFu8/8IJbYSCCQEaB8p5kv5ZTsiz69Bqkk1cD2T5G3hfPUKVeblVUU7j7KXCIO2IrCkKAc3tJhha/U+rN0c/qE8ZaLKkyaI41YJwlfHDKeFjxo/HhOsN1znv7kzJafWfxqCWEKhtvk+umQoai78n9M4nV37ft5d0YgplbmRzdHJlYW0KZW5kb2JqCgo5IDAgb2JqCjw8L1R5cGUvRm9udC9TdWJ0eXBlL1RydWVUeXBlL0Jhc2VGb250L0JBQUFBQStMaWJlcmF0aW9uU2VyaWYKL0ZpcnN0Q2hhciAwCi9MYXN0Q2hhciA0Ci9XaWR0aHNbNzc3IDYxMCA0NDMgMzg5IDI3NyBdCi9Gb250RGVzY3JpcHRvciA3IDAgUgovVG9Vbmljb2RlIDggMCBSCj4+CmVuZG9iagoKMTAgMCBvYmoKPDwvRjEgOSAwIFIKPj4KZW5kb2JqCgoxMSAwIG9iago8PC9Gb250IDEwIDAgUgovUHJvY1NldFsvUERGL1RleHRdCj4+CmVuZG9iagoKMSAwIG9iago8PC9UeXBlL1BhZ2UvUGFyZW50IDQgMCBSL1Jlc291cmNlcyAxMSAwIFIvTWVkaWFCb3hbMCAwIDYxMiA3OTJdL0dyb3VwPDwvUy9UcmFuc3BhcmVuY3kvQ1MvRGV2aWNlUkdCL0kgdHJ1ZT4+L0NvbnRlbnRzIDIgMCBSPj4KZW5kb2JqCgo0IDAgb2JqCjw8L1R5cGUvUGFnZXMKL1Jlc291cmNlcyAxMSAwIFIKL01lZGlhQm94WyAwIDAgNjEyIDc5MiBdCi9LaWRzWyAxIDAgUiBdCi9Db3VudCAxPj4KZW5kb2JqCgoxMiAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgNCAwIFIKL09wZW5BY3Rpb25bMSAwIFIgL1hZWiBudWxsIG51bGwgMF0KL0xhbmcoZW4tVVMpCj4+CmVuZG9iagoKMTMgMCBvYmoKPDwvQ3JlYXRvcjxGRUZGMDA1NzAwNzIwMDY5MDA3NDAwNjUwMDcyPgovUHJvZHVjZXI8RkVGRjAwNEMwMDY5MDA2MjAwNzIwMDY1MDA0RjAwNjYwMDY2MDA2OTAwNjMwMDY1MDAyMDAwMzcwMDJFMDAzMj4KL0NyZWF0aW9uRGF0ZShEOjIwMjIwNTIzMDczODM3LTA3JzAwJyk+PgplbmRvYmoKCnhyZWYKMCAxNAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDU3MTUgMDAwMDAgbiAKMDAwMDAwMDAxOSAwMDAwMCBuIAowMDAwMDAwMTk2IDAwMDAwIG4gCjAwMDAwMDU4NTggMDAwMDAgbiAKMDAwMDAwMDIxNiAwMDAwMCBuIAowMDAwMDA0OTI4IDAwMDAwIG4gCjAwMDAwMDQ5NDkgMDAwMDAgbiAKMDAwMDAwNTE0NCAwMDAwMCBuIAowMDAwMDA1NDUzIDAwMDAwIG4gCjAwMDAwMDU2MjggMDAwMDAgbiAKMDAwMDAwNTY2MCAwMDAwMCBuIAowMDAwMDA1OTU3IDAwMDAwIG4gCjAwMDAwMDYwNTQgMDAwMDAgbiAKdHJhaWxlcgo8PC9TaXplIDE0L1Jvb3QgMTIgMCBSCi9JbmZvIDEzIDAgUgovSUQgWyA8ODREQjY2QjEwREU5OTRGNzA1ODlCQTNCRjUzODE4RDg+Cjw4NERCNjZCMTBERTk5NEY3MDU4OUJBM0JGNTM4MThEOD4gXQovRG9jQ2hlY2tzdW0gLzg3MTVEQTJGQzEyOEM2RUY4NzlFREY4RUZGMjRBQTc0Cj4+CnN0YXJ0eHJlZgo2MjI5CiUlRU9GCg==",
              "title": "UploadTest.pdf"
          },
          "provision": {
              "period": {
                  "start": "2022-05-15",
                  "end": "2022-10-10"
              }
          }
        }
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Consent/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Consent/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Consent",
          "id": "a9d3c0d9-e87a-4737-b909-ac81ee62f9a0",
          "status": "inactive",
          "scope": {
              "text": "Unknown"
          },
          "category": [
            {
              "coding": [
                {
                  "system": "internal",
                  "display": "Restraints"
                }
              ]
            }
          ],
          "patient": {
              "reference": "Patient/2c4b29a411b043bfb1c34c8c3683c7ca",
              "type": "Patient"
          },
          "dateTime": "2022-04-13T14:43:32.317476+00:00",
          "sourceAttachment": {
              "url": "https://fumage-example.canvasmedical.com/Consent/a9d3c0d9-e87a-4737-b909-ac81ee62f9a0/files/sourceAttachment"
          },
          "provision": {
              "period": {
                  "start": "2022-04-13",
                  "end": "2022-12-31"
              }
          }
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
            "resourceType": "OperationOutcome",
            "issue": [
                {
                    "severity": "error",
                    "code": "not-found",
                    "details": {
                        "text": "Unknown Consent resource '7d1ce256fcd7408193b0459650937a07'"
                    }
                }
            ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Consent?patient=Patient/2c4b29a411b043bfb1c34c8c3683c7ca' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Consent?patient=Patient/2c4b29a411b043bfb1c34c8c3683c7ca"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Bundle",
          "type": "searchset",
          "total": 486,
          "link": [
            {
              "relation": "self",
              "url": "/Consent?_count=2&_offset=0"
            },
            {
              "relation": "first",
              "url": "/Consent?_count=2&_offset=0"
            },
            {
              "relation": "next",
              "url": "/Consent?_count=2&_offset=2"
            },
            {
              "relation": "last",
              "url": "/Consent?_count=2&_offset=484"
            }
          ],
          "entry": [
            {
              "resource": {
                  "resourceType": "Consent",
                  "id": "a9d3c0d9-e87a-4737-b909-ac81ee62f9a0",
                  "status": "inactive",
                  "scope": {
                      "text": "Unknown"
                  },
                  "category": [
                    {
                      "coding": [
                          {
                            "system": "internal",
                            "display": "Restraints"
                          }
                      ]
                    }
                  ],
                  "patient": {
                      "reference": "Patient/2c4b29a411b043bfb1c34c8c3683c7ca",
                      "type": "Patient"
                  },
                  "dateTime": "2022-04-13T14:43:32.317476+00:00",
                  "sourceAttachment": {
                      "url": "https://fumage-example.canvasmedical.com/Consent/a9d3c0d9-e87a-4737-b909-ac81ee62f9a0/files/sourceAttachment"
                  },
                  "provision": {
                      "period": {
                          "start": "2022-04-13",
                          "end": "2022-12-31"
                      }
                  }
              }
            },
            {
              "resource": {
                "resourceType": "Consent",
                "id": "38a78199-e05f-4967-a203-aa6a1fc1b6da",
                "status": "active",
                "scope": {
                    "text": "Unknown"
                },
                "category": [
                    {
                      "coding": [
                        {
                          "system": "internal",
                          "display": "Photo"
                        }
                      ]
                    }
                ],
                "patient": {
                    "reference": "Patient/2c4b29a411b043bfb1c34c8c3683c7ca",
                    "type": "Patient"
                },
                "dateTime": "2022-04-13T14:45:12.460858+00:00",
                "provision": {
                    "period": {
                        "start": "2022-04-11"
                    }
                }
              }
            }
          ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Coverage

Source: https://docs.canvasmedical.com/api/coverage/

### 
Financial instrument which may be used to reimburse or pay for health care products and services. Includes both insurance and self-payment.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-coverage.html>
#### Additional information
  - The insurance card front and back images in the coverage section of the Canvas UI are uploaded and viewed only through the UI. The API cannot upload them, retrieve them, or tell front from back. A [DocumentReference](/api/documentreference) created through the API lands in the patient's admin documents, not in the coverage card section.
### Endpoints
post/Coverage get/Coverage/{id} put/Coverage/{id} get/Coverage
post
/Coverage
#### Coverage create
### Attributes
resourceType
string
The FHIR Resource name.
identifier
array[json] required
An identifier for the insured of an insurance policy, usually assigned by the insurance carrier.
Click to view child attributes
type
json required
Insurance member ID description
Click to view child attributes
system
required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v2-0203
code
required
The code of the insurance member ID description.
**Value Options Supported:**
  - MB
display
The display name of the coding.
value
string required
Insurance member ID value
status
enum [ active | cancelled ] required
The status of the Coverage.   
In Canvas, the status of `active` means it appears in the Patient's Profile page either under the main or other coverage sections, while a status of `cancelled` means it was removed and no longer appears on the page. An expired coverage will still show as `active`, so be sure to set/read the `period.end` attribute.
Currently there is no way to create a coverage that appears under the "Other Coverages" section on the Patient Profile. All coverages created with `active` will appear as the primary, secondary, tertiary, etc coverage depending on the order number. Coverages created with a `cancelled` status will not appear on the UI, but can still be read out.
type
json
Type of coverage, such as medical, workers compensation, self pay, etc.  
In order for this value to display on the Canvas UI, the coverage type needs to be configured for the specific payor via our insurer settings. To get to these settings, see this [Pylon article](https://help.canvasmedical.com/articles/5877696655-patient-coverages#managing-insurers-68).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/coverage-selfpay
  - http://terminology.hl7.org/CodeSystem/v3-ActCode
code
string required
The code of the coverage type.
**Value Options Supported:**
  - pay
  - ANNU
  - AUTOPOL
  - CHAR
  - COL
  - CRIME
  - DENTAL
  - DENTPRG
  - DIS
  - DISEASE
  - DRUGPOL
  - EAP
  - EWB
  - ENDRENAL
  - EHCPOL
  - FLEXP
  - GOVEMP
  - HIP
  - HMO
  - HSAPOL
  - HIRISK
  - HIVAIDS
  - IND
  - LIFE
  - LTC
  - MCPOL
  - MANDPOL
  - MENTPOL
  - MENTPRG
  - MILITARY
  - POS
  - PPO
  - PNC
  - DISEASEPRG
  - PUBLICPOL
  - REI
  - RETIRE
  - SAFNET
  - SOCIAL
  - SUBSIDIZ
  - SUBSIDMC
  - SUBSUPP
  - SUBPOL
  - SUBPRG
  - SURPL
  - TLIFE
  - UMBRL
  - UNINSMOT
  - ULIFE
  - VET
  - VISPOL
  - CANPRG
  - WCBPOL
display
string
The display name of the coding.
**Value Options Supported:**
  - Pay
  - Annuity policy
  - Automobile
  - Charity program
  - Collision coverage policy
  - Crime victim program
  - Dental care policy
  - Dental program
  - Disability insurance policy
  - Disease specific policy
  - Drug policy
  - Employee assistance program
  - Employee welfare benefit plan policy
  - End renal program
  - Extended healthcare
  - Flexible benefit plan policy
  - Government employee health program
  - Health insurance plan policy
  - Health maintenance organization policy
  - Health spending account
  - High risk pool program
  - HIV-AIDS program
  - Indigenous peoples health program
  - Life insurance policy
  - Long term care policy
  - Managed care policy
  - Mandatory health program
  - Mental health policy
  - Mental health program
  - Military health program
  - Point of service policy
  - Preferred provider organization policy
  - Property and casualty insurance policy
  - Public health program
  - Public healthcare
  - Reinsurance policy
  - Retiree health program
  - Safety net clinic program
  - Social service program
  - Subsidized health program
  - Subsidized managed care program
  - Subsidized supplemental health program
  - Substance use policy
  - Substance use program
  - Surplus line insurance policy
  - Term life insurance policy
  - Umbrella liability insurance policy
  - Uninsured motorist policy
  - Universal life insurance policy
  - Veteran health program
  - Vision care policy
  - Women's cancer detection program
  - Worker's compensation
subscriber
json required
Who was signed up for or 'owns' the Coverage.
Click to view child attributes
reference
string required
The reference string of the patient subscriber in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
subscriberId
string
ID assigned to the subscriber
beneficiary
json required
Who benefits from the coverage; the patient when products or services are provided.
Click to view child attributes
reference
string required
The reference string of the patient beneficiary in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
relationship
json required
The relationship of beneficiary (patient) to the subscriber.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/subscriber-relationship
code
string
The code of the relationship.
**Value Options Supported:**
  - child
  - spouse
  - other
  - self
  - injured
display
string
The display name of the coding.
period
json
If the start date is missing for a create/update interaction, it will be set to the current date of ingestion.
Click to view child attributes
start
date
Starting time with inclusive boundary
end
date
End time with inclusive boundary, if not ongoing.
payor
array[json] required
Issuer of the policy.
Two methods for specifying this data are supported:
  - sending an [**Organization**](/api/organization) reference in `payor[0].reference`
        ```json
          "payor": [
             {
                 "reference": "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728",
                 "type": "Organization",
                 "display": "Medicare Advantage"
             }
           ],
        ```
  - sending a `payor[0].identifier.value` corresponding to the Coverage's payor id. For now, these values can only be found and updated in the [Insurers Admin view](https://canvas-medical.help.usepylon.com/articles/8126548200-managing-insurers) in Canvas.
        ```json
          "payor": [
           {
             "identifier": {
               "system": "https://www.claim.md/services/era/",
               "value": "13162"
             },
             "display": "1199 National Benefit Fund"
           }
         ],
        ```
A `reference` or `identifier.value` is required in a Create/Update.
Click to view child attributes
reference
string
The Organization reference to the Coverage's payor in the format "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728"
type
string
Type the reference refers to (e.g. "Organization").
display
string
The display name of the payor.
identifier
json
Logical reference, when literal reference is not known.
Click to view child attributes
value
string required
The value that is unique. These values can only be found and updated in the [Insurers Admin view](https://help.canvasmedical.com/articles/5877696655-patient-coverages#managing-insurers-68) in Canvas.
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - https://www.claim.md/services/era/
class
json
Additional coverage classifications.  
Only plan and group will be visible in the Canvas UI.
Click to view child attributes
type
json required
Type of class such as 'group' or 'plan'.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/coverage-class
code
string required
The code of the class.
**Value Options Supported:**
  - plan
  - subplan
  - group
  - subgroup
value
string
Value associated with the type, such as plan or group number.
name
string
Human readable description of the type and value, such as plan name or group name.
order
number [ 1-5 ] required
The order in which coverages should be used when adjudicating claims.
The order must between 1 and 5, inclusive.  
If multiple coverages for a patient are created with the same order number, the older one will be bumped down in rank, and the new one will take that rank.  
If this leads to multiple coverages being incremented to 5, the oldest (first to be inputted into Canvas) of the coverages at this rank will be displayed on the Canvas UI.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Coverage/{id}
#### Coverage read
### Path Parameters
id required
string
The unique identifier for the Coverage   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Coverage.
identifier
array[json]
An identifier for the insured of an insurance policy, usually assigned by the insurance carrier.
Click to view child attributes
type
json
Insurance member ID description
Click to view child attributes
system
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v2-0203
code
The code of the insurance member ID description.
**Value Options Supported:**
  - MB
display
The display name of the coding.
value
string
Insurance member ID value
status
enum [ active | cancelled ]
The status of the Coverage.   
In Canvas, the status of `active` means it appears in the Patient's Profile page either under the main or other coverage sections, while a status of `cancelled` means it was removed and no longer appears on the page. An expired coverage will still show as `active`, so be sure to set/read the `period.end` attribute.
type
json
Type of coverage, such as medical, workers compensation, self pay, etc.  
In order for this value to display on the Canvas UI, the coverage type needs to be configured for the specific payor via our insurer settings. To get to these settings, see this [Pylon article](https://help.canvasmedical.com/articles/5877696655-patient-coverages#managing-insurers-68).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/coverage-selfpay
  - http://terminology.hl7.org/CodeSystem/v3-ActCode
code
string
The code of the coverage type.
**Value Options Supported:**
  - pay
  - ANNU
  - AUTOPOL
  - CHAR
  - COL
  - CRIME
  - DENTAL
  - DENTPRG
  - DIS
  - DISEASE
  - DRUGPOL
  - EAP
  - EWB
  - ENDRENAL
  - EHCPOL
  - FLEXP
  - GOVEMP
  - HIP
  - HMO
  - HSAPOL
  - HIRISK
  - HIVAIDS
  - IND
  - LIFE
  - LTC
  - MCPOL
  - MANDPOL
  - MENTPOL
  - MENTPRG
  - MILITARY
  - POS
  - PPO
  - PNC
  - DISEASEPRG
  - PUBLICPOL
  - REI
  - RETIRE
  - SAFNET
  - SOCIAL
  - SUBSIDIZ
  - SUBSIDMC
  - SUBSUPP
  - SUBPOL
  - SUBPRG
  - SURPL
  - TLIFE
  - UMBRL
  - UNINSMOT
  - ULIFE
  - VET
  - VISPOL
  - CANPRG
  - WCBPOL
display
string
The display name of the coding.
**Value Options Supported:**
  - Pay
  - Annuity policy
  - Automobile
  - Charity program
  - Collision coverage policy
  - Crime victim program
  - Dental care policy
  - Dental program
  - Disability insurance policy
  - Disease specific policy
  - Drug policy
  - Employee assistance program
  - Employee welfare benefit plan policy
  - End renal program
  - Extended healthcare
  - Flexible benefit plan policy
  - Government employee health program
  - Health insurance plan policy
  - Health maintenance organization policy
  - Health spending account
  - High risk pool program
  - HIV-AIDS program
  - Indigenous peoples health program
  - Life insurance policy
  - Long term care policy
  - Managed care policy
  - Mandatory health program
  - Mental health policy
  - Mental health program
  - Military health program
  - Point of service policy
  - Preferred provider organization policy
  - Property and casualty insurance policy
  - Public health program
  - Public healthcare
  - Reinsurance policy
  - Retiree health program
  - Safety net clinic program
  - Social service program
  - Subsidized health program
  - Subsidized managed care program
  - Subsidized supplemental health program
  - Substance use policy
  - Substance use program
  - Surplus line insurance policy
  - Term life insurance policy
  - Umbrella liability insurance policy
  - Uninsured motorist policy
  - Universal life insurance policy
  - Veteran health program
  - Vision care policy
  - Women's cancer detection program
  - Worker's compensation
text
string
Plain text representation of the coverage type.
subscriber
json
Who was signed up for or 'owns' the Coverage.
Click to view child attributes
reference
string
The reference string of the patient subscriber in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
subscriberId
string
ID assigned to the subscriber
beneficiary
json
Who benefits from the coverage; the patient when products or services are provided.
Click to view child attributes
reference
string
The reference string of the patient beneficiary in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
relationship
json
The relationship of beneficiary (patient) to the subscriber.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/subscriber-relationship
code
string
The code of the relationship.
**Value Options Supported:**
  - child
  - spouse
  - other
  - self
  - injured
  - parent
  - common
display
string
The display name of the coding.
text
string
The 2 character code that represents the patient relationship to the insured as defined by CMS.
**Value Options Supported:**
  - 18 (Self)
  - 01 (Spouse)
  - 19 (Natural Child, insured has financial responsibility)
  - 43 (Natural Child, insured does not have financial responsibility),
  - 17 (Step Child)
  - 10 (Foster Child)
  - 15 (Ward of the Court)
  - 20 (Employee)
  - 21 (Unknown)
  - 22 (Handicapped Dependent)
  - 39 (Organ donor)
  - 40 (Cadaver donor)
  - 05 (Grandchild)
  - 07 (Niece/Nephew)
  - 41 (Injured Plaintiff)
  - 23 (Sponsored Dependent)
  - 24 (Minor Dependent of a Minor Dependent)
  - 32 (Mother)
  - 33 (Father)
  - 04 (Grandparent)
  - 53 (Life Partner)
  - 29 (Significant Other)
  - G8 (Other)
period
json
The period during which the Coverage is in force.  
A missing end date means the coverage continues to be in force.
Click to view child attributes
start
date
Starting time with inclusive boundary
end
date
End time with inclusive boundary, if not ongoing.
payor
array[json]
Issuer of the policy.
Click to view child attributes
reference
string
The Organization reference to the Coverage's payor in the format "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728"
type
string
Type the reference refers to (e.g. "Organization").
display
string
The display name of the payor.
class
json
Additional coverage classifications.  
Only plan and group will be visible in the Canvas UI.
Click to view child attributes
type
json
Type of class such as 'group' or 'plan'.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/coverage-class
code
string
The code of the class.
**Value Options Supported:**
  - plan
  - subplan
  - group
  - subgroup
value
string
Value associated with the type, such as plan or group number.
name
string
Human readable description of the type and value, such as plan name or group name.
order
number [ 1-5 ]
The order in which coverages should be used when adjudicating claims.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Coverage/{id}
#### Coverage update
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The identifier of the Coverage.
identifier
array[json] required
An identifier for the insured of an insurance policy, usually assigned by the insurance carrier.
Click to view child attributes
type
json required
Insurance member ID description
Click to view child attributes
system
required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v2-0203
code
required
The code of the insurance member ID description.
**Value Options Supported:**
  - MB
display
The display name of the coding.
value
string required
Insurance member ID value
status
enum [ active | cancelled ] required
The status of the Coverage.   
In Canvas, the status of `active` means it appears in the Patient's Profile page either under the main or other coverage sections, while a status of `cancelled` means it was removed and no longer appears on the page. An expired coverage will still show as `active`, so be sure to set/read the `period.end` attribute.
If a coverage in the Canvas UI is in the "Other coverages" section, on an update if the status stays `active`, it will remain in the "Other coverages" section.
type
json
Type of coverage, such as medical, workers compensation, self pay, etc.  
In order for this value to display on the Canvas UI, the coverage type needs to be configured for the specific payor via our insurer settings. To get to these settings, see this [Pylon article](https://help.canvasmedical.com/articles/5877696655-patient-coverages#managing-insurers-68).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/coverage-selfpay
  - http://terminology.hl7.org/CodeSystem/v3-ActCode
code
string required
The code of the coverage type.
**Value Options Supported:**
  - pay
  - ANNU
  - AUTOPOL
  - CHAR
  - COL
  - CRIME
  - DENTAL
  - DENTPRG
  - DIS
  - DISEASE
  - DRUGPOL
  - EAP
  - EWB
  - ENDRENAL
  - EHCPOL
  - FLEXP
  - GOVEMP
  - HIP
  - HMO
  - HSAPOL
  - HIRISK
  - HIVAIDS
  - IND
  - LIFE
  - LTC
  - MCPOL
  - MANDPOL
  - MENTPOL
  - MENTPRG
  - MILITARY
  - POS
  - PPO
  - PNC
  - DISEASEPRG
  - PUBLICPOL
  - REI
  - RETIRE
  - SAFNET
  - SOCIAL
  - SUBSIDIZ
  - SUBSIDMC
  - SUBSUPP
  - SUBPOL
  - SUBPRG
  - SURPL
  - TLIFE
  - UMBRL
  - UNINSMOT
  - ULIFE
  - VET
  - VISPOL
  - CANPRG
  - WCBPOL
display
string
The display name of the coding.
**Value Options Supported:**
  - Pay
  - Annuity policy
  - Automobile
  - Charity program
  - Collision coverage policy
  - Crime victim program
  - Dental care policy
  - Dental program
  - Disability insurance policy
  - Disease specific policy
  - Drug policy
  - Employee assistance program
  - Employee welfare benefit plan policy
  - End renal program
  - Extended healthcare
  - Flexible benefit plan policy
  - Government employee health program
  - Health insurance plan policy
  - Health maintenance organization policy
  - Health spending account
  - High risk pool program
  - HIV-AIDS program
  - Indigenous peoples health program
  - Life insurance policy
  - Long term care policy
  - Managed care policy
  - Mandatory health program
  - Mental health policy
  - Mental health program
  - Military health program
  - Point of service policy
  - Preferred provider organization policy
  - Property and casualty insurance policy
  - Public health program
  - Public healthcare
  - Reinsurance policy
  - Retiree health program
  - Safety net clinic program
  - Social service program
  - Subsidized health program
  - Subsidized managed care program
  - Subsidized supplemental health program
  - Substance use policy
  - Substance use program
  - Surplus line insurance policy
  - Term life insurance policy
  - Umbrella liability insurance policy
  - Uninsured motorist policy
  - Universal life insurance policy
  - Veteran health program
  - Vision care policy
  - Women's cancer detection program
  - Worker's compensation
subscriber
json required
Who was signed up for or 'owns' the Coverage.
Click to view child attributes
reference
string required
The reference string of the patient subscriber in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
subscriberId
string
ID assigned to the subscriber
beneficiary
json required
Who benefits from the coverage; the patient when products or services are provided.
Click to view child attributes
reference
string required
The reference string of the patient beneficiary in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
relationship
json required
The relationship of beneficiary (patient) to the subscriber.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/subscriber-relationship
code
string
The code of the relationship.
**Value Options Supported:**
  - child
  - spouse
  - other
  - self
  - injured
display
string
The display name of the coding.
period
json
If the start date is missing for a create/update interaction, it will be set to the current date of ingestion.
Click to view child attributes
start
date
Starting time with inclusive boundary
end
date
End time with inclusive boundary, if not ongoing.
payor
array[json] required
Issuer of the policy.
Two methods for specifying this data are supported:
  - sending an [**Organization**](/api/organization) reference in `payor[0].reference`
        ```json
          "payor": [
             {
                 "reference": "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728",
                 "type": "Organization",
                 "display": "Medicare Advantage"
             }
           ],
        ```
  - sending a `payor[0].identifier.value` corresponding to the Coverage's payor id. For now, these values can only be found and updated in the [Insurers Admin view](https://canvas-medical.help.usepylon.com/articles/8126548200-managing-insurers) in Canvas.
        ```json
          "payor": [
           {
             "identifier": {
               "system": "https://www.claim.md/services/era/",
               "value": "13162"
             },
             "display": "1199 National Benefit Fund"
           }
         ],
        ```
A `reference` or `identifier.value` is required in a Create/Update.
Click to view child attributes
reference
string
The Organization reference to the Coverage's payor in the format "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728"
type
string
Type the reference refers to (e.g. "Organization").
display
string
The display name of the payor.
identifier
json
Logical reference, when literal reference is not known.
Click to view child attributes
value
string required
The value that is unique. These values can only be found and updated in the [Insurers Admin view](https://help.canvasmedical.com/articles/5877696655-patient-coverages#managing-insurers-68) in Canvas.
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - https://www.claim.md/services/era/
class
json
Additional coverage classifications.  
Only plan and group will be visible in the Canvas UI.
Click to view child attributes
type
json required
Type of class such as 'group' or 'plan'.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/coverage-class
code
string required
The code of the class.
**Value Options Supported:**
  - plan
  - subplan
  - group
  - subgroup
value
string
Value associated with the type, such as plan or group number.
name
string
Human readable description of the type and value, such as plan name or group name.
order
number [ 1-5 ] required
The order in which coverages should be used when adjudicating claims.
The order must between 1 and 5, inclusive.  
If multiple coverages for a patient are created with the same order number, the older one will be bumped down in rank, and the new one will take that rank.  
If this leads to multiple coverages being incremented to 5, the oldest (first to be inputted into Canvas) of the coverages at this rank will be displayed on the Canvas UI.
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Coverage
#### Coverage search
Search for Coverage resources. Search does not filter by date; each Coverage's effective dates are in its `period.start` and `period.end`.
### Query Parameters
****
_id
string
The Canvas resource identifier of the Coverage.
patient
string
Retrieve coverages for a patient in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
identifier
string
Retrieve all coverages with a specific member ID
subscriberid
string
Retrieve all coverages with a specific subscriber ID
status
string
Retrieve coverages by a specific status.
**Search Values Supported:**
  - active
  - cancelled
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Coverage.
identifier
array[json]
An identifier for the insured of an insurance policy, usually assigned by the insurance carrier.
Click to view child attributes
type
json
Insurance member ID description
Click to view child attributes
system
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v2-0203
code
The code of the insurance member ID description.
**Value Options Supported:**
  - MB
display
The display name of the coding.
value
string
Insurance member ID value
status
enum [ active | cancelled ]
The status of the Coverage.   
In Canvas, the status of `active` means it appears in the Patient's Profile page either under the main or other coverage sections, while a status of `cancelled` means it was removed and no longer appears on the page. An expired coverage will still show as `active`, so be sure to set/read the `period.end` attribute.
type
json
Type of coverage, such as medical, workers compensation, self pay, etc.  
In order for this value to display on the Canvas UI, the coverage type needs to be configured for the specific payor via our insurer settings. To get to these settings, see this [Pylon article](https://help.canvasmedical.com/articles/5877696655-patient-coverages#managing-insurers-68).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/coverage-selfpay
  - http://terminology.hl7.org/CodeSystem/v3-ActCode
code
string
The code of the coverage type.
**Value Options Supported:**
  - pay
  - ANNU
  - AUTOPOL
  - CHAR
  - COL
  - CRIME
  - DENTAL
  - DENTPRG
  - DIS
  - DISEASE
  - DRUGPOL
  - EAP
  - EWB
  - ENDRENAL
  - EHCPOL
  - FLEXP
  - GOVEMP
  - HIP
  - HMO
  - HSAPOL
  - HIRISK
  - HIVAIDS
  - IND
  - LIFE
  - LTC
  - MCPOL
  - MANDPOL
  - MENTPOL
  - MENTPRG
  - MILITARY
  - POS
  - PPO
  - PNC
  - DISEASEPRG
  - PUBLICPOL
  - REI
  - RETIRE
  - SAFNET
  - SOCIAL
  - SUBSIDIZ
  - SUBSIDMC
  - SUBSUPP
  - SUBPOL
  - SUBPRG
  - SURPL
  - TLIFE
  - UMBRL
  - UNINSMOT
  - ULIFE
  - VET
  - VISPOL
  - CANPRG
  - WCBPOL
display
string
The display name of the coding.
**Value Options Supported:**
  - Pay
  - Annuity policy
  - Automobile
  - Charity program
  - Collision coverage policy
  - Crime victim program
  - Dental care policy
  - Dental program
  - Disability insurance policy
  - Disease specific policy
  - Drug policy
  - Employee assistance program
  - Employee welfare benefit plan policy
  - End renal program
  - Extended healthcare
  - Flexible benefit plan policy
  - Government employee health program
  - Health insurance plan policy
  - Health maintenance organization policy
  - Health spending account
  - High risk pool program
  - HIV-AIDS program
  - Indigenous peoples health program
  - Life insurance policy
  - Long term care policy
  - Managed care policy
  - Mandatory health program
  - Mental health policy
  - Mental health program
  - Military health program
  - Point of service policy
  - Preferred provider organization policy
  - Property and casualty insurance policy
  - Public health program
  - Public healthcare
  - Reinsurance policy
  - Retiree health program
  - Safety net clinic program
  - Social service program
  - Subsidized health program
  - Subsidized managed care program
  - Subsidized supplemental health program
  - Substance use policy
  - Substance use program
  - Surplus line insurance policy
  - Term life insurance policy
  - Umbrella liability insurance policy
  - Uninsured motorist policy
  - Universal life insurance policy
  - Veteran health program
  - Vision care policy
  - Women's cancer detection program
  - Worker's compensation
text
string
Plain text representation of the coverage type.
subscriber
json
Who was signed up for or 'owns' the Coverage.
Click to view child attributes
reference
string
The reference string of the patient subscriber in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
subscriberId
string
ID assigned to the subscriber
beneficiary
json
Who benefits from the coverage; the patient when products or services are provided.
Click to view child attributes
reference
string
The reference string of the patient beneficiary in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
relationship
json
The relationship of beneficiary (patient) to the subscriber.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/subscriber-relationship
code
string
The code of the relationship.
**Value Options Supported:**
  - child
  - spouse
  - other
  - self
  - injured
  - parent
  - common
display
string
The display name of the coding.
text
string
The 2 character code that represents the patient relationship to the insured as defined by CMS.
**Value Options Supported:**
  - 18 (Self)
  - 01 (Spouse)
  - 19 (Natural Child, insured has financial responsibility)
  - 43 (Natural Child, insured does not have financial responsibility),
  - 17 (Step Child)
  - 10 (Foster Child)
  - 15 (Ward of the Court)
  - 20 (Employee)
  - 21 (Unknown)
  - 22 (Handicapped Dependent)
  - 39 (Organ donor)
  - 40 (Cadaver donor)
  - 05 (Grandchild)
  - 07 (Niece/Nephew)
  - 41 (Injured Plaintiff)
  - 23 (Sponsored Dependent)
  - 24 (Minor Dependent of a Minor Dependent)
  - 32 (Mother)
  - 33 (Father)
  - 04 (Grandparent)
  - 53 (Life Partner)
  - 29 (Significant Other)
  - G8 (Other)
period
json
The period during which the Coverage is in force.  
A missing end date means the coverage continues to be in force.
Click to view child attributes
start
date
Starting time with inclusive boundary
end
date
End time with inclusive boundary, if not ongoing.
payor
array[json]
Issuer of the policy.
Click to view child attributes
reference
string
The Organization reference to the Coverage's payor in the format "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728"
type
string
Type the reference refers to (e.g. "Organization").
display
string
The display name of the payor.
class
json
Additional coverage classifications.  
Only plan and group will be visible in the Canvas UI.
Click to view child attributes
type
json
Type of class such as 'group' or 'plan'.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/coverage-class
code
string
The code of the class.
**Value Options Supported:**
  - plan
  - subplan
  - group
  - subgroup
value
string
Value associated with the type, such as plan or group number.
name
string
Human readable description of the type and value, such as plan name or group name.
order
number [ 1-5 ]
The order in which coverages should be used when adjudicating claims.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Coverage' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
          "resourceType": "Coverage",
          "identifier": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                    "code": "MB",
                    "display": "Member Number"
                  }
                ]
              },
              "value": "1234"
            }
          ],
          "status": "active",
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
                "code": "MILITARY",
                "display": "military health program"
              }
            ]
          },
          "subscriber": {
            "reference": "Patient/febae9dcb7cf4d88ba27cc552a3f96b34"
          },
          "subscriberId": "123",
          "beneficiary": {
            "reference": "Patient/febae9dcb7cf4d88ba27cc552a3f96b3"
          },
          "relationship": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
                "code": "self"
              }
            ]
          },
          "period": {
            "start": "2021-06-27",
            "end": "2023-06-27"
          },
          "payor": [
            {
              "reference": "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728",
              "type": "Organization",
              "display": "Medicare Advantage"
            }
          ],
          "class": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "plan"
                  }
                ]
              },
              "value": "Starfleet HMO",
              "name": "Starfleet HMO"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "subplan"
                  }
                ]
              },
              "value": "Stars",
              "name": "Stars"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "group"
                  }
                ]
              },
              "value": "Captains Only",
              "name": "Captains Only"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "subgroup"
                  }
                ]
              },
              "value": "Subgroup 2",
              "name": "Subgroup 2"
            }
          ],
          "order": 1
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Coverage"
        payload = {
          "resourceType": "Coverage",
          "identifier": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                    "code": "MB",
                    "display": "Member Number"
                  }
                ]
              },
              "value": "1234"
            }
          ],
          "status": "active",
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
                "code": "MILITARY",
                "display": "military health program"
              }
            ]
          },
          "subscriber": { "reference": "Patient/febae9dcb7cf4d88ba27cc552a3f96b34" },
          "subscriberId": "123",
          "beneficiary": { "reference": "Patient/febae9dcb7cf4d88ba27cc552a3f96b3" },
          "relationship": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
                "code": "self"
              }
            ]
          },
          "period": {
            "start": "2021-06-27",
            "end": "2023-06-27"
          },
          "payor": [
            {
              "reference": "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728",
              "type": "Organization",
              "display": "Medicare Advantage"
            }
          ],
          "class": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "plan"
                  }
                ]
              },
              "value": "Starfleet HMO",
              "name": "Starfleet HMO"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "subplan"
                  }
                ]
              },
              "value": "Stars",
              "name": "Stars"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "group"
                  }
                ]
              },
              "value": "Captains Only",
              "name": "Captains Only"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "subgroup"
                  }
                ]
              },
              "value": "Subgroup 2",
              "name": "Subgroup 2"
            }
          ],
          "order": 1
        }
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Coverage/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Coverage/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Coverage",
          "id": "a7c6af04-a22f-47bf-9cc8-d41158b2ad62",
          "identifier": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                    "code": "MB",
                    "display": "Member Number"
                  }
                ]
              },
              "value": "12345"
            }
          ],
          "status": "active",
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
                "code": "MILITARY",
                "display": "Military health program"
              }
            ]
          },
          "subscriber": {
            "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
            "type": "Patient"
          },
          "subscriberId": "1234",
          "beneficiary": {
            "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
            "type": "Patient"
          },
          "relationship": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
                "code": "self",
                "display": "Self"
              }
            ],
            "text": "18"
          },
          "period": {
            "start": "2023-09-19"
          },
          "payor": [
            {
              "reference": "Organization/c152eeb7-f204-4e28-acb5-c7e85390b17e",
              "type": "Organization",
              "display": " Custody Medical Services Program"
            }
          ],
          "class": [
              {
                "type": {
                  "coding": [
                    {
                      "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                      "code": "plan"
                    }
                  ]
                },
                "value": "Starfleet HMO",
                "name": "Starfleet HMO"
              },
              {
                "type": {
                  "coding": [
                    {
                      "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                      "code": "subplan"
                    }
                  ]
                },
                "value": "Stars",
                "name": "Stars"
              },
              {
                "type": {
                  "coding": [
                    {
                      "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                      "code": "group"
                    }
                  ]
                },
                "value": "Captains Only",
                "name": "Captains Only"
              },
              {
                "type": {
                  "coding": [
                    {
                      "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                      "code": "subgroup"
                    }
                  ]
                },
                "value": "Subgroup 2",
                "name": "Subgroup 2"
              }
          ],
          "order": 1
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Coverage resource 'c152eeb7-f204-4e28-acb5-c7e85390b17e'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/Coverage/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
          "resourceType": "Coverage",
          "identifier": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                    "code": "MB",
                    "display": "Member Number"
                  }
                ]
              },
              "value": "1234"
            }
          ],
          "status": "active",
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
                "code": "MILITARY",
                "display": "military health program"
              }
            ]
          },
          "subscriber": {
            "reference": "Patient/febae9dcb7cf4d88ba27cc552a3f96b34"
          },
          "subscriberId": "123",
          "beneficiary": {
            "reference": "Patient/febae9dcb7cf4d88ba27cc552a3f96b3"
          },
          "relationship": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
                "code": "self"
              }
            ]
          },
          "period": {
            "start": "2021-06-27",
            "end": "2023-06-27"
          },
          "payor": [
            {
              "reference": "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728",
              "type": "Organization",
              "display": "Medicare Advantage"
            }
          ],
          "class": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "plan"
                  }
                ]
              },
              "value": "Starfleet HMO",
              "name": "Starfleet HMO"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "subplan"
                  }
                ]
              },
              "value": "Stars",
              "name": "Stars"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "group"
                  }
                ]
              },
              "value": "Captains Only",
              "name": "Captains Only"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "subgroup"
                  }
                ]
              },
              "value": "Subgroup 2",
              "name": "Subgroup 2"
            }
          ],
          "order": 1
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Coverage/<id>"
        payload = {
          "resourceType": "Coverage",
          "identifier": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                    "code": "MB",
                    "display": "Member Number"
                  }
                ]
              },
              "value": "1234"
            }
          ],
          "status": "active",
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
                "code": "MILITARY",
                "display": "military health program"
              }
            ]
          },
          "subscriber": { "reference": "Patient/febae9dcb7cf4d88ba27cc552a3f96b34" },
          "subscriberId": "123",
          "beneficiary": { "reference": "Patient/febae9dcb7cf4d88ba27cc552a3f96b3" },
          "relationship": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
                "code": "self"
              }
            ]
          },
          "period": {
            "start": "2021-06-27",
            "end": "2023-06-27"
          },
          "payor": [
            {
              "reference": "Organization/6741b035-2846-45b3-b7a3-251f7b7fc728",
              "type": "Organization",
              "display": "Medicare Advantage"
            }
          ],
          "class": [
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "plan"
                  }
                ]
              },
              "value": "Starfleet HMO",
              "name": "Starfleet HMO"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "subplan"
                  }
                ]
              },
              "value": "Stars",
              "name": "Stars"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "group"
                  }
                ]
              },
              "value": "Captains Only",
              "name": "Captains Only"
            },
            {
              "type": {
                "coding": [
                  {
                    "system": "http://terminology.hl7.org/CodeSystem/coverage-class",
                    "code": "subgroup"
                  }
                ]
              },
              "value": "Subgroup 2",
              "name": "Subgroup 2"
            }
          ],
          "order": 1
        }
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Coverage resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Coverage?identifier=12345&patient=Patient/b3084f7e884e4af2b7e23b1dca494abd' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Coverage?identifier=12345&patient=Patient/b3084f7e884e4af2b7e23b1dca494abd"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Bundle",
          "type": "searchset",
          "total": 2,
          "link": [
            {
                "relation": "self",
                "url": "/Coverage?identifier=12345&patient=Patient%2Fb3084f7e884e4af2b7e23b1dca494abd&_count=10&_offset=0"
            },
            {
                "relation": "first",
                "url": "/Coverage?identifier=12345&patient=Patient%2Fb3084f7e884e4af2b7e23b1dca494abd&_count=10&_offset=0"
            },
            {
                "relation": "last",
                "url": "/Coverage?identifier=12345&patient=Patient%2Fb3084f7e884e4af2b7e23b1dca494abd&_count=10&_offset=0"
            }
          ],
          "entry": [
            {
              "resource": {
                "resourceType": "Coverage",
                "id": "171a7243-f568-48cb-8052-3f2990dac1cd",
                "identifier": [
                  {
                    "type": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                          "code": "MB",
                          "display": "Member Number"
                        }
                      ]
                    },
                    "value": "11111"
                  }
                ],
                "status": "cancelled",
                "subscriber": {
                    "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
                    "type": "Patient"
                },
                "subscriberId": "1111",
                "beneficiary": {
                    "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
                    "type": "Patient"
                },
                "relationship": {
                  "coding": [
                    {
                      "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
                      "code": "self",
                      "display": "Self"
                    }
                  ],
                  "text": "18"
                },
                "period": {
                    "start": "2022-01-01"
                },
                "payor": [
                  {
                    "reference": "Organization/9b6709aa-a84e-4070-9a83-7c14dc31a511",
                    "type": "Organization",
                    "display": "AL BCBS"
                  }
                ],
                "order": 2
              }
            },
            {
              "resource": {
                "resourceType": "Coverage",
                "id": "27f42512-23e6-4c17-8569-80e14792b6f8",
                "identifier": [
                  {
                    "type": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                          "code": "MB",
                          "display": "Member Number"
                        }
                      ]
                    },
                    "value": "A1"
                  }
                ],
                "status": "cancelled",
                "subscriber": {
                    "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
                    "type": "Patient"
                },
                "subscriberId": "A",
                "beneficiary": {
                    "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd",
                    "type": "Patient"
                },
                "relationship": {
                  "coding": [
                    {
                      "system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
                      "code": "self",
                      "display": "Self"
                    }
                  ],
                  "text": "18"
                },
                "period": {
                    "start": "2022-05-31"
                },
                "payor": [
                  {
                    "reference": "Organization/02211bf5-9ee1-47d1-a1bc-e06bd848e5f3",
                    "type": "Organization",
                    "display": "Kevin Carey Insurance, Inc."
                  }
                ],
                "order": 1
              }
            }
          ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# CoverageEligibilityRequest

Source: https://docs.canvasmedical.com/api/coverageeligibilityrequest/

### 
The CoverageEligibilityRequest provides patient and insurance coverage information to an insurer for them to respond, in the form of an CoverageEligibilityResponse, with information regarding whether the stated coverage is valid and in-force.  
<https://hl7.org/fhir/R4/coverageeligibilityrequest.html>
### Endpoints
post/CoverageEligibilityRequest
post
/CoverageEligibilityRequest
#### CoverageEligibilityRequest create
If Claim.MD is set up in your Canvas instance, a creation of a coverage CoverageEligibilityRequest will kick off a request to Claim.MD to fetch the eligibility information. Use the returned `id` in the response.headers['location'] attribute to perform a [CoverageEligibilityResponse Search](/api/coverageeligibilityresponse/#search) to see what response Claim.MD returned.
### Attributes
resourceType
string
The FHIR Resource name.
status
string required
Describes the state the request is in.
**Value Options Supported:**
  - active
purpose
array[string] required
What information is being requested.  
Supported values: only **["benefits"]** is valid
patient
json required
Canvas patient resource whom the CoverageEligibilityRequest is for.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
date required
Creation date, required by the FHIR specification, but unused by Canvas as it will be defaulted to the Canvas ingestion timestamp.  
Canvas recommends sending the current datetime in ISO 8601 format.
insurer
json required
Coverage issuer, required by the FHIR schema but unused by Canvas because we inherit the issuer directly from the Coverage resource provided.  
Canvas recommends setting `insurer` to `{}`.
insurance
array[json] required
Patient insurance information.  
Canvas requires a single coverage resource identifying the insurance to check eligibility against.
Click to view child attributes
coverage
json required
Insurance information.
Click to view child attributes
reference
string required
The reference string of the coverage in the format of `"Coverage/f7663d7b-13bd-4236-843e-086306aea125"`.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/CoverageEligibilityRequest' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "CoverageEligibilityRequest",
            "status": "active",
            "purpose": [
                "benefits"
            ],
            "patient": {
                "reference": "Patient/9713f5a3c8464a2587912e80bc2dd938"
            },
            "created": "2023-09-19",
            "insurer": {},
            "insurance": [
                {
                    "focal": true,
                    "coverage": {
                        "reference": "Coverage/743aa331-2f85-420b-ab10-8a6b7bb6a1cf"
                    }
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/CoverageEligibilityRequest"
        payload = {
            "resourceType": "CoverageEligibilityRequest",
            "status": "active",
            "purpose": [
                "benefits"
            ],
            "patient": {
                "reference": "Patient/9713f5a3c8464a2587912e80bc2dd938"
            },
            "created": "2023-09-19",
            "insurer": {},
            "insurance": [
                {
                    "focal": True,
                    "coverage": {
                        "reference": "Coverage/743aa331-2f85-420b-ab10-8a6b7bb6a1cf"
                    }
                }
            ]
        }
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```

---

# CoverageEligibilityResponse

Source: https://docs.canvasmedical.com/api/coverageeligibilityresponse/

### 
The CoverageEligibilityResponse resource provides eligibility and plan details from processing a CoverageEligibilityRequest resource. It combines key information from a payor as to whether a Coverage is in-force, and optionally the nature of the Policy benefit details as well as the ability for the insurer to indicate whether the insurance provides benefits for requested types of services or requires preauthorization and if so what supporting information may be required.  
<https://hl7.org/fhir/R4/coverageeligibilityresponse.html>
### Endpoints
get/CoverageEligibilityResponse/{id} get/CoverageEligibilityResponse
get
/CoverageEligibilityResponse/{id}
#### CoverageEligibilityResponse read
### Path Parameters
id required
string
The unique identifier for the CoverageEligibilityResponse   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the CoverageEligibilityResponse.
status
string
Status of the resource. The value is "entered-in-error" if the call to the third-party eligibility service failed.
**Value Options Supported:**
  - active
  - draft
  - entered-in-error
purpose
array[string]
Reason for the request, will always be **["benefits"]**
patient
json
Patient resource the CoverageEligibilityResponse is for.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
datetime
Response creation date.
request
json
CoverageEligibilityRequest reference the elibibility response is for.
Click to view child attributes
reference
string
The reference string of the request in the format of `"CoverageEligibilityRequest/cd98975b-6cd4-413d-ab65-1fc5eec76762"`.
type
string
Type the reference refers to (e.g. "CoverageEligibilityRequest").
outcome
string
Outcome of the request processing, if an error occurs it will be marked as **"error"** othervise it will be marked as **"complete"**.
**Value Options Supported:**
  - error
  - complete
insurer
json
Coverage issuer.
Click to view child attributes
string
Payor ID for the Coverage issuer.
string
Text alternative for the resource.
insurance
array[json]
Patient insurance information. This includes the **Coverage** reference, extension for plan name and an array of items containing benefits and authorization details returned from Claim.MD.  
The amount of information surfaced here depends on the what the payor supports. Our clearinghouse (Claim.md) performs these eligibility checks, but not all coverages will support real-time eligibility checks. For more information on coverages within Canvas, see this [article](https://canvas-medical.help.usepylon.com/articles/5877696655-patient-coverages).
Click to view child attributes
coverage
json
Insurance information.
Click to view child attributes
reference
string
The reference string of the coverage in the format of `"Coverage/4a86f580-e192-489a-a9f0-7c915fc67111"`.
type
string
Type the reference refers to (e.g. "Coverage").
extension
array[json]
Canvas supports a plan name extension on this resource for read and search interactions.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/active-health-benefit-plan-coverage-description
valueString
string
The plan name of the insurance.
item
array[json]
Array of items containing benefits and authorization details.
Click to view child attributes
name
string
Short name for the benefit
unit
json
Individual or family.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/benefit-unit
code
string
The code of the benefit unit.
**Value Options Supported:**
  - individual
  - family
display
string
The display name of the coding.
**Value Options Supported:**
  - Individual
  - Family
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Individual
  - Family
network
json
In or out of network.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/benefit-network
code
string
The code of the benefit network.
**Value Options Supported:**
  - in
  - out
display
string
The display name of the coding.
**Value Options Supported:**
  - In Network
  - Out of Network
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - In Network
  - Out of Network
benefit
array[json]
Benefit Summary.
Click to view child attributes
type
json
Benefit classification.
Click to view child attributes
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Co-Insurance
  - Co-Payment
  - Active Coverage
  - Deductible
  - Out of Pocket (Stop Loss)
  - Limitations
  - Contact following entity for eligibility or benefit information
  - (Incomplete information)
allowedString
string
Benefits allowed.   
Used for Co-Insurance benefit types.
allowedMoney
json
Benefits allowed.   
Used for Co-Payment, Deductible, or Out of Pocket benefit types.
Click to view child attributes
value
decimal
Numerical value (with implicit precision)
allowedUnsignedInt
unsignedInt
Benefits allowed.   
Used for Limitations benefit types.
usedMoney
json
Benefits used.   
Used for Deductible or Out of Pocket benefit types.
Click to view child attributes
value
decimal
Numerical value (with implicit precision)
usedUnsignedInt
unsignedInt
Benefits used.   
Used for Limitations benefit types.
extension
array[json]
Canvas supports a benefit message extension on each benefit line for read and search interactions. It is present only when the payor returned a note for that line, and repeats once per note.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/eligibility-benefit-message
valueString
string
The payor's note for this benefit line, for example "Primary Care Visit or Evaluation" or "Specialist Visit or Evaluation".  
Payors commonly return several copay or coinsurance lines under one service type and distinguish them only in this note, so it is what identifies which line is which.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/CoverageEligibilityResponse
#### CoverageEligibilityResponse search
### Query Parameters
****
_id
string
The Canvas resource identifier of the CoverageEligibilityResponse.
patient
string
The patient reference associated with the CoverageEligibilityResponse in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
request
string
The coverage eligibility request reference associated with the CoverageEligibilityResponse in the format `"CoverageEligibilityRequest/cd98975b-6cd4-413d-ab65-1fc5eec76762"`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the CoverageEligibilityResponse.
status
string
Status of the resource. The value is "entered-in-error" if the call to the third-party eligibility service failed.
**Value Options Supported:**
  - active
  - draft
  - entered-in-error
purpose
array[string]
Reason for the request, will always be **["benefits"]**
patient
json
Patient resource the CoverageEligibilityResponse is for.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
datetime
Response creation date.
request
json
CoverageEligibilityRequest reference the elibibility response is for.
Click to view child attributes
reference
string
The reference string of the request in the format of `"CoverageEligibilityRequest/cd98975b-6cd4-413d-ab65-1fc5eec76762"`.
type
string
Type the reference refers to (e.g. "CoverageEligibilityRequest").
outcome
string
Outcome of the request processing, if an error occurs it will be marked as **"error"** othervise it will be marked as **"complete"**.
**Value Options Supported:**
  - error
  - complete
insurer
json
Coverage issuer.
Click to view child attributes
string
Payor ID for the Coverage issuer.
string
Text alternative for the resource.
insurance
array[json]
Patient insurance information. This includes the **Coverage** reference, extension for plan name and an array of items containing benefits and authorization details returned from Claim.MD.  
The amount of information surfaced here depends on the what the payor supports. Our clearinghouse (Claim.md) performs these eligibility checks, but not all coverages will support real-time eligibility checks. For more information on coverages within Canvas, see this [article](https://canvas-medical.help.usepylon.com/articles/5877696655-patient-coverages).
Click to view child attributes
coverage
json
Insurance information.
Click to view child attributes
reference
string
The reference string of the coverage in the format of `"Coverage/4a86f580-e192-489a-a9f0-7c915fc67111"`.
type
string
Type the reference refers to (e.g. "Coverage").
extension
array[json]
Canvas supports a plan name extension on this resource for read and search interactions.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/active-health-benefit-plan-coverage-description
valueString
string
The plan name of the insurance.
item
array[json]
Array of items containing benefits and authorization details.
Click to view child attributes
name
string
Short name for the benefit
unit
json
Individual or family.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/benefit-unit
code
string
The code of the benefit unit.
**Value Options Supported:**
  - individual
  - family
display
string
The display name of the coding.
**Value Options Supported:**
  - Individual
  - Family
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Individual
  - Family
network
json
In or out of network.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/benefit-network
code
string
The code of the benefit network.
**Value Options Supported:**
  - in
  - out
display
string
The display name of the coding.
**Value Options Supported:**
  - In Network
  - Out of Network
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - In Network
  - Out of Network
benefit
array[json]
Benefit Summary.
Click to view child attributes
type
json
Benefit classification.
Click to view child attributes
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - Co-Insurance
  - Co-Payment
  - Active Coverage
  - Deductible
  - Out of Pocket (Stop Loss)
  - Limitations
  - Contact following entity for eligibility or benefit information
  - (Incomplete information)
allowedString
string
Benefits allowed.   
Used for Co-Insurance benefit types.
allowedMoney
json
Benefits allowed.   
Used for Co-Payment, Deductible, or Out of Pocket benefit types.
Click to view child attributes
value
decimal
Numerical value (with implicit precision)
allowedUnsignedInt
unsignedInt
Benefits allowed.   
Used for Limitations benefit types.
usedMoney
json
Benefits used.   
Used for Deductible or Out of Pocket benefit types.
Click to view child attributes
value
decimal
Numerical value (with implicit precision)
usedUnsignedInt
unsignedInt
Benefits used.   
Used for Limitations benefit types.
extension
array[json]
Canvas supports a benefit message extension on each benefit line for read and search interactions. It is present only when the payor returned a note for that line, and repeats once per note.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/eligibility-benefit-message
valueString
string
The payor's note for this benefit line, for example "Primary Care Visit or Evaluation" or "Specialist Visit or Evaluation".  
Payors commonly return several copay or coinsurance lines under one service type and distinguish them only in this note, so it is what identifies which line is which.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/CoverageEligibilityResponse/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/CoverageEligibilityResponse/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "CoverageEligibilityResponse",
          "id": "9ad12f4e-4f35-4f54-8b4f-036516488191",
          "status": "active",
          "purpose": [
              "benefits"
          ],
          "patient": {
              "reference": "Patient/b41c7cda738d440cb55e0e6cb67499a1",
              "type": "Patient"
          },
          "created": "2023-09-19T18:16:39.551617+00:00",
          "request": {
              "reference": "CoverageEligibilityRequest/d7254641-e363-488c-91fa-b93a6170b9e0",
              "type": "CoverageEligibilityRequest"
          },
          "outcome": "complete",
          "insurer": {
              "identifier": "1111",
              "display": "Payer ID: 1111"
          },
          "insurance": [
            {
              "extension": [
                {
                  "url": "http://schemas.canvasmedical.com/fhir/extensions/active-health-benefit-plan-coverage-description",
                  "valueString": "Humana Gold Plus"
                }
              ],
              "coverage": {
                  "reference": "Coverage/4a86f580-e192-489a-a9f0-7c915fc67111",
                  "type": "Coverage"
              },
              "item": [
                {
                  "network": {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                        "code": "in",
                        "display": "In Network"
                      }
                    ],
                    "text": "In Network"
                  },
                  "unit": {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                        "code": "individual",
                        "display": "Individual"
                      }
                    ],
                    "text": "Individual"
                  },
                  "benefit": [
                    {
                      "type": {
                          "text": "Co-Payment"
                      },
                      "allowedMoney": {
                          "value": 333
                      }
                    },
                    {
                      "type": {
                          "text": "Co-Insurance"
                      },
                      "allowedString": "0.0%"
                    }
                  ]
                },
                {
                  "network": {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                        "code": "in",
                        "display": "In Network"
                      }
                    ],
                    "text": "In Network"
                  },
                  "unit": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                          "code": "individual",
                          "display": "Individual"
                        }
                      ],
                      "text": "Individual"
                  },
                    "benefit": [
                      {
                        "type": {
                            "text": "Co-Insurance"
                        },
                        "allowedString": "0.0%"
                      },
                      {
                        "type": {
                            "text": "Co-Insurance"
                        },
                        "allowedString": "0.0%"
                      },
                      {
                        "type": {
                            "text": "Co-Insurance"
                        },
                        "allowedString": "0.0%"
                      }
                    ]
                },
                {
                  "benefit": [
                    {
                      "type": {
                          "text": "Benefit Description (Incomplete information)"
                      }
                    }
                  ]
                },
                {
                  "benefit": [
                    {
                      "type": {
                          "text": "Active Coverage"
                      }
                    }
                  ]
                },
                {
                  "network": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                          "code": "in",
                          "display": "In Network"
                        }
                      ],
                      "text": "In Network"
                  },
                  "benefit": [
                    {
                      "type": {
                          "text": "Active Coverage"
                      }
                    },
                    {
                      "type": {
                          "text": "Primary Care Provider (Incomplete information)"
                      }
                    },
                    {
                      "type": {
                          "text": "Benefit Description (Incomplete information)"
                      }
                    },
                    {
                      "type": {
                          "text": "Benefit Disclaimer (Incomplete information)"
                      }
                    }
                  ]
                },
                {
                  "name": "Dental Care",
                  "network": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                          "code": "in",
                          "display": "In Network"
                        }
                      ],
                      "text": "In Network"
                  },
                  "unit": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                          "code": "individual",
                          "display": "Individual"
                        }
                      ],
                      "text": "Individual"
                  },
                  "benefit": [
                    {
                      "type": {
                          "text": "Active Coverage"
                      }
                    }
                  ]
                },
                {
                  "name": "Health Benefit Plan Coverage",
                  "network": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                          "code": "in",
                          "display": "In Network"
                        }
                      ],
                      "text": "In Network"
                  },
                  "unit": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                          "code": "individual",
                          "display": "Individual"
                        }
                      ],
                      "text": "Individual"
                  },
                  "benefit": [
                    {
                      "type": {
                          "text": "Deductible (Incomplete information)"
                      }
                    },
                    {
                      "type": {
                          "text": "Deductible"
                      },
                      "allowedMoney": {
                          "value": 6900
                      },
                      "usedMoney": {
                          "value": 0.0
                      }
                    },
                    {
                      "type": {
                          "text": "Active Coverage"
                      }
                    },
                    {
                      "type": {
                          "text": "Out of Pocket (Stop Loss)"
                      },
                      "allowedMoney": {
                          "value": 6900
                      },
                      "usedMoney": {
                          "value": 0.0
                      }
                    },
                    {
                      "type": {
                          "text": "Out of Pocket (Stop Loss)"
                      },
                      "allowedMoney": {
                          "value": 6900
                      },
                      "usedMoney": {
                          "value": 0.0
                      }
                    }
                  ]
                },
                {
                  "name": "Health Benefit Plan Coverage",
                  "network": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                          "code": "in",
                          "display": "In Network"
                        }
                      ],
                      "text": "In Network"
                  },
                  "benefit": [
                    {
                      "type": {
                          "text": "Benefit Description (Incomplete information)"
                      }
                    }
                  ]
                },
                {
                  "name": "Physician Visit - Well",
                  "network": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                          "code": "in",
                          "display": "In Network"
                        }
                      ],
                      "text": "In Network"
                  },
                  "benefit": [
                    {
                      "type": {
                          "text": "Non-Covered (Incomplete information)"
                      }
                    }
                  ]
                },
                {
                  "name": "Professional (Physician) Visit - Office",
                  "network": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                          "code": "in",
                          "display": "In Network"
                        }
                      ],
                      "text": "In Network"
                  },
                  "unit": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                          "code": "individual",
                          "display": "Individual"
                        }
                      ],
                      "text": "Individual"
                  },
                  "benefit": [
                    {
                      "type": {
                          "text": "Co-Payment"
                      },
                      "allowedMoney": {
                          "value": 0
                      },
                      "extension": [
                        {
                          "url": "http://schemas.canvasmedical.com/fhir/extensions/eligibility-benefit-message",
                          "valueString": "Primary Care Visit or Evaluation"
                        }
                      ]
                    },
                    {
                      "type": {
                          "text": "Co-Payment"
                      },
                      "allowedMoney": {
                          "value": 50
                      },
                      "extension": [
                        {
                          "url": "http://schemas.canvasmedical.com/fhir/extensions/eligibility-benefit-message",
                          "valueString": "GYN Visit"
                        },
                        {
                          "url": "http://schemas.canvasmedical.com/fhir/extensions/eligibility-benefit-message",
                          "valueString": "Specialist Visit or Evaluation"
                        }
                      ]
                    },
                    {
                      "type": {
                          "text": "Co-Insurance"
                      },
                      "allowedString": "0.0%"
                    }
                  ]
                },
                {
                  "name": "Professional (Physician) Visit - Office",
                  "network": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                          "code": "in",
                          "display": "In Network"
                        }
                      ],
                      "text": "In Network"
                  },
                  "benefit": [
                    {
                      "type": {
                          "text": "Non-Covered (Incomplete information)"
                      }
                    },
                    {
                      "type": {
                          "text": "Active Coverage"
                      }
                    }
                  ]
                }
              ]
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown CoverageEligibilityResponse resource 'c152eeb7-f204-4e28-acb5-c7e85390b17e'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/CoverageEligibilityResponse?request=CoverageEligibilityRequest/b41c7cda738d440cb55e0e6cb67499a1' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/CoverageEligibilityResponse?request=CoverageEligibilityRequest/b41c7cda738d440cb55e0e6cb67499a1"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Bundle",
          "type": "searchset",
          "total": 1,
          "entry": [
            {
              "resource": {
                "resourceType": "CoverageEligibilityResponse",
                "id": "9ad12f4e-4f35-4f54-8b4f-036516488191",
                "status": "active",
                "purpose": [
                    "benefits"
                ],
                "patient": {
                    "reference": "Patient/b41c7cda738d440cb55e0e6cb67499a1",
                    "type": "Patient"
                },
                "created": "2023-09-19T18:16:39.551617+00:00",
                "request": {
                    "reference": "CoverageEligibilityRequest/d7254641-e363-488c-91fa-b93a6170b9e0",
                    "type": "CoverageEligibilityRequest"
                },
                "outcome": "complete",
                "insurer": {
                    "identifier": "1111",
                    "display": "Payer ID: 1111"
                },
                "insurance": [
                  {
                    "extension": [
                      {
                        "url": "http://schemas.canvasmedical.com/fhir/extensions/active-health-benefit-plan-coverage-description",
                        "valueString": "Humana Gold Plus"
                      }
                    ],
                    "coverage": {
                        "reference": "Coverage/4a86f580-e192-489a-a9f0-7c915fc67111",
                        "type": "Coverage"
                    },
                    "item": [
                      {
                        "network": {
                          "coding": [
                            {
                              "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                              "code": "in",
                              "display": "In Network"
                            }
                          ],
                          "text": "In Network"
                        },
                        "unit": {
                          "coding": [
                            {
                              "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                              "code": "individual",
                              "display": "Individual"
                            }
                          ],
                          "text": "Individual"
                        },
                        "benefit": [
                          {
                            "type": {
                                "text": "Co-Payment"
                            },
                            "allowedMoney": {
                                "value": 333
                            }
                          },
                          {
                            "type": {
                                "text": "Co-Insurance"
                            },
                            "allowedString": "0.0%"
                          }
                        ]
                      },
                      {
                        "network": {
                          "coding": [
                            {
                              "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                              "code": "in",
                              "display": "In Network"
                            }
                          ],
                          "text": "In Network"
                        },
                        "unit": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                                "code": "individual",
                                "display": "Individual"
                              }
                            ],
                            "text": "Individual"
                        },
                          "benefit": [
                            {
                              "type": {
                                  "text": "Co-Insurance"
                              },
                              "allowedString": "0.0%"
                            },
                            {
                              "type": {
                                  "text": "Co-Insurance"
                              },
                              "allowedString": "0.0%"
                            },
                            {
                              "type": {
                                  "text": "Co-Insurance"
                              },
                              "allowedString": "0.0%"
                            }
                          ]
                      },
                      {
                        "benefit": [
                          {
                            "type": {
                                "text": "Benefit Description (Incomplete information)"
                            }
                          }
                        ]
                      },
                      {
                        "benefit": [
                          {
                            "type": {
                                "text": "Active Coverage"
                            }
                          }
                        ]
                      },
                      {
                        "network": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                                "code": "in",
                                "display": "In Network"
                              }
                            ],
                            "text": "In Network"
                        },
                        "benefit": [
                          {
                            "type": {
                                "text": "Active Coverage"
                            }
                          },
                          {
                            "type": {
                                "text": "Primary Care Provider (Incomplete information)"
                            }
                          },
                          {
                            "type": {
                                "text": "Benefit Description (Incomplete information)"
                            }
                          },
                          {
                            "type": {
                                "text": "Benefit Disclaimer (Incomplete information)"
                            }
                          }
                        ]
                      },
                      {
                        "name": "Dental Care",
                        "network": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                                "code": "in",
                                "display": "In Network"
                              }
                            ],
                            "text": "In Network"
                        },
                        "unit": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                                "code": "individual",
                                "display": "Individual"
                              }
                            ],
                            "text": "Individual"
                        },
                        "benefit": [
                          {
                            "type": {
                                "text": "Active Coverage"
                            }
                          }
                        ]
                      },
                      {
                        "name": "Health Benefit Plan Coverage",
                        "network": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                                "code": "in",
                                "display": "In Network"
                              }
                            ],
                            "text": "In Network"
                        },
                        "unit": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                                "code": "individual",
                                "display": "Individual"
                              }
                            ],
                            "text": "Individual"
                        },
                        "benefit": [
                          {
                            "type": {
                                "text": "Deductible (Incomplete information)"
                            }
                          },
                          {
                            "type": {
                                "text": "Deductible"
                            },
                            "allowedMoney": {
                                "value": 6900
                            },
                            "usedMoney": {
                                "value": 0.0
                            }
                          },
                          {
                            "type": {
                                "text": "Active Coverage"
                            }
                          },
                          {
                            "type": {
                                "text": "Out of Pocket (Stop Loss)"
                            },
                            "allowedMoney": {
                                "value": 6900
                            },
                            "usedMoney": {
                                "value": 0.0
                            }
                          },
                          {
                            "type": {
                                "text": "Out of Pocket (Stop Loss)"
                            },
                            "allowedMoney": {
                                "value": 6900
                            },
                            "usedMoney": {
                                "value": 0.0
                            }
                          }
                        ]
                      },
                      {
                        "name": "Health Benefit Plan Coverage",
                        "network": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                                "code": "in",
                                "display": "In Network"
                              }
                            ],
                            "text": "In Network"
                        },
                        "benefit": [
                          {
                            "type": {
                                "text": "Benefit Description (Incomplete information)"
                            }
                          }
                        ]
                      },
                      {
                        "name": "Physician Visit - Well",
                        "network": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                                "code": "in",
                                "display": "In Network"
                              }
                            ],
                            "text": "In Network"
                        },
                        "benefit": [
                          {
                            "type": {
                                "text": "Non-Covered (Incomplete information)"
                            }
                          }
                        ]
                      },
                      {
                        "name": "Professional (Physician) Visit - Office",
                        "network": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                                "code": "in",
                                "display": "In Network"
                              }
                            ],
                            "text": "In Network"
                        },
                        "unit": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-unit",
                                "code": "individual",
                                "display": "Individual"
                              }
                            ],
                            "text": "Individual"
                        },
                        "benefit": [
                          {
                            "type": {
                                "text": "Co-Payment"
                            },
                            "allowedMoney": {
                                "value": 0
                            },
                            "extension": [
                              {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/eligibility-benefit-message",
                                "valueString": "Primary Care Visit or Evaluation"
                              }
                            ]
                          },
                          {
                            "type": {
                                "text": "Co-Payment"
                            },
                            "allowedMoney": {
                                "value": 50
                            },
                            "extension": [
                              {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/eligibility-benefit-message",
                                "valueString": "GYN Visit"
                              },
                              {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/eligibility-benefit-message",
                                "valueString": "Specialist Visit or Evaluation"
                              }
                            ]
                          },
                          {
                            "type": {
                                "text": "Co-Insurance"
                            },
                            "allowedString": "0.0%"
                          }
                        ]
                      },
                      {
                        "name": "Professional (Physician) Visit - Office",
                        "network": {
                            "coding": [
                              {
                                "system": "http://terminology.hl7.org/CodeSystem/benefit-network",
                                "code": "in",
                                "display": "In Network"
                              }
                            ],
                            "text": "In Network"
                        },
                        "benefit": [
                          {
                            "type": {
                                "text": "Non-Covered (Incomplete information)"
                            }
                          },
                          {
                            "type": {
                                "text": "Active Coverage"
                            }
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "id": "101",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Customer Authentication

Source: https://docs.canvasmedical.com/api/customer-authentication/

##  Introduction 
  - Canvas is an OAuth 2.0 authorization server.
  - This page contains information about how you can create third-party applications within your Canvas EHR instance and use those applications to access the FHIR API.
  - Canvas supports most OAuth flows, but this document will focus on two of the most used:
    - **Client Credentials** : Mostly used for Machine-to-Machine authentication (e.g., CLIs, Daemons).
    - **Authorization Code** : Usually used for web/native applications since it requires a user to log in to the system.
##  Registering a third-party application on Canvas 
  - Registering a third-party application is always the first step.
  - To register, view, edit, or delete applications, you need the Administrative Developer or Clinical Developer role, or membership in a group with the **Can register and manage OAuth applications** permission. Canvas support sets up the group, and you add staff to it in **Staff Permissions**.
  - Any user can review and revoke the tokens they approved for an application at `{YOUR_CANVAS_EHR_INSTANCE}/auth/authorized_tokens/`.
  - In order to do so, you'll need to:
    1. Go to `{YOUR_CANVAS_EHR_INSTANCE}/auth/applications/` where you'll see the following page: ![Authorization Page](/assets/images/ed67823-Screenshot_2021-10-26_at_16.22.31.png)
    2. Once you click the link on that page, you'll see the following: ![Application Registration](/assets/images/8b49344-Screenshot_2021-10-26_at_16.24.01.png)
    - You'll need to set a name for the app, set the `Client type` to `Confidential`, choose one of the `Authorization grant types`, and set the `Redirect URIs` if needed. Leave the `Algorithm` at `No OIDC support` for now.
    - Here's how it should look if you created a new "Test Application" with the `client-credentials` grant type: ![Application Example](/assets/images/6190a01-Screenshot_2021-10-26_at_16.26.59.png)
    - That's it. Take note of your `Client ID` and `Client Secret`, and proceed to the section related to the `Authorization Grant Type` you chose.
##  Client Credentials 
  - The Client Credentials flow assumes that everyone involved is capable of securely storing the `Client ID` and `Client Secret`.
  - In order to get a token, you just need to:
    ```shell
    curl --request POST '{YOUR_CANVAS_EHR_INSTANCE}/auth/token/' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
    --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}'
    ```
and you'll get back a JSON which will contain an `access_token` that'll be valid for 10 hours.
The `/api` endpoints check no scopes, and a client credentials token acts there with every permission of the application's owner. For that reason, a client credentials token must carry the `system/*.*` scope to call `/api`. Canvas refuses a token with narrower scopes there with `403 Forbidden`. The [Note API](/api/note/), the [Letter API](/api/letter/), and the plugin endpoints check scopes, so they accept narrower tokens.
##  Authorization Code 
The Authorization Code flow ensures a user of the Canvas EHR explicitly approves the token request. It's typically used by web/mobile applications that act on behalf of a specific user (staff or patient).
The access token obtained through this flow carries the identity of the user who authorized it. This means:
  - **FHIR API calls** are scoped to that user's permissions.
  - **SimpleAPI plugin endpoints** receive the user as the [event actor](/sdk/events/#event-actor), allowing plugins to identify which user is making the request and enforce access controls.
###  Basic Steps 
  1. The application opens a browser to the Canvas authorization endpoint.
  2. The logged-in user sees the authorization prompt and approves the request.
  3. The user is redirected back to the `redirect_uri` with an authorization code in the query string.
  4. The application exchanges the authorization code for an access token and refresh token.
###  Step 1: Redirect the User to Authorize 
Open the following URL in the user's browser:
    ```text
    {YOUR_CANVAS_EHR_INSTANCE}/auth/authorize/?response_type=code&client_id={CLIENT_ID}&scope={SCOPES}&redirect_uri={REDIRECT_URI}&launch={LAUNCH_CONTEXT}
    ```
**Important notes:**
  - **`launch` parameter (required for staff users):** Staff users must include a `launch` parameter containing a base64-encoded JSON object with context. Without this parameter, the authorization will be denied with `error=access_denied`.
        ```bash
        # Encode a launch context with a patient id
        echo -n '{"patient":"PATIENT_KEY_HERE"}' | base64
        # Result: eyJwYXRpZW50IjoiUEFUSUVOVF9LRVlfSEVSRSJ9
        # Or with an empty patient (if no specific patient context is needed,
        # or the token must call staff APIs such as the Note API)
        echo -n '{"patient":""}' | base64
        # Result: eyJwYXRpZW50IjoiIn0=
        ```
  - **URL-encode special characters in scopes:** Scopes like `user/*.read` contain `/` which must be encoded as `%2F` in the URL. For example: `scope=user%2F*.read%20user%2F*.write`
  - **Authorization codes expire quickly:** The code returned in the redirect is valid for approximately 60 seconds. Exchange it for tokens immediately.
**Example authorize URL:**
    ```text
    {YOUR_CANVAS_EHR_INSTANCE}/auth/authorize/?response_type=code&client_id={CLIENT_ID}&scope=user%2F*.read%20user%2F*.write&redirect_uri=https://your-app.com/callback&launch=eyJwYXRpZW50IjoiIn0=
    ```
After the user clicks **Authorize** , they are redirected to your `redirect_uri` with a `code` parameter:
    ```text
    https://your-app.com/callback?code=AUTHORIZATION_CODE
    ```
###  Step 2: Exchange the Code for Tokens 
    ```shell
    curl --request POST '{YOUR_CANVAS_EHR_INSTANCE}/auth/token/' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=authorization_code' \
    --data-urlencode 'client_id={CLIENT_ID}' \
    --data-urlencode 'client_secret={CLIENT_SECRET}' \
    --data-urlencode 'redirect_uri={REDIRECT_URI}' \
    --data-urlencode 'code={CODE_FROM_PREVIOUS_STEP}'
    ```
**Response:**
    ```json
    {
      "access_token": "AN_ACCESS_TOKEN",
      "expires_in": 36000,
      "token_type": "Bearer",
      "scope": "user/*.read user/*.write",
      "refresh_token": "A_REFRESH_TOKEN",
      "patient": ""
    }
    ```
  - **`access_token`** : Valid for 10 hours (36000 seconds). Use this as a `Bearer` token in API requests.
  - **`refresh_token`** : Non-expiring but **single-use**. Each time you refresh, you receive a new refresh token — store it to maintain long-term access.
###  Step 3: Use the Token 
Use the access token as a Bearer token in the `Authorization` header:
    ```shell
    # FHIR API example
    curl --request GET '{FUMAGE_BASE_URL}/Patient' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}'
    # SimpleAPI plugin endpoint example
    curl --request GET '{YOUR_CANVAS_EHR_INSTANCE}/plugin-io/api/{plugin_name}/{endpoint}' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}'
    ```
When a SimpleAPI plugin receives a request with a Bearer token, Canvas validates the token, identifies the user, and sets them as the [event actor](/sdk/events/#event-actor). The plugin can then use `self.event.actor` to determine which user is making the request.
###  Step 4: Refresh the Token 
Access tokens expire after 10 hours. Use the refresh token to get a new access token without requiring the user to re-authorize:
    ```shell
    curl --request POST '{YOUR_CANVAS_EHR_INSTANCE}/auth/token/' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=refresh_token' \
    --data-urlencode 'client_id={CLIENT_ID}' \
    --data-urlencode 'client_secret={CLIENT_SECRET}' \
    --data-urlencode 'refresh_token={REFRESH_TOKEN}' \
    --data-urlencode 'scope={SCOPES}'
    ```
**Note:** The `scope` parameter must match the scopes from the original authorization (or be a subset). If omitted, Canvas will attempt to use the application's default allowed scopes, but this may fail with `invalid_scope` if the defaults don't match the original grant.
This returns a new `access_token` and a **new** `refresh_token`. The previous refresh token is consumed and cannot be reused. Store the new refresh token for the next refresh cycle.
###  Recommended Pattern for External Applications 
For applications that need to make API calls on behalf of specific Canvas users (e.g., a provider portal calling plugin endpoints):
  1. **One-time setup per user:** Each user authorizes the app via the browser flow. Store the refresh token per user in your backend.
  2. **Ongoing access:** Before making API calls, check if the access token is still valid. If expired, use the stored refresh token to get a new one.
  3. **Token storage:** Access tokens last 10 hours. Refresh tokens are non-expiring but single-use — always store the latest one returned from a refresh.
##  Patient Scoped Tokens 
Canvas supports patient scoped tokens. These are access tokens requested on behalf of a specific patient and have read/write access to that patient's records only.
To acquire a patient scoped token, you will need to include some parameters in the body of your token request:
  - A `client_id` and `client_secret` that your application will use to authenticate with Canvas.
  - The Canvas resource id for the `patient` the token will be scoped to
  - A `scope` parameter with space separated patient level scopes requested for the token.
    - Additional requested scopes should follow the pattern `patient/<ResourceName>.<read/write/*>`
      - `patient/Appointment.*`
      - `patient/Appointment.read patient/Appointment.write`
      - `patient/Patient.read`
      - `patient/Practitioner.read`
    - Canvas provides support for the wildcard character, but highly recommends only requesting the minimal scopes and access needed and using it as a convenience when both read and write are truly required for the application.
See Resources by context for the full list of resources a `patient/` scope can read and write.
###  Example curl request 
    ```bash
    curl --location --request POST \
          'https://<your_subdomain_here>.canvasmedical.com/auth/token/' \
          --header 'Content-Type: application/x-www-form-urlencoded' \
          --data-urlencode 'grant_type=client_credentials' \
          --data-urlencode 'client_id=<client_id_from_Canvas>' \
          --data-urlencode 'client_secret=<client_secret_from_Canvas>' \
          --data-urlencode 'patient=abc123' \
          --data-urlencode 'scope=patient/Patient.read patient/Appointment.* patient/Practitioner.read'
    ```
###  Expected Response Body 
    ```json
    {
      "access_token": "<the_access_token_to_use_in_your_request>",
      "expires_in": 36000,
      "token_type": "Bearer",
      "scope": "patient/Patient.read patient/Appointment.* patient/Practitioner.read",
      "smart_style_url": "https://canvas-storages.s3.us-west-2.amazonaws.com/fhir-static-resources/smart-style.json",
      "patient": "abc123",
      "need_patient_banner": true
    }
    ```
Using this access token in subsequent requests ensures that records referencing other patients cannot be retrieved through accidental or malicious misuse of the token. Canvas will also deny requests for any resource types which were not included in `scope` of the token request and requests for resource types which do not support patient-scoped tokens.
**Note:** A patient scoped token must include which patient scopes are being requested. Token requests that include the patient parameter but are missing scope or request invalid scopes will be rejected.
##  Tokens with a patient context 
A token carries a patient context in these cases:
  - It's a patient scoped token.
  - It comes from an authorization code flow whose `launch` context names a patient.
These tokens work with the FHIR API, but Canvas refuses them on staff APIs. Staff APIs include the `/api` endpoints, the [Note API](/api/note/), the [Letter API](/api/letter/), and the plugin install and management endpoints. Canvas also refuses tokens on staff APIs when the user they act as isn't a staff member, such as a patient.
A refused token gets `403 Forbidden` on `/api`. On the Note and Letter APIs and the plugin endpoints, it gets `401 Unauthorized`. To call these APIs, request a separate token. Use the client credentials flow, or the authorization code flow with a `launch` context that names no patient.
FHIR operations, such as [Create Lab Report](/api/diagnosticreport-operations/) and [Add Claim Activity Log Item](/api/claim-operations/), also need a token without a patient context, including when an app is launched from a patient's chart.
##  Scopes 
Scopes control which parts of the API the token can access.
  - **Client Credentials Flow:** Scopes are optional. If omitted, the token is issued with the OAuth application's configured allowed scopes.
  - **Authorization Code Flow:** Scopes are required and must be passed in the authorize URL.
Every scope you request must be one of the application's allowed scopes, whatever the grant type. Canvas rejects a request that includes any other scope with an `invalid_scope` error. To use a scope the application doesn't have, add it to the application's allowed scopes first.
A patient who signs in through the authorization code flow can approve only `patient/` resource scopes, plus the launch and OpenID scopes. If the request includes a `user/` or `system/` scope, Canvas denies it and redirects with `error=access_denied`.
Canvas implements [SMART on FHIR scopes](https://hl7.org/fhir/smart-app-launch/STU2/scopes-and-launch-context.html).
###  Scope syntax 
Most scopes have the form `<context>/<resource>.<permission>`:
  - **`<context>`** — `user/` (staff member; mirrors EHR permissions), `patient/` (limited to the launch-context patient), or `system/` (machine-to-machine, used with Client Credentials).
  - **`<resource>`** — a FHIR resource (e.g., `Patient`) or `*` for any supported resource.
  - **`<permission>`** — `read`, `write`, or `*` (v1 / legacy), or `c` (create), `r` (read), `u` (update), `s` (search) (v2 / granular). v2 letters can be combined, e.g., `Patient.crus`.
Separate multiple scopes with spaces, e.g., `user/Patient.read user/Observation.read`. URL-encode `/` as `%2F` and spaces as `%20`.
Common examples:
Scope| Description  
---|---  
`user/*.read`| Read access to all resources  
`user/*.write`| Write access to all resources  
`user/*.*`| Full access to all resources  
`user/Patient.read`| Read Patient resources only  
`system/*.read`| System-level read access to all resources (used for bulk-data export, e.g., `Group/{id}/$export`)  
###  Launch and OpenID scopes 
Scope| Description  
---|---  
`launch`| Allows external app launches  
`launch/patient`| Allows patient context  
`openid`| OpenID Connect scope  
`fhirUser`| Returns the authenticated user's FHIR identity  
`offline_access`| Requests a refresh token  
###  Resources by context 
Examples: `user/*.read`, `system/Patient.crus`, `patient/Appointment.write`.
**`user/`** — most clinical resources support `read`, `write`, `*`, and v2 `c r u s`. Read-only: `Coverage`, `MedicationDispense`, `Questionnaire`, `RelatedPerson`, `ServiceRequest`, `Specimen`. `Note` supports `read` and `write` only (no `*`). Resources: `*`, `AllergyIntolerance`, `CarePlan`, `CareTeam`, `Condition`, `Coverage`, `DetectedIssue`, `Device`, `DiagnosticReport`, `DocumentReference`, `Encounter`, `Goal`, `Immunization`, `Location`, `Medication`, `MedicationDispense`, `MedicationRequest`, `Note`, `Observation`, `Organization`, `Patient`, `Practitioner`, `PractitionerRole`, `Procedure`, `Provenance`, `Questionnaire`, `QuestionnaireResponse`, `RelatedPerson`, `ServiceRequest`, `Specimen`.
**`system/`** — same set as `user/` plus `Task` (full access). Read-only resources match `user/`. `system/Plugins.*` grants full access to plugin install/list/management endpoints. These endpoints accept only a client credentials token. Canvas refuses an authorization code token even when it carries `system/Plugins.*`.
**`patient/`** — restricted to the launch-context patient. Writable: `Appointment`, `Communication`, `Consent`, `Coverage`, `Media`, `MedicationStatement`, `Patient`, `PaymentNotice`, `QuestionnaireResponse`. All others read-only. Additional read-only resources beyond the user/system list: `Appointment`, `Communication`, `Consent`, `Media`, `MedicationStatement`, `PaymentNotice`, `Schedule`, `Slot`.
###  Operation scopes 
Some FHIR operations require a dedicated scope in addition to the resource scope. An operation scope covers only its operation: reading or writing the resource itself still needs a resource scope. Available under both `user/` and `system/`:
Scope suffix| Operation  
---|---  
`Claim.add-activity-log-item`| Add an activity log entry to a Claim  
`DiagnosticReport.create-lab-report`| Create a lab report  
`Practitioner.send-reset-password-email`| Send a password-reset email to a practitioner  
##  Additional reading 
  - [Authentication Best Practices](/api/authentication-best-practices)
  - [Event Actor](/sdk/events/#event-actor) — how plugins identify the authenticated user

---

# Date Filtering

Source: https://docs.canvasmedical.com/api/date-filtering/

A few of the API Search endpoints support date search parameters. You have the ability to filter a Resources query result by a specific date or a date range. For more details, see https://hl7.org/fhir/search.html#prefix
We support the following date search modifiers:
  - `ge`   
Greater than or equal to the date.  
Example: `"?date=ge2021-01-01"``
  - `gt` Strictly greater than the date.   
Example: `"?date=gt2021-01-01"`
  - `le` Less than or equal to the date.   
Example: `"?date=le2021-01-01"`
  - `lt` Strictly less than the date.   
Example: `"?date=lt2021-01-01"`
  - `eq` Strictly equal to the date.   
Example: `"?date=eq2021-01-01"`  
You can supply multiple date search parameters to search in a range. For example if we want to find all the records within 2024-04-11 and 2024-04-20, we can pass `?date=ge2024-04-11&date=le2024-04-20`
The API endpoints that support date search parameters include:
  - [Appointment](/api/appointment/) (/Appointment) - Filter by appointment date
  - [Claim](/api/claim/) (/Claim) - Filter by created date (the date of service of the claim's note)
  - [Consent](/api/consent/) (/Consent) - Filter by consent date
  - [DetectedIssue](/api/detectedissue/) (/DetectedIssue) - Filter by identified date
  - [DiagnosticReport](/api/diagnosticreport/) (/DiagnosticReport) - Filter by report date
  - [DocumentReference](/api/documentreference/) (/DocumentReference) - Filter by document date
  - [Encounter](/api/encounter/) (/Encounter) - Filter by encounter date/period
  - [Observation](/api/observation/) (/Observation) - Filter by observation date/time
  - [QuestionnaireResponse](/api/questionnaireresponse/) (/QuestionnaireResponse) - Filter by authored date
  - [ServiceRequest](/api/servicerequest/) (/ServiceRequest) - Filter by authored date
  - [Task](/api/task/) (/Task) - Filter by date

---

# detectedissue

Source: https://docs.canvasmedical.com/api/detectedissue/

### 
Indicates an actual or potential clinical issue with or between one or more active or proposed clinical actions for a patient; e.g. Drug-drug interaction, Ineffective treatment frequency, Procedure-condition conflict, etc.   
<https://www.hl7.org/fhir/R4/detectedissue.html>  
### Endpoints
post/DetectedIssue get/DetectedIssue/{id} put/DetectedIssue/{id} get/DetectedIssue
post
/DetectedIssue
#### DetectedIssue create
Create an **DetectedIssue**.
### Attributes
resourceType
string
The FHIR Resource name.
identifier
array[json]
External identifiers associated with this DetectedIssue.
The `identifier` field allows for one external identifier to be stored for each DetectedIssue. This identifier may help users identify the issue in their own systems, particularly if the DetectedIssue was added from an external system or source.
Click to view child attributes
system
string required
The namespace for the identifier value.
value
string required
The unique value for the identifier within the specified `system`.
status
enum required
The status of the DetectedIssue.
There is some extra validation when creating/updating depending on what is supplied in the `mitigation` attribute  
\- The status must be `registered` if no `mitigation` is supplied.   
\- If there is only one `mitigation` supplied and the action of that mitigation is `valid`, the status must be `preliminary`.   
\- If there is only one `mitigation` supplied and the action of that mitigation is `invalid`, the status must be `cancelled`.   
\- If there are more than one mitigation and the one with the latest date has an action of `deferred`, the status must be `amended`.  
\- If there are more than one mitigation and the one with the latest date has an action of `accepted` or `refuted`, the status must be `final`.  
\- If there are more than one mitigation and the one with the latest date has an action of `corrected`, the status must be `corrected`.
**Value Options Supported:**
  - registered
  - preliminary
  - final
  - amended
  - corrected
  - cancelled
  - entered-in-error
code
json required
Identifies the general type of issue identified.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - https://terminology.hl7.org/CodeSystem/v3-ActCode
code
string required
The code that identifies the general type of issue identified.
**Value Options Supported:**
  - CODINGGAP
severity
enum
Indicates the degree of importance associated with the identified issue based on the potential impact on the patient.
**Value Options Supported:**
  - high
  - moderate
  - low
patient
json required
The patient for the DetectedIssue record.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
identifiedDateTime
datetime required
The datetime when the detected issue was identified.
author
json required
Individual or device responsible for the issue being raised.
Click to view child attributes
reference
string required
The reference string of the author in the format of `"Practitioner/4d789a3d5e794c0eb159a126b48c8b9f"`.
type
string
Type the reference refers to (e.g. "Practitioner").
evidence
array[json] required
Supporting evidence or manifestations that provide the basis for identifying the detected issue.
There must be at least one evidence element with system "http://hl7.org/fhir/sid/icd-10-cm".
Click to view child attributes
code
array[json] required
A manifestation that led to the recording of this detected issue.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/icd-10-cm
code
string required
The code of the Evidence.
display
string required
The display name of the coding.
detail
string
A textual explanation of the detected issue.
reference
string
The literature, knowledge base, or similar reference that describes the propensity for the detected issue identified. This field requires a valid URL representing the reference.
mitigation
array[json]
Indicates an action that has been taken or is committed to reduce or eliminate the likelihood of the risk identified by the detected issue from manifesting.
Click to view child attributes
action
json required
The type of action that has been taken or is committed to reduce or eliminate the likelihood of the risk identified by the detected issue from manifesting.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action
code
enum required
Describes the action that was taken or the observation that was made that reduces/eliminates the risk associated with the identified issue.
If only one mitigation is supplied, the `action` must be either `valid` or `invalid`.   
If there are more than one mitigation, the one with the earliest date must be `valid`. The rest of the mitigations that are not the last date will need to have an action of `deferred`. While the final mitigation can have a status of `deferred`, `accepted`, `refuted` or `corrected`.
**Value Options Supported:**
  - valid
  - invalid
  - accepted
  - refuted
  - deferred
  - corrected
date
datetime required
The datetime when the mitigation action was taken or committed to be taken.
author
json required
Individual or device responsible for the mitigation action.
Click to view child attributes
reference
string required
The reference string of the author in the format of `"Practitioner/4d789a3d5e794c0eb159a126b48c8b9f"`.
type
string
Type the reference refers to (e.g. "Practitioner").
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/DetectedIssue/{id}
#### DetectedIssue read
Read an **DetectedIssue**.
### Path Parameters
id required
string
The unique identifier for the DetectedIssue   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The Canvas identifier of the DetectedIssue.
identifier
array[json]
External identifiers associated with this DetectedIssue.
Click to view child attributes
system
string
The namespace for the identifier value.
value
string
The unique value for the identifier within the specified `system`.
status
enum
The status of the DetectedIssue.
**Value Options Supported:**
  - registered
  - preliminary
  - final
  - amended
  - corrected
  - cancelled
  - entered-in-error
code
json
Identifies the general type of issue identified.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - https://terminology.hl7.org/CodeSystem/v3-ActCode
code
string
The code that identifies the general type of issue identified.
**Value Options Supported:**
  - CODINGGAP
display
string
The display name of the coding.
text
string
Plain text representation of the coding.
severity
enum
Indicates the degree of importance associated with the identified issue based on the potential impact on the patient.
**Value Options Supported:**
  - high
  - moderate
  - low
patient
json
The patient for the DetectedIssue record.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
identifiedDateTime
datetime
The datetime when the detected issue was identified.
author
json
Individual or device responsible for the issue being raised.
Click to view child attributes
reference
string
The reference string of the author in the format of `"Practitioner/4d789a3d5e794c0eb159a126b48c8b9f"`.
type
string
Type the reference refers to (e.g. "Practitioner").
evidence
array[json]
Supporting evidence or manifestations that provide the basis for identifying the detected issue.
Click to view child attributes
code
array[json]
A manifestation that led to the recording of this detected issue.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/icd-10-cm
code
string
The code of the Evidence.
display
string
The display name of the coding.
detail
string
A textual explanation of the detected issue.
reference
string
The literature, knowledge base, or similar reference that describes the propensity for the detected issue identified. This field requires a valid URL representing the reference.
mitigation
array[json]
Indicates an action that has been taken or is committed to reduce or eliminate the likelihood of the risk identified by the detected issue from manifesting.
Click to view child attributes
id
string
The Canvas identifier of the DetectedIssueMitigation.
action
json
The type of action that has been taken or is committed to reduce or eliminate the likelihood of the risk identified by the detected issue from manifesting.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action
code
enum
Describes the action that was taken or the observation that was made that reduces/eliminates the risk associated with the identified issue.
**Value Options Supported:**
  - valid
  - invalid
  - accepted
  - refuted
  - deferred
  - corrected
display
string
The display name of the coding
date
datetime
The datetime when the mitigation action was taken or committed to be taken.
author
json
Individual or device responsible for the mitigation action.
Click to view child attributes
reference
string
The reference string of the author in the format of `"Practitioner/4d789a3d5e794c0eb159a126b48c8b9f"`.
type
string
Type the reference refers to (e.g. "Practitioner").
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/DetectedIssue/{id}
#### DetectedIssue update
Update an **DetectedIssue**.
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The Canvas identifier of the DetectedIssue.
identifier
array[json]
External identifiers associated with this DetectedIssue.
The `identifier` field allows for one external identifier to be stored for each DetectedIssue. This identifier may help users identify the issue in their own systems, particularly if the DetectedIssue was added from an external system or source.
Click to view child attributes
system
string required
The namespace for the identifier value.
value
string required
The unique value for the identifier within the specified `system`.
status
enum required
The status of the DetectedIssue.
There is some extra validation when creating/updating depending on what is supplied in the `mitigation` attribute  
\- The status must be `registered` if no `mitigation` is supplied.   
\- If there is only one `mitigation` supplied and the action of that mitigation is `valid`, the status must be `preliminary`.   
\- If there is only one `mitigation` supplied and the action of that mitigation is `invalid`, the status must be `cancelled`.   
\- If there are more than one mitigation and the one with the latest date has an action of `deferred`, the status must be `amended`.  
\- If there are more than one mitigation and the one with the latest date has an action of `accepted` or `refuted`, the status must be `final`.  
\- If there are more than one mitigation and the one with the latest date has an action of `corrected`, the status must be `corrected`.
**Value Options Supported:**
  - registered
  - preliminary
  - final
  - amended
  - corrected
  - cancelled
  - entered-in-error
code
json required
Identifies the general type of issue identified.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - https://terminology.hl7.org/CodeSystem/v3-ActCode
code
string required
The code that identifies the general type of issue identified.
**Value Options Supported:**
  - CODINGGAP
severity
enum
Indicates the degree of importance associated with the identified issue based on the potential impact on the patient.
**Value Options Supported:**
  - high
  - moderate
  - low
patient
json required
The patient for the DetectedIssue record.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
identifiedDateTime
datetime required
The datetime when the detected issue was identified.
author
json required
Individual or device responsible for the issue being raised.
Click to view child attributes
reference
string required
The reference string of the author in the format of `"Practitioner/4d789a3d5e794c0eb159a126b48c8b9f"`.
type
string
Type the reference refers to (e.g. "Practitioner").
evidence
array[json] required
Supporting evidence or manifestations that provide the basis for identifying the detected issue.
When updating attributes, make sure to supply the `id` field for the evidences that already exist in Canvas so they are not duplicated or removed.   
There must be at least one evidence element with system "http://hl7.org/fhir/sid/icd-10-cm".
Click to view child attributes
code
array[json] required
A manifestation that led to the recording of this detected issue.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/icd-10-cm
code
string required
The code of the Evidence.
display
string required
The display name of the coding.
detail
string
A textual explanation of the detected issue.
reference
string
The literature, knowledge base, or similar reference that describes the propensity for the detected issue identified. This field requires a valid URL representing the reference.
mitigation
array[json]
When updating attributes, make sure to supply the `id` field for the mitigations that already exist in Canvas so they are not duplicated or removed.
Click to view child attributes
id
string
The Canvas identifier of the DetectedIssueMitigation.
action
json required
The type of action that has been taken or is committed to reduce or eliminate the likelihood of the risk identified by the detected issue from manifesting.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action
code
enum required
Describes the action that was taken or the observation that was made that reduces/eliminates the risk associated with the identified issue.
If only one mitigation is supplied, the `action` must be either `valid` or `invalid`.   
If there are more than one mitigation, the one with the earliest date must be `valid`. The rest of the mitigations that are not the last date will need to have an action of `deferred`. While the final mitigation can have a status of `deferred`, `accepted`, `refuted` or `corrected`.
**Value Options Supported:**
  - valid
  - invalid
  - accepted
  - refuted
  - deferred
  - corrected
date
datetime required
The datetime when the mitigation action was taken or committed to be taken.
author
json required
Individual or device responsible for the mitigation action.
Click to view child attributes
reference
string required
The reference string of the author in the format of `"Practitioner/4d789a3d5e794c0eb159a126b48c8b9f"`.
type
string
Type the reference refers to (e.g. "Practitioner").
### Responses
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/DetectedIssue
#### DetectedIssue search
Search an **DetectedIssue**.
### Query Parameters
****
_id
string
A Canvas-issued unique identifier for a specific DetectedIssue.
patient
string
The patient for the DetectedIssue record in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
status
string
The status of the DetectedIssue.
**Search Values Supported:**
  - registered
  - preliminary
  - final
  - amended
  - corrected
  - cancelled
  - entered-in-error
identified
date
Filter by identifiedDateTime. See [Date Filtering](/api/date-filtering) for more information.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The Canvas identifier of the DetectedIssue.
identifier
array[json]
External identifiers associated with this DetectedIssue.
Click to view child attributes
system
string
The namespace for the identifier value.
value
string
The unique value for the identifier within the specified `system`.
status
enum
The status of the DetectedIssue.
**Value Options Supported:**
  - registered
  - preliminary
  - final
  - amended
  - corrected
  - cancelled
  - entered-in-error
code
json
Identifies the general type of issue identified.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - https://terminology.hl7.org/CodeSystem/v3-ActCode
code
string
The code that identifies the general type of issue identified.
**Value Options Supported:**
  - CODINGGAP
display
string
The display name of the coding.
text
string
Plain text representation of the coding.
severity
enum
Indicates the degree of importance associated with the identified issue based on the potential impact on the patient.
**Value Options Supported:**
  - high
  - moderate
  - low
patient
json
The patient for the DetectedIssue record.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
identifiedDateTime
datetime
The datetime when the detected issue was identified.
author
json
Individual or device responsible for the issue being raised.
Click to view child attributes
reference
string
The reference string of the author in the format of `"Practitioner/4d789a3d5e794c0eb159a126b48c8b9f"`.
type
string
Type the reference refers to (e.g. "Practitioner").
evidence
array[json]
Supporting evidence or manifestations that provide the basis for identifying the detected issue.
Click to view child attributes
code
array[json]
A manifestation that led to the recording of this detected issue.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/icd-10-cm
code
string
The code of the Evidence.
display
string
The display name of the coding.
detail
string
A textual explanation of the detected issue.
reference
string
The literature, knowledge base, or similar reference that describes the propensity for the detected issue identified. This field requires a valid URL representing the reference.
mitigation
array[json]
Indicates an action that has been taken or is committed to reduce or eliminate the likelihood of the risk identified by the detected issue from manifesting.
Click to view child attributes
id
string
The Canvas identifier of the DetectedIssueMitigation.
action
json
The type of action that has been taken or is committed to reduce or eliminate the likelihood of the risk identified by the detected issue from manifesting.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action
code
enum
Describes the action that was taken or the observation that was made that reduces/eliminates the risk associated with the identified issue.
**Value Options Supported:**
  - valid
  - invalid
  - accepted
  - refuted
  - deferred
  - corrected
display
string
The display name of the coding
date
datetime
The datetime when the mitigation action was taken or committed to be taken.
author
json
Individual or device responsible for the mitigation action.
Click to view child attributes
reference
string
The reference string of the author in the format of `"Practitioner/4d789a3d5e794c0eb159a126b48c8b9f"`.
type
string
Type the reference refers to (e.g. "Practitioner").
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/DetectedIssue' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
          {
            "resourceType": "DetectedIssue",
            "identifier": [
                {
                    "system": "http://external.identifier.system/url",
                    "value": "080abebd"
                }
            ],
            "status": "preliminary",
            "code": {
                "coding": [
                    {
                        "system": "https://terminology.hl7.org/CodeSystem/v3-ActCode",
                        "code": "CODINGGAP"
                    }
                ]
            },
            "severity": "moderate",
            "patient": {
                "reference": "Patient/a39cafb9d1b445be95a2e2548e12a787",
                "type": "Patient"
            },
            "identifiedDateTime": "2024-08-10T14:23:08+00:00",
            "author": {
                "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                "type": "Practitioner"
            },
            "evidence": [
                {
                    "code": [
                        {
                            "coding": [
                                {
                                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                    "code": "I23.43",
                                    "display": "Code text explanation"
                                }
                            ]
                        }
                    ]
                }
            ],
            "detail": "Detail for detected issue",
            "reference": "https://example.com",
            "mitigation": [
                {
                    "action": {
                        "coding": [
                            {
                                "system": "https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action",
                                "code": "valid"
                            }
                        ]
                    },
                    "date": "2024-08-09T14:23:08+00:00",
                    "author": {
                        "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                        "type": "Practitioner"
                    }
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DetectedIssue"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json",
        }
        payload = {
            "resourceType": "DetectedIssue",
            "identifier": [
                {
                    "system": "http://external.identifier.system/url",
                    "value": "080abebd"
                }
            ],
            "status": "preliminary",
            "code": {
                "coding": [
                    {
                        "system": "https://terminology.hl7.org/CodeSystem/v3-ActCode",
                        "code": "CODINGGAP"
                    }
                ]
            },
            "severity": "moderate",
            "patient": {
                "reference": "Patient/a39cafb9d1b445be95a2e2548e12a787",
                "type": "Patient"
            },
            "identifiedDateTime": "2024-08-10T14:23:08+00:00",
            "author": {
                "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                "type": "Practitioner"
            },
            "evidence": [
                {
                    "code": [
                        {
                            "coding": [
                                {
                                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                    "code": "I23.43",
                                    "display": "Code text explanation"
                                }
                            ]
                        }
                    ]
                }
            ],
            "detail": "Detail for detected issue",
            "reference": "https://example.com",
            "mitigation": [
                {
                    "action": {
                        "coding": [
                            {
                                "system": "https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action",
                                "code": "valid"
                            }
                        ]
                    },
                    "date": "2024-08-09T14:23:08+00:00",
                    "author": {
                        "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                        "type": "Practitioner"
                    }
                }
            ]
        }
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/DetectedIssue/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DetectedIssue/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "DetectedIssue",
            "id": "d9aefede-da05-4bef-bbf9-63bcf83c806a",
            "identifier": [
                {
                    "system": "http://external.identifier.system/url",
                    "value": "080abebd"
                }
            ],
            "status": "preliminary",
            "code": {
                "coding": [
                    {
                        "system": "https://terminology.hl7.org/CodeSystem/v3-ActCode",
                        "code": "CODINGGAP",
                        "display": "Codinggap"
                    }
                ],
                "text": "Codinggap"
            },
            "severity": "moderate",
            "patient": {
                "reference": "Patient/a39cafb9d1b445be95a2e2548e12a787",
                "type": "Patient"
            },
            "identifiedDateTime": "2024-08-10T14:23:08+00:00",
            "author": {
                "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                "type": "Practitioner"
            },
            "evidence": [
                {
                    "code": [
                        {
                            "coding": [
                                {
                                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                    "code": "I23.43",
                                    "display": "Code text explanation"
                                }
                            ]
                        }
                    ]
                }
            ],
            "detail": "Detail for detected issue",
            "reference": "https://example.com",
            "mitigation": [
                {
                    "id": "9a1cfc8c-4ee9-4eb7-9658-a5b0f9576698",
                    "action": {
                        "coding": [
                            {
                                "system": "https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action",
                                "code": "valid"
                            }
                        ]
                    },
                    "date": "2024-08-09T14:23:08+00:00",
                    "author": {
                        "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                        "type": "Practitioner"
                    }
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown DetectedIssue resource 'd9aefede-da05-4bef-bbf9-63bcf83c806b'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/DetectedIssue/d9aefede-da05-4bef-bbf9-63bcf83c806a' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
          {
            "resourceType": "DetectedIssue",
            "id": "d9aefede-da05-4bef-bbf9-63bcf83c806a",
            "identifier": [
                {
                    "system": "http://external.identifier.system/url",
                    "value": "080abebd"
                }
            ],
            "status": "preliminary",
            "code": {
                "coding": [
                    {
                        "system": "https://terminology.hl7.org/CodeSystem/v3-ActCode",
                        "code": "CODINGGAP"
                    }
                ]
            },
            "severity": "moderate",
            "patient": {
                "reference": "Patient/a39cafb9d1b445be95a2e2548e12a787",
                "type": "Patient"
            },
            "identifiedDateTime": "2024-08-10T14:23:08+00:00",
            "author": {
                "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                "type": "Practitioner"
            },
            "evidence": [
                {
                    "code": [
                        {
                            "coding": [
                                {
                                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                    "code": "I23.43",
                                    "display": "Code text explanation"
                                }
                            ]
                        }
                    ]
                }
            ],
            "detail": "Detail for detected issue",
            "reference": "https://example.com",
            "mitigation": [
                {
                    "id": "9a1cfc8c-4ee9-4eb7-9658-a5b0f9576698",
                    "action": {
                        "coding": [
                            {
                                "system": "https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action",
                                "code": "valid"
                            }
                        ]
                    },
                    "date": "2024-08-09T14:23:08+00:00",
                    "author": {
                        "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                        "type": "Practitioner"
                    }
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DetectedIssue/d9aefede-da05-4bef-bbf9-63bcf83c806a"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json",
        }
        payload = {
            "resourceType": "DetectedIssue",
            "id": "d9aefede-da05-4bef-bbf9-63bcf83c806a",
            "identifier": [
                {
                    "system": "http://external.identifier.system/url",
                    "value": "080abebd"
                }
            ],
            "status": "preliminary",
            "code": {
                "coding": [
                    {
                        "system": "https://terminology.hl7.org/CodeSystem/v3-ActCode",
                        "code": "CODINGGAP"
                    }
                ]
            },
            "severity": "moderate",
            "patient": {
                "reference": "Patient/a39cafb9d1b445be95a2e2548e12a787",
                "type": "Patient"
            },
            "identifiedDateTime": "2024-08-10T14:23:08+00:00",
            "author": {
                "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                "type": "Practitioner"
            },
            "evidence": [
                {
                    "code": [
                        {
                            "coding": [
                                {
                                    "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                    "code": "I23.43",
                                    "display": "Code text explanation"
                                }
                            ]
                        }
                    ]
                }
            ],
            "detail": "Detail for detected issue",
            "reference": "https://example.com",
            "mitigation": [
                {
                    "id": "9a1cfc8c-4ee9-4eb7-9658-a5b0f9576698",
                    "action": {
                        "coding": [
                            {
                                "system": "https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action",
                                "code": "valid"
                            }
                        ]
                    },
                    "date": "2024-08-09T14:23:08+00:00",
                    "author": {
                        "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                        "type": "Practitioner"
                    }
                }
            ]
        }
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/DetectedIssue?patient=Patient/a39cafb9d1b445be95a2e2548e12a787' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DetectedIssue?patient=Patient/a39cafb9d1b445be95a2e2548e12a787"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
              {
                "relation": "self",
                "url": "/DetectedIssue?patient=Patient%2Fa39cafb9d1b445be95a2e2548e12a787&_count=10&_offset=0"
              },
              {
                "relation": "first",
                "url": "/DetectedIssue?patient=Patient%2Fa39cafb9d1b445be95a2e2548e12a787&_count=10&_offset=0"
              },
              {
                "relation": "last",
                "url": "/DetectedIssue?patient=Patient%2Fa39cafb9d1b445be95a2e2548e12a787&_count=10&_offset=0"
              }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "DetectedIssue",
                        "id": "d9aefede-da05-4bef-bbf9-63bcf83c806a",
                        "identifier": [
                            {
                                "system": "http://external.identifier.system/url",
                                "value": "080abebd"
                            }
                        ],
                        "status": "preliminary",
                        "code": {
                            "coding": [
                                {
                                    "system": "https://terminology.hl7.org/CodeSystem/v3-ActCode",
                                    "code": "CODINGGAP",
                                    "display": "Codinggap"
                                }
                            ],
                            "text": "Codinggap"
                        },
                        "patient": {
                            "reference": "Patient/a39cafb9d1b445be95a2e2548e12a787",
                            "type": "Patient"
                        },
                        "identifiedDateTime": "2024-08-10T14:23:08+00:00",
                        "author": {
                            "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                            "type": "Practitioner"
                        },
                        "evidence": [
                            {
                                "code": [
                                    {
                                        "coding": [
                                            {
                                                "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                                "code": "I23.43",
                                                "display": "Code text explanation"
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "detail": "Detail for detected issue",
                        "reference": "https://example.com",
                        "mitigation": [
                            {
                                "id": "9a1cfc8c-4ee9-4eb7-9658-a5b0f9576698",
                                "action": {
                                    "coding": [
                                        {
                                            "system": "https://schemas.canvasmedical.com/fhir/detectedissue-mitigation-action",
                                            "code": "valid"
                                        }
                                    ]
                                },
                                "date": "2024-08-09T14:23:08+00:00",
                                "author": {
                                    "reference": "Practitioner/4d789a3d5e794c0eb159a126b48c8b9f",
                                    "type": "Practitioner"
                                }
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Third-Party Developer Access

Source: https://docs.canvasmedical.com/api/developer-access/

Canvas Medical is certified to ONC's [§170.315(g)(10)](/product-updates/rwt/) _Standardized API for Patient and Population Services_. This page describes how a third-party developer requests access to the FHIR API, the verification we perform, and the timelines we commit to under [45 CFR 170.404](https://www.ecfr.gov/current/title-45/section-170.404).
##  Two kinds of access 
The API supports two distinct access models. The authorization gate is different for each, and it is important to know which one your application needs.
###  Patient-directed access 
An individual patient authorizes your application to access **their own** health information. The patient authenticates and grants consent through the [SMART on FHIR](/api/customer-authentication/#authorization-code) authorization-code flow, and the resulting token is scoped to that patient (`patient/` context). The patient's authorization is the only approval required — access does not depend on separate sign-off from the patient's practice.
###  Population and bulk access 
A practice or organization using Canvas as its EHR authorizes access to data across its patient population, typically through the client-credentials flow (`system/` context) and bulk export. This access is authorized by the practice or organization that holds the data.
##  One Canvas instance per customer 
Each Canvas customer runs its own isolated instance, with its own base URL and its own authorization server. There is no single shared endpoint that spans customers. For patient-directed access, as part of verification we register and enable your application on every Canvas instance that has a patient portal enabled. Two things follow:
  - **Discover instances from the published directory.** The [Service Base URLs](/api/service-base-urls/) directory lists each customer's FHIR base URL in a machine-readable FHIR R4 Bundle, so your application can present the right practice to a user and route requests to the correct instance.
  - **Patients authorize on their own practice's instance.** For patient-directed access, send the patient to the authorization endpoint of the instance where they are a patient. They sign in with that practice's patient portal credentials and consent, and the resulting token is scoped to that single patient. Access to a given practice requires that the practice has its patient portal enabled and that the individual has a login there.
##  Requesting access 
Third-party developers do not need to be an existing Canvas customer to request access. To begin:
  1. Contact us at [developer-access@canvasmedical.com](mailto:developer-access@canvasmedical.com) with your organization name, a description of your application, the access model you need (patient-directed or population/bulk), and a technical point of contact.
  2. We complete an authenticity-verification review. This process is objective and applied uniformly to all API users, and we complete it within **ten business days** of receiving your request.
  3. Once verification is complete, we register and enable your application for production use within **five business days**.
We do not condition access on fees or royalties for the rights the API Condition of Certification protects, non-compete or exclusive-dealing terms, unrelated licenses, transfer of your intellectual property, Canvas-specific testing or certification, or reciprocal access to your application's data.
##  What we verify 
Verification confirms the authenticity of your organization and your application. It is limited to identity and does not evaluate the merits of your product. We apply the same criteria to every API user. You provide:
  - **Organization identity** — your registered legal business name and a verifiable business identifier, such as control of your organization's domain, a state business registration, or a D-U-N-S number.
  - **A domain-verified contact** — a named representative reachable at an email address on your organization's domain who can act on the organization's behalf.
  - **Application details** — the application name, a description of its intended use, the access model (patient-directed or population/bulk), and the redirect URIs or registered endpoints it will use.
  - **Attestations** — that the application has a published privacy policy and terms, that it will access data only as authorized by the patient (patient-directed access) or the organization (population/bulk access), and that you will comply with applicable law.
  - **Agreement to our[Terms of Use](/api/terms-of-use/).**
##  Sandbox access 
We provision a sandbox so your team can build and test before production enablement. Request sandbox credentials as part of step 1 above. Sandbox base URLs follow the pattern `https://fumage-<sandbox-name>.canvasmedical.com`; see the [Quickstart](/api/quickstart/) for making your first request.
##  Registering your application 
Once you have access to an instance (sandbox or production), register your application and obtain OAuth credentials by following [Customer Authentication](/api/customer-authentication/). That page documents the client-credentials and authorization-code flows and the available SMART scopes.
##  Fees 
There is no fee to register, verify, or enable a third-party application for access to the API.
##  Service base URLs 
Canvas publishes service base URLs for its customers. See [Service Base URLs](/api/service-base-urls/).
##  Terms of Use 
Use of the API is governed by our [Terms of Use](/api/terms-of-use/).

---

# Device

Source: https://docs.canvasmedical.com/api/device/

### 
A type of a manufactured item that is used in the provision of healthcare without being substantially changed through that activity. The device may be a medical or non-medical device.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-implantable-device.html>  
For information about creating Device resources for a patient, see this [Zendesk article](https://canvas-medical.help.usepylon.com/articles/8311513697-implantable-devices). Devices are not currently used by the Canvas UI, but any devices that are created can be accessed with the Device read and search endpoints, In order to generate the type attribute, a device code must be created and linked to the device via the admin settings on Canvas.
### Endpoints
get/Device/{id} get/Device
get
/Device/{id}
#### Device read
### Path Parameters
id required
string
The unique identifier for the Device   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Device
udiCarrier
array[json]
Unique Device Identifier (UDI) Barcode string.
Click to view child attributes
deviceIdentifier
string
Mandatory fixed portion of UDI.
carrierHRF
string
UDI Human Readable Barcode String.
status
enum [ active | inactive ]
Status of the Device availability.
distinctIdentifier
string
The distinct identification string.
manufacturer
string
Name of device manufacturer.
manufactureDate
date
Date when the device was made.
expirationDate
date
Date of expiry of this device (if applicable).
lotNumber
string
Lot number of manufacture.
serialNumber
string
Serial number assigned by the manufacturer.
modelNumber
string
The model number for the device.
type
json
The kind or type of device.
Click to view child attributes
coding
A CodeableConcept combination of one or more coding elements.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the category.
display
string
The display name of the coding.
patient
json
Patient to whom Device is affixed
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Device
#### Device search
### Query Parameters
****
_id
string
The identifier of the Device.
patient
string
The patient reference associated to the Device in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Device
udiCarrier
array[json]
Unique Device Identifier (UDI) Barcode string.
Click to view child attributes
deviceIdentifier
string
Mandatory fixed portion of UDI.
carrierHRF
string
UDI Human Readable Barcode String.
status
enum [ active | inactive ]
Status of the Device availability.
distinctIdentifier
string
The distinct identification string.
manufacturer
string
Name of device manufacturer.
manufactureDate
date
Date when the device was made.
expirationDate
date
Date of expiry of this device (if applicable).
lotNumber
string
Lot number of manufacture.
serialNumber
string
Serial number assigned by the manufacturer.
modelNumber
string
The model number for the device.
type
json
The kind or type of device.
Click to view child attributes
coding
A CodeableConcept combination of one or more coding elements.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the category.
display
string
The display name of the coding.
patient
json
Patient to whom Device is affixed
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Device/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Device/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Device",
            "id": "c6bf6efc-1fe1-4221-9821-e60acb53becc",
            "udiCarrier":
            [
                {
                    "deviceIdentifier": "08717648200274",
                    "carrierHRF": "=/08717648200274=,000025=A99971312345600=>014032=}013032&,1000000000000XYZ123"
                }
            ],
            "status": "active",
            "distinctIdentifier": "A99971312345600",
            "manufacturer": "ACME Biomedical",
            "manufactureDate": "2021-02-15",
            "expirationDate": "2021-09-15",
            "lotNumber": "234234",
            "serialNumber": "13213123123123",
            "modelNumber": "1.0",
            "type":
            {
                "coding":
                [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "2478003",
                        "display": "Ocular prosthesis"
                    }
                ]
            },
            "patient":
            {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                "type": "Patient"
            }
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Device resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Device?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Device?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Device/?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Device/?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Device/?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Device",
                        "id": "c6bf6efc-1fe1-4221-9821-e60acb53becc",
                        "udiCarrier": [
                            {
                                "deviceIdentifier": "08717648200274",
                                "carrierHRF": "=/08717648200274=,000025=A99971312345600=>014032=}013032&,1000000000000XYZ123"
                            }
                        ],
                        "status": "active",
                        "distinctIdentifier": "A99971312345600",
                        "manufacturer": "ACME Biomedical",
                        "manufactureDate": "2021-02-15",
                        "expirationDate": "2021-09-15",
                        "lotNumber": "234234",
                        "serialNumber": "13213123123123",
                        "modelNumber": "1.0",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "2478003",
                                    "display": "Ocular prosthesis"
                                }
                            ]
                        },
                        "patient": {
                            "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                            "type": "Patient"
                        }
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# DiagnosticReport Operations

Source: https://docs.canvasmedical.com/api/diagnosticreport-operations/

##  create-lab-report 
Creates a lab report, lab tests, lab values, and a stored PDF in Canvas.
This endpoint is a [FHIR operation](https://hl7.org/fhir/R4/operations.html) and was developed as a convenience method in order to post all data associated with a lab report in a single request. In order to adhere to the FHIR standard, the request structure for creating lab reports is in the [Parameters](https://hl7.org/fhir/R4/parameters.html) format. This means that an array of named parameter resources makes up the body of the request.
In the example below, the first object in the parameter array is a named parameter called `labReport`. This references a `DiagnosticReport` resource. The `subject` attribute passed here must contain a valid patient reference and the `presentedForm` attribute must contain a base64-encoded string of the report PDF. Only one `labReport` parameter is allowed per payload.
The subsequent parameters in the array must be named `labTestCollection`. These represent the lab tests performed and associated result values. Each `labTestCollection` has a `part` array with `labTest` and `labValue` parameters. Only one `labTest` parameter is allowed per `labTestCollection`. Multiple `labValue` parameters are allowed per `labTestCollection`. Both resources must be represented as `Observation` resources.
To mark a lab value as abnormal, an optional `interpretation` attribute can be added to a `labValue` `Observation` resource. **Only abnormal interpretations (`"code": "A"`)** are currently supported, and the `interpretation` payload must match the exact structure shown in the example below (`text`, `coding[0].system`, `coding[0].code`, and `coding[0].display` are all required and must match).
For the values/units in each `labValue` object, a `valueQuantity`, `valueString`, or `valueCodeableConcept` can be supplied in the payload. For example:
    ```json
    {
      "valueQuantity": {
        "value": 0.7,
        "unit": "mg/dL",
        "system": "http://unitsofmeasure.org"
      }
    }
    ```
or
    ```json
    {
      "valueString": "Normal"
    }
    ```
or
    ```json
    {
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "http://snomed.info/sct",
            "code": "260385009",
            "display": "Negative"
          }
        ]
      }
    }
    ```
If using `valueQuantity` and a comparator value is needed (i.e. `<1.0`), the comparator value can be passed in a `comparator` key like so:
    ```json
    {
      "valueQuantity": {
        "value": 1.0,
        "unit": "mg/dL",
        "system": "http://unitsofmeasure.org",
        "comparator": "<"
      }
    }
    ```
Supported `comparator` values are `<`, `<=`, `>=`, and `>`.
A `referenceRange` array may also be supplied on each `labValue` `Observation`. Only `referenceRange[0].text` is persisted in Canvas; `low` and `high` are accepted by the API but are not stored.
###  Validation requirements 
The following constraints are enforced when creating a lab report:
  - `labReport.presentedForm` must contain exactly one entry.
  - `labReport.presentedForm[0].contentType` must be `application/pdf`.
  - `labReport.presentedForm[0].data` is required and must contain a base64-encoded PDF.
  - `labReport.effectiveDateTime` must be a full ISO 8601 datetime (a date alone is not accepted).
  - Each `labTest` and `labValue` `Observation.code.coding` must contain exactly one entry, the `system` must be `http://loinc.org`, and `code` is required.
> **Warning:** While lab tests can be posted and are visible in the Canvas UI, they are not currently available to be read through the FHIR API. Only lab values can be read through the Observation resource.
The bearer token included in requests send to this endpoint must have one of the following scopes:
  - `system/DiagnosticReport.create-lab-report`
  - `user/DiagnosticReport.create-lab-report`
  - **curl**
        ```shell
        curl -X POST "https://fumage-example.canvasmedical.com/DiagnosticReport/\$create-lab-report" \
             -H "accept: application/json" \
             -H "Authorization: Bearer <token>" \
             -H "content-type: application/json" \
             -d '{
            "resourceType": "Parameters",
            "parameter":
            [
                {
                    "name": "labReport",
                    "resource":
                    {
                        "resourceType": "DiagnosticReport",
                        "status": "final",
                        "category":
                        [
                            {
                                "coding":
                                [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v2-0074",
                                        "code": "LAB",
                                        "display": "Laboratory"
                                    }
                                ]
                            }
                        ],
                        "subject":
                        {
                            "reference": "Patient/4cc6fd69f81042a0b6d123e2080a7c1a",
                            "type": "Patient"
                        },
                        "presentedForm":
                        [
                            {
                                "data": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoVW50aXRsZWQgZG9jdW1lbnQpCi9Qcm9kdWNlciAoU2tpYS9QREYgbTEwNCBHb29nbGUgRG9jcyBSZW5kZXJlcik+PgplbmRvYmoKMyAwIG9iago8PC9jYSAxCi9CTSAvTm9ybWFsPj4KZW5kb2JqCjUgMCBvYmoKPDwvRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDE4Mj4+IHN0cmVhbQp4nHWQ0QrCMAxF3/MV+QG7pmmaFsQHQfes9A/UDYQ9OP8fbDfdQFhTmnIP9zaU0JbaUTk0ObwN8AKjMqm/XkTCWtcW58vYQ9My9m+oPFJAshJwfEAHl78EdXWXjK/jmKE5eyRvQl2KuQNapzBeUyTlhHmAqrFxquw5Yr7j3lrWA+YnqGEXUhAunhn4OIFoSIisxgVIWByRnKz6nOSNVUoqugDLG0B44wmvWyBN4JTLv3wAWrRKswplbmRzdHJlYW0KZW5kb2JqCjIgMCBvYmoKPDwvVHlwZSAvUGFnZQovUmVzb3VyY2VzIDw8L1Byb2NTZXQgWy9QREYgL1RleHQgL0ltYWdlQiAvSW1hZ2VDIC9JbWFnZUldCi9FeHRHU3RhdGUgPDwvRzMgMyAwIFI+PgovRm9udCA8PC9GNCA0IDAgUj4+Pj4KL01lZGlhQm94IFswIDAgNjEyIDc5Ml0KL0NvbnRlbnRzIDUgMCBSCi9TdHJ1Y3RQYXJlbnRzIDAKL1BhcmVudCA2IDAgUj4+CmVuZG9iago2IDAgb2JqCjw8L1R5cGUgL1BhZ2VzCi9Db3VudCAxCi9LaWRzIFsyIDAgUl0+PgplbmRvYmoKNyAwIG9iago8PC9UeXBlIC9DYXRhbG9nCi9QYWdlcyA2IDAgUj4+CmVuZG9iago4IDAgb2JqCjw8L0xlbmd0aDEgMTg0MjgKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCA5MTQxPj4gc3RyZWFtCnic7XoJeFRF1vapureXdLqT29k76aRv0kkD6bAlYY+kQxbAiOyYYJAEiIRFWQIIihLGPaIwqKjoCO64dxLEgDowbqO4gIo6boCIiuMgyCgqSu7/VnWHBHC+n/H/vu9/fJ65N+etU1Xnnqp7zqlT1d0hRkSxAJV6DS0pLWOFLI+I7UVr/tBRI8deMWV9IpFiRf2uoWPHD7H92bIC/UHUe40c2zN3ccLTLiK+AfXqCSUjKkatnvk9Ud86IuctUy+qmctXsLvRfw76q6YuWqDf437/ayLzL6BxF86dftHrSyrXEjlGoX7x9Jr6uZREEdBfAHlt+uwlF046+GkrUdeuRFGD66ZdtPiF63+4ARPeRmTdUFdbM21v3MvQx+NIDIqGmLyIdDyPOVJm3UULFmd8yf9MZLoLbdWz50ytydqe/hbe5370N19Us3iuqcXRgD4xP/3imotqE6t7fwJjVKCtZO6c+gVGNq0BP1v0z51fOzfrvRFbidx4v0joJYWsxMlJzDDAC1tW0BEqoD+RBe0a9aQJ0PYYZE2oKyQvo4vQ+SsXnrcMbjuXijU69uSxSzXZctJVIVts1AO3qWZ+zRTSpy6ZP5v06fNrZ5FeVztlPumzaxZcTHqHTrKHeU7mcJsiZ9sPN6OhNBw4FjfDbM8DimdMrrWPttz61uTogu+tKVb52L2fdckW5WujBm069uTx6RpZheaITrPk0iZEcWFrxCGuhqGMknYyY1bj6EKaSwtoPSxGsj4N9XpRNz47cU897c0V5Tq2Cla0mtaaRISmhErlLbqQx1hNPNKscnGp4RmcuEaMPHckBTDSetM7baNZnmUwaw4Ih2F81Wd6Rs5CDdt1CFWRIi2aE7KotKV4C+E3A1K8E8868Rh1Vu18yHbGsP2FHIcFmCSNQnPsgXGTw77oJ30w3PhI1IDDjFSaAIKPUPvfvpb/1zdbxW9VRpx+q8PFbZ5p8UgtFpoookDFeqaZ1BDmGay8KMxzxEVdmFfgo65hXu0kY4KNosK8GRxREc2nGVRDs2kEomcC1aJej5Y5JKK+D+zam3qhf4RsmYNYW4IIq0XfcLoI7dMhezFQp+6gDm06jYHUdFoIvgatJ9c65B6GZC5G6I1bxG+d1H36aMWozQcvsAbtoRn2kGPODo83AyPUoa8+PHq9fJtFwGnUw9x5YQ34X4+C/9FL/QwW/H95vp7KQOWwS+wZyl97gicqxHOZpi3kAiWbHiKX6sPOQ8aXoAOibJthHBD9ouR/x0OtYSLaQI+zGfQ4baXn2WE89SRtpo30CiVSCd1FS+kWjGRG7L9C18OnYxDBJXQLcxkbsRvcg0i+h96A7Hl0BW2hBJZkfEXL6GrlHTx1NTkoA9ExCpFyIzvHWIhstEe9EtnhHETOXNZgVBg3GauN++kB2qy8YhynSKyOqbjfML4x/c34GBFdRbfSHbSHrY54CivqPKy7zcqfEFNrlUkqM6YbxzCDdLoEc1ARs2+wbdwP7bX0JUtiS5ViaLnPCBovQspNkxCba2kL68OG8nRTlTHCeIMSMMZiaL2DmmkT7lZ6jj5kdtNh437jMLkoB6tsGezxJtumtB1f3lYIi5lgpW40AD1z6M/0V9rJvOwvfI7Jbso1BUyXGruQKXvTeMz2ITz5BfuBX4F7mfKyWmYMwZq/mv4orE0v0acsmfVkI9kE3o3P4Xcr85FRc+RKnIa1dD3dDu27mZ9t4na+Q7lPfVT92ZzatteIgkd8dCf25b8wB95UZ/XsD+w99hkv5pP5nXyfcov6sPq2pQZvfQGyxI30KP3AYlh/Npqdz+rYUnYt+yO7g73BdrIDvIiP47P4IaVOmac8pw7BPVatV680XWO6wXygraLtxba32n4wco1raDTiYTlmfyvdjTfbTDvoA9x7aB8zsUgWhVtn6Ww8uwz3FexGdi/bwB5mGzHKTraPfcWOsO/ZzxyJkpt5Ck/nGbi9fD6/hN/C7+I7cO/k/+A/KYlKhuJX+igFSqUyB7O6VlmF+ynlUzVZ3aEasHOuaY1pnWmD6VHT86bDZrvlD1ayvv7Lfcezj+9uo7br2ta0NbdtND6lePgwGVbw4BQzGnmrBrl7Mc4rDyDO32F22C6ZZbPB7BxYZjKbyeaxxbDkVWwte0DO/Qn2LKz0PjuEOTu4W865B+/Dh/CRuC/gtXweX8VX8438PX5MsSiRSrQSr2QrQ5VJSq2yQFmirFGCyuvKJ8o+5ajyC25DtakeNUP1qX51qDpZXajerX6pfmmqMr1m+txsM19kvsbcav7W0tcy2DLKMtoyybLSssmyy1qN6HyBnqKnO+cBtldZrpQqT9FNPE918Tf5m4jnyTRNGcELxTmWXccvZxt5pmmxeRAfxM6lw6oPtn6Zr+NH+SBlBCtnY2km7x3SZo5TH0FRoL5AB9Vn8W5vQvNis51dwQ+Z7dTMZN5mLym9VL/yGn2o7GEW9R76SLWxRHaQP6SMQhQ8pw42VVC6chc9ocxjl9NTvBRHkZ+tKxDH57JHkBfGsVz2o4ITJj8XUdRP+YyupFn8b3QQ6/g6uo1NU6fTTZTHltKX9CBWRTfTxeZsczx7lc9QG3ks20hcfVjsISyTKaY4uopNUtaaD/EPsLvtUG20W3kMs9/Bn8Aeftg0htVhBVxO19A8YzktMVWob7PppLAJlKXuRXZbquSq6SiXIatUIadtwuregjxQpIxASxIi5xzExXhkiLW4b0eeUBFBM7DGz0MWe5M2msfxVppuimLIOsjGr7WNoYnGg3SHMZ0uNlZTd+SDa42l0LiBPqeVtIFd3XYZ9tE0rJzd7BxTGd9hKjO680b+AR/L15zsX1g7iyXR33E/gcpgnO8a1fdxti00VhjvIrq7IsPeQVPobNqPt/wGIwxTtlFe27m8yShT5uJ999Bo4yHDw2xUZ8ymkfQsPWAxUY3FDx8H2dt438uolo8xFii1bTNgh5WwQgDWWoj8c32gePy4okDh4LMKBg0c0L9fn/y83N69evbonuPP7ta1iy8r05uRrnvSUt0pya6kxIT4uNgYpxYd5bBH2iKsFrNJVTijnFJvWbUe9FUHVZ932LDuou6tQUNNp4bqoI6mspNlgnq1FNNPlgxA8sJTJAMhycAJSabpBVTQPUcv9erBN0q8eiubOLoC/I0l3ko9eFDyIyS/SvIO8OnpeEAvTaor0YOsWi8Nli2qayytLoG6pkhbsbe41tY9h5pskWAjwQUTvXObWOJgJhmeWDqwCSdjByYVTPaWlAZd3hIxg6CSVVozLThqdEVpSUp6emX3nCArnuqdEiTvkGC0X4pQsRwmaC4OWuQw+gzxNnSD3pSzrXFFq0ZTqv32ad5pNVUVQaWmUozh9GPckmDipfuTOqpQHlNccW3n3hSlsTRphi6qjY3X6sH1oys696YLrKyEDjzLs8qqG8sw9AoYsXysjtH41ZUVQXY1htTFm4i3Cr1frbdUtFTP1IMR3iHeusaZ1XBNcmOQxixJb05ODmw29lJyqd44rsKbHixM8VbWlLib4qhxzJIWV0B3ndzTPadJc4YM2xQVHWbsjs5M7Yk+yUlxwZWPOWFZJmbkHY6ACOpTdcykwot36i+gtj81Tu0PMVyVDE8Fp8EjM4IRxdWN2kDRLp4PmrI0r974PSECvAf/cXJLTbjFnKV9T4IVcXIi1NDfzgf9/mB2tggRSzF8ijkOlvU+3XMWtXKvd66mo4D5aBRsW1M5sCfMn54uHHxDa4CmoBJsGF0Rqus0JaWZAj39lUFeLXq2tffEjxc9De09Jx6v9iKSN8oTd3zQ6jvxF60lxJbWDQyyhP+iuzbUXz7WWz56YoVe2lgdtm35uJNqof7+J/rCXDC2uEJJ4WGOpyiyF0FZdUJYVCrsQTULf2YZ1NNaLVZEpWxhellQqx4WwkpbevoZPtRqHBZPyaLjsfA0gwP9J9cHnVQ/aXr2RgUTxlZZPm5iY6PtpD6EWmjA4eECEU/jKtL14iCNx8rMwl+rsa2/oMqUYAAmKxYCiL9QU7h6kmBKmK/EJaKze04ZEl1jY5lXL2usbqxpNRqmeHXN27iZP8+fb5xbWt0eOK3GlhtSgmUrKmGrOjYQi4LTkCYvu250U4BdN3ZixWaNSL9uXEUzZ7y4ekhlUyb6KjbrRAHZykWraBQVXVSonOElm7lVyqdsDhA1yF5VNsj61FZGss3a3sZoaisPtWntbRxtaqgtINvEJXJM8biKztEjl2Rld7nh4XMLVUVarad873GGl/nUulnt3GeGTntExG/TbTm1blE694maw2YjUunfv/5vuqEzOjLyt+mOOKVutXZogZlFTbPb/3t0R0SonfuEbqfDIT4z/XfoNnXuE7pjo6J+m277KfXIyI7IgZlt0BmvaafH02/SbT9JtxgpKSbmdJ+fyRV1at1h6dxnRy0lLk769d++tFPq0dEduqOhHjpTExJ+m+5Tv9XQtA4tGDcaNT0p6XSf/xbdTqetg4d66Ex3uX6b7vhT6jGddMOFTujMcrvFd63//pV46lhxHVowbgxq2bp+ejydyZV86liJjs7jxkFnD68XCes36HafOlZyR1RiXDFSrs93eqyeyeU5dSx3hxaM60Ktb7duMh7/7Sv9lHpaWoeWNKwb1Abm5Jy+Ds7kyjylrusdWnSsG9SKc3NPj9UzubqdUs/K6tCSRZSBWnn//qfH6plc3U+pZ2d3aMkm8qE2dvDg02P1TK78U+o9eiR18FAPnVWlpafH6plcp35/nJeX0sFDPXROKy8/PVbP5Bp8Sr1//9QOHrENnZtpnNK1xZfk2fms0o32grjSrdmf6tmsdFFSmwd5Aq2KtyUmPje6qLui42zUU6IOnAN6ErRVEb/TTFbSxG8owGWgBtCToK2gnSDsFEDRq4PmgNaB9ooeJVVxN+seraiL4sKzLpy1opVEOgQyQAp5gD1BI0GTQStB60BmKSda5oCWgbaCDsuegJLYvDoPc09svkEWLTNn58pqTahaNUlWW86rDJUjRofKkuEhsYEhsd75oeYeQ0Jll5xQGZOV2yBKmyN3W1GCkoCXTMDE5wIZf5GiGUMCWK/EUxDEFXO4JaDEtGT6ctdtVVRiClcYTSOPsU1hzQ5nbpGNG/wQkrGHf8MPhnr4wZYoZ+66orP5PnoStBWk8H24P+Wf0jK+V9gcWAhaB9oK2gE6BDLzvbj34N7Nd1M0/4R6ggpBk0HrQFtBh0AW/glQ4x+Lz1ESBV8I4vxjoMY/wmt9BIzmH4L7kH+Iqb3T3G9A7mbJ+HuGGU9WmElMCTMxCbmt/O3mn7ohonzwNCLqGSUDoZmnZDRn9fa0KknNBTM8rfyzFt3vWV/Ui++iIIhjJrsw8i7SQaNA1aC5IDO498C9Rw2gVaD1oCAIUQbUQDrfDnod9B71AgVAo0BWvrMZw7TyHc2+IZ6iBP4m/ytSgoe/wV+R5ev8ZVm+xl+S5aso01Bu5y83p3moKBL9hGc0lBrKnug38b+0ZMZ4jCIn3wrbeYA9QYWgkaDJoJUgM9/KM5qneWKg5BnajoOChzfTV7J8kO61UmCmJ+ArRgDqAnwDzwIHWKev8/GAb80dqArw3bQanADfVSvACfBduhycAN/sReAE+KbNBCfAN3EyOAG+kePAAVr53U9ndvH0GzmL6UXR/BJY6RJY6RJY6RJS+SXipp9UMbc7m7OzYbG1AX+3bE/DFtbwLGsYwxruZQ21rOEK1rCcNRSwhgtYg581uFlDGmsIsIZnWH+YooEFNp5UHRBIYg3bWcPjrKGeNfhYQxZryGQNOusXaOXpzcPzZFEqi5YisehQnjUY2Seap8Oi6Yj5dOSErcAdIEPWAhDSM0LCrjRRZrRkF4bqPQbmzikaxl/Agy/ADS/QHpAKB72AMHoBSl6AgmhgIWgyaBvoEMgAmSGdgYmvlBgN7AkqBE0GLQMdApnldA6BOM0JT/FJObGe4UmPFDX+Am7xQ0E6Tw+kam7Nrw1TVrpZdBobmWak8X4kzqQ4mFmdrcyx6QfHjz84KKIogt/EV1IqHLEqXK5s/inV08pub/Y94ymKZ7dRmoqoYwPIx7JQ9qd6We9Dbqso88nNH0WZ2+yegMeim305ni0sSjy1yfOTe7/nK3crB3vA/Yznfb1VZc2ed9Hy6CbPLvf1nld7tlrR8qyvlaHYokvRze7+nse3S9Hl6Fjb7LlCFJs8l7uHema5ZUdtqOOCetQC0Z4xvomeYdBX4p7iCdRD5yZPofsCT0FIqo94ZpOnF6bgD7HZmGw3txzUmyYVju/XyuoCOZY1lgrLSEtfS64lx5Ju8VhSLSmWOGuMVbNGWe1Wm9VqNVtVK7eSNa7V2Bvwi9/548zynzbEZ2hGquQ1TvLfBuS/AnBm5XQ2BWOVcl4+dggrD26bSuVT9ODRsd5WZhs9MWjyDmHBmHIqHzck2N9f3moxxgT7+cuDllHnVzQxdlMlWoP8ulZG4ypamSGark4R319uJsacV9+YIsquV99YWUlJCYsKkwpjBjsHlJX8ClSH0d9xJZ3EpwbXlI+tCD6SWhnMFYyRWlkevFl8wbmZHWGHS0s2s29FUVmxWRnMjpSOEe3K4JLKyvJWNkHKkc6+hRwi5lspZ8XGLORIt6aF5NaG5LLwPOQyRQG5iAjKknJZERFSTmVCrqk+s7SkKTNTyiTqVC9l6hP1zjLbsyCTlSVlEhpou5TZntAgZIKDpYjbDZE0txRhyeSWIm6WLEUmdIj0DItcf0LkejmSwjpk3CEZx952GcdeyPjP9Kod4vezlkGVU6vEl8PV3tJaUHXwhkV1ScGGKbreNLUy/K2xr3rK1DpR1tQGK721JcGp3hK9aVDVr3RXie5B3pImnBfHVTRVBWpLmgcFBpV6a0oqW4aOyu930ljXnxgrf9SvKBsllOWLsYb2+5XufqJ7qBirnxirnxhraGCoHItkjI+qaLLSkMriqlDZwiNtiNfqlPTKIQna3MEyeAelJ12RsgWnlQ0U6a8M2r1Dgg6Q6Ope1L1IdGFNia4o8QtAuCvpikHpKVvYhnCXhmandwj5FyysX0hJpTNKQn/1uNC0YKEweAj99f/qQl9pMFBTUr8AnxKC2WPLg4WjJ1Y0WSxorRavFBzY3hYZWdpqbAs19kDjQNGoKCcERVuBaIuICAue7v+F4bJYrIIG/kwLC6SxBVRfqQTTysdxpIJx4a9at+AsJbaH+kq8YD3zs/p2HeFp+/0UqpN453ZasDDMhW2xIFyGnsQj9e0mOXEJY/lPWGwBFIrk1YtI3WLaQhbaHXCZud0+ZLxFotkSGQleIms1ftooGAITcArObLI70C0R3T9vFAy6fw44BWfiaarCSf74FdHK61t0lanIx0+bdcZ7KkwB/xRj4tNAq3EgEKlpfDxZo6O50HFko90umX0bHQ7J/IIWs2Da0CIYaLRuuiPJrx0NvdykAu070PH9k77QCrQCKiwsOF7QuxfreP10Z3qf9Ph0J49tS1Ub21JMjscfP/ZPpPAy44CyBxZwUirbGlhq46ojy5HvKHGY+sT1cZ/Hx9nGxI11T+fTTLURU+Oq3ds8u0zvxn7i+jz287hDiV+7Pk/d6zE8CR6PP7kgoSC5PHmuZ5XH0oNnOnokDOR9HOW81FEWN9x9nm2CY7rjc/OXCcfYd1Eai1eiIrVoSnFHWpxki3crkUmtxo94vyHjBfO0cEJSnrDPkael7bOc0e0CYL7bKATAHAl0Ed3RWZq208k0Z8BZ7Wxwqp5AZCQf7wkICzpjhH2deCjgFDZ2mqOigEmyT2iIjIw0j3dGaZpZ1L+R1naGBgsxgWoxmnNBjFUMH2MXtZgoMW5MpkWTUaOJnq2WHZY9FsOieiyF2GcVS5qYhSVJONSSJsaz2MVYFrvQbEkWA1lcafmjkvznat+FfTnP7x9xEMzxTtE7aV6BJtq04/6C/YjdwoOFBYKcA5wxA3r3okls3iSal97H7M3w+frkx/TNy01IdOY5WVxCXm7fPvk+b4ZZ6V/74rJ3F87cdWX1mp4tx/XHFi56YMNli++55u4VP9+3jimNo4t41LEyHvP69r+8/OHrL4r/fCw3Dqhp6mCKR3TcHUj0kDuej1cmmSZFjI+sVWaZ5kTURlrjW4397abaHxgjuFS3wC4xH5iOxR1NVnvHDHT1dhfFjEguco+OqXKNcdfEXJRc415sXhx/lB9N0iiBRTsSE0clVCfMxUdCd/Qqbb3GNU1NcdsstIU/QszYtlG4EattW0C6SmOM3RrrViMTW43DMhwSxeIRXgHz4ybhkMSAo9X4WK4jh/CsmBWYv0sXO4SqiC7Z+UEHcyR7UGvJ8uWL8uk0b34vD/MkYO0FqoSihDzNKobQpNc1GQdapiWQmZ3f7msZFcKzQL2T393S71HS727p8QTpffi9Xye/w8n+EcLn+9GGGDg6T7TJSIC7j09CR+HBmAE9JxUcn1fA4PYBwvNsEqHHz+bNZ4lmeJ+cGuXlkjPOkp4gXM/SfV2k8y/YkvPN5q/aDrG4j99lUeyXA7bmq6euOP4hH23vP+H6pQ+zCYn3bWQepjA769q2u+0nTX9ySx279ZriugdFpoxFODSY3qFE1i2QFhfBol09Xb1cAddc1532uxwPO6zJjq6OoGubS3UJswaSPfmpVodij3bbWDz3x8Wq+CRvWxfH4oxYacPYgJoomURpzERpvsQsFYf91Uys+20tvfvnizLgd3vyVxFzBcTqdQUcWL0UJ3NmV5kzM8R6ppxwtsR6lgk0TlichLNFtID5YmN0tGSOPS3z6X1JrmfZFkqno8xGOCYe7bzg/H7kVORSueoO+g9OEkm1AGm18OAAJwxfvCQQpznNERaz1czNWkRMCjnN0SnYwvzZy5czP9bj/Dynt09en/x+fbEcEy3CDfHxefFeZ/O6dbHJVy46pyqlf+6Ykh07lLUr5s3KLzsv5k+2suopK365ECvv2rYZajpWXgylsTWBBXatu3aWVq6phXpQ5x69m92bmhufmzokda6+SrcOTByYcnbi2SmV1vPtVYlVKTOts+wztIsSZ6Vs09+J+yTpk+R30vbH7U/bqxt6glf1a/74PupArUw9W5uofR75dWqbFumMwsJzmy3MnOCOiqQoV/tqcrWnW5dIhR7hLVfmThvTbAFbta3Bpuoy2eoy2dpg50CkcIstKVw/Jjc0m1h/wiU2oU54wib2vj7CFbYFLDaP54XTayixhpJsFtE2xlax9SzIDjPVwwrZSMSoWJepwutME4MwTYzANDENJjMsJI5Kv0vRBDEcs4uhWIxYfMzlGdoviXVefcix8wtGaGIFfrdfO97RGlqByLaFB50DwtkWsjQv1pkXL1ybkBAfx0Xm7eJUOuXba+8fuLruup0zF+65bOLKHs4HFy1+9KEF9U1tM0zPNY4evcK4/b62n284Z+Dxn5X733jxtXdf2/6+WGeF2I+b4PdeSlMgNrRAkiS6JHZt90WXdsbXzmS1M5ntjLedyWhn0tsZXeyGywSnZsRlDIw4O6Ikc0JGbcbSiJsirsp8MPbRnOcVR0RiclJir/Kc9xJNKXw851ousyVVWasiqmxVkVX2KsdM68yImbaZkTPtMx0bfRu7RHfxZXbJ7NY3c6KtMnKab1rXBd4FmQ2ZN9vusq/uelvOrb3utz1sv6/L/V1bfC/5EuS7CG9ktDPediaznQm/r7n9FcztL2Vuf01sNq3G7kBM2oCJ1i5ZdpuarPvi1cgeqcmt/JFAhitHHgRcha6RrsmuJ107XOZol8c1x7XHpXpcK13c9RxyRTyym9xjAnFCXGMBxjW2k3FiGuNiz2mJS8iXe48W5cxnrEdV6uxUnuqOt6hiGuIhVWQYEXKCCcSKkFPdPSI9ySw50xWITcrPFY/3kTksKYQidl0JInZdunjSpYunXJp4K5fcJUQvfL+Fn08W48gmeSjNzIaip9wDdmazbDGmeB7MgY1CqWTE89ki8wkVYL7bJLRkJ8sZpGPHq87dlssLcxtyea7YRjNJToU0ebzUQ8bnMkjkG8lo8Yi56TIK9cxoudai5dyjdSGMs9ixgE9MITpKjB8tzzjRZnlOy9hDrJBGIq+5eod3vUnzRrSvPbHCkJL8B+efq+H4E8rD88Te17E60YltEGXhwXnYBeVy9WOdygK7If6wKSaGMnOgS/c0rykux+fUYrRYTTFnOPQUiuhqSWGm7oC0OFTTo7wplOF12K3dbCmsa5cIm9mvppBHS01h+NAhDtIhkMfobP/y5cupU7Jgk+Yjx59oEEKx/RJCy7+Lr0sP3ie/b79QekDul8k/LjEBdxqPjxNbta+wOfr6y5Yu7pN188t3jCzqn/3HsZc/N9EZtNfPWDozIaFnylVbb5sw4+XLd3zAznLPml9bcpY3KSt3+PJzhy7p6vEPu2x60piqMf287tRYW2Ze0dKqievOe0xkkEzjCM823YGd2rOZ7PjMIDwQ2RpmrO2MpZ0xtzM2EeZeX36EiJKxYBpcjJjdYWMKJWgR/mgbdgYlMlrLoAzmOClZ20LJ2s4Mi7U0orTaMtfSYFllUcmiW9ZbgpZtlp0Ws0XsAGLbtoR2AMkc2SjSuCV02g4z8tgk9g0Re2AOiw0FnFmenkSAywPUFj6Tkljfpgs7PghJzyB9HywQCbxA2/9dgTwrHy8QqduZl6e9Ks5MYdGsxNB5WWzTzn5OsTXHCQ9yLfmcgimzc666quWpp2L9XdPuWacNrr2XT13BLLPbblxx/OYROaHfqxRSmLhMioI0wSjJ9I/IbfSj1SArWY02iqAI4zjZyCb/rz0SaIdLjpODHMAoidEUBdQoGugE/oI93wmMpRhgHMUC44E/UwLFARMpHpgEPEYuSgSfTC7wKZQMdEtMpRRgGrmNn8gjUadUYDp5gBmkA73AHymT0oFZlAH0AX+gLuQFdkUc/UDdyAfMluinLsZRyqGuwO4Se1A2sCf5gb2oO7A38HvKpR7APOoJzKdexnfUR2Jf6g3sR3nA/pRv/JMGSBxIfYCDJBZQX+BZ1A84mPoDC2mAcYQCNBBYRIOAQ6gAWAz8lkroLGApDQaWYfc8TEMpABxGRcDhNAR4tsRyKgaeQyXAEfjce4jOlTiShgJH0TDgaBpufENjJI6ls4Hj8BnoII2nEcAJEs+jc4EVNNL4B1XSKOBE4EE6n0aDr6KxwEk0DniBxMk03viaqmkCsIbOA04B/p2mUiVwGk0E1tL5wAupyviKpkuso0nAGXSBcYBmUjX4WRJnUw3wIpqC9otpKnCOxLk0zfiS5lEtcD5NB9ZLXEB1xhe0kGYAF9FM4CXAz2kxzQIuoYuAl9LFwMskLqU5wMtpLvAKmmfsp2USG6geuJwWAP9ACw3x/9qLgFdJvJouMfbRNbQYeC0tAV5HlwKvp8uMT6mRlgJvoMvRsgL4Kd1IVwBvomXAlbQcuAq4l/5IfwCupiuBN9NVxh66ReKtdDVwDV0LvI2uQ+/twD10B10PXEuNxm66k24A3kUrgH+SeDfdBFxHK4HraRXwHuAndC/9EXgfrQbeTzcDH6BbjI/pQbrV+IgeojXADXQb8GGJj9DtwEfpDuBjdCfwcYlP0F3AJ+lPwCDdDWwCfkjNtA7YQuuBG+le4wN6iu4z/kabJD5N9wNb6QHgZnoQuEXiM7QB+Cw9bLxPz9EjwD9L3EqPArfRY8C/0OPA5+kJ4Av0pPEevUhB4EvUZLxLL0v8KzUDX6EWYxe9ShuB2+kp4Gu0Cfg6PQ18A5+CdtGbtBm4Q+JO2gJ8i54Fvk3PGe/QO8C3aRf9GfgubQW+R9uMt+h9iX+j54Ef0AvAD+lF4EcSP6aXgJ/Qy8Dd9FdjJ+2RuJdeNXbQp7QduI9eA34mcT+9Dvyc3gB+QW8Cv6Sdxpt0QOJX9Bbw7/S28QZ9Te8A/yHxIO0CfkPvGa/TIXofeFjit/Q34BH6APhP+hD4ncTv6WPjNTpKnwB/oN3AH4Hb6SfaAzxGe4E/06fAXyQep8+MV6mN9gMN+hz4n5z+P5/Tv/2d5/Svzzinf/UvcvpXp+X0A/8ip395Wk7/4gxy+v4TOX3+STn9s3+R0z+TOf2z03L6PpnT93XK6ftkTt8nc/q+Tjn909Ny+l6Z0/fKnL73d5jTP/j/lNN3/Sen/yen/+5y+u/9nP77zen/6pz+n5z+n5z+6zn9ld9/Tv8/7yjp0QplbmRzdHJlYW0KZW5kb2JqCjkgMCBvYmoKPDwvVHlwZSAvRm9udERlc2NyaXB0b3IKL0ZvbnROYW1lIC9BQUFBQUErQXJpYWxNVAovRmxhZ3MgNAovQXNjZW50IDkwNS4yNzM0NAovRGVzY2VudCAtMjExLjkxNDA2Ci9TdGVtViA0NS44OTg0MzgKL0NhcEhlaWdodCA3MTUuODIwMzEKL0l0YWxpY0FuZ2xlIDAKL0ZvbnRCQm94IFstNjY0LjU1MDc4IC0zMjQuNzA3MDMgMjAwMCAxMDA1Ljg1OTM4XQovRm9udEZpbGUyIDggMCBSPj4KZW5kb2JqCjEwIDAgb2JqCjw8L1R5cGUgL0ZvbnQKL0ZvbnREZXNjcmlwdG9yIDkgMCBSCi9CYXNlRm9udCAvQUFBQUFBK0FyaWFsTVQKL1N1YnR5cGUgL0NJREZvbnRUeXBlMgovQ0lEVG9HSURNYXAgL0lkZW50aXR5Ci9DSURTeXN0ZW1JbmZvIDw8L1JlZ2lzdHJ5IChBZG9iZSkKL09yZGVyaW5nIChJZGVudGl0eSkKL1N1cHBsZW1lbnQgMD4+Ci9XIFswIFs3NTAgMCAwIDI3Ny44MzIwM10gNTUgWzYxMC44Mzk4NF0gNzEgNzIgNTU2LjE1MjM0IDczIFsyNzcuODMyMDNdIDgzIFs1NTYuMTUyMzQgMCAwIDUwMCAyNzcuODMyMDNdXQovRFcgMD4+CmVuZG9iagoxMSAwIG9iago8PC9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggMjYyPj4gc3RyZWFtCnicXZHNasQgFIX3PsVdTheDTpKZoRACZUohi/7QtA9g9CYVGhVjFnn7+pOmUEHlcO539Cq9tY+tVh7omzOiQw+D0tLhbBYnEHoclSanAqQSflNpFRO3hAa4W2ePU6sHQ+oagL4Hd/ZuhcODND3eEfrqJDqlRzh83rqgu8Xab5xQe2CkaUDiEJKeuX3hEwJN2LGVwVd+PQbmr+JjtQhF0qd8G2EkzpYLdFyPSGoWRgP1UxgNQS3/+WWm+kF8cZeqy1DNWMGaqMprUucqqXP2riwlbUzxm7AfWGWouk/bZWMvOSl713KLyFC8V3y/vWmxOBf6TY+cGo0tKo37P1hjIxXnDxIJhhgKZW5kc3RyZWFtCmVuZG9iago0IDAgb2JqCjw8L1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUwCi9CYXNlRm9udCAvQUFBQUFBK0FyaWFsTVQKL0VuY29kaW5nIC9JZGVudGl0eS1ICi9EZXNjZW5kYW50Rm9udHMgWzEwIDAgUl0KL1RvVW5pY29kZSAxMSAwIFI+PgplbmRvYmoKeHJlZgowIDEyCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxNSAwMDAwMCBuIAowMDAwMDAwMzk3IDAwMDAwIG4gCjAwMDAwMDAxMDggMDAwMDAgbiAKMDAwMDAxMDgxMSAwMDAwMCBuIAowMDAwMDAwMTQ1IDAwMDAwIG4gCjAwMDAwMDA2MDUgMDAwMDAgbiAKMDAwMDAwMDY2MCAwMDAwMCBuIAowMDAwMDAwNzA3IDAwMDAwIG4gCjAwMDAwMDk5MzQgMDAwMDAgbiAKMDAwMDAxMDE2OCAwMDAwMCBuIAowMDAwMDEwNDc4IDAwMDAwIG4gCnRyYWlsZXIKPDwvU2l6ZSAxMgovUm9vdCA3IDAgUgovSW5mbyAxIDAgUj4+CnN0YXJ0eHJlZgoxMDk1MAolJUVPRg==",
                                "contentType": "application/pdf"
                            }
                        ],
                        "effectiveDateTime": "2024-02-25T14:46:39.219042",
                        "code":
                        {
                            "coding":
                            []
                        }
                    }
                },
                {
                    "name": "labTestCollection",
                    "part":
                    [
                        {
                            "name": "labTest",
                            "resource":
                            {
                                "resourceType": "Observation",
                                "code":
                                {
                                    "text": "Hepatic Function Panel (7)",
                                    "coding":
                                    [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "24325-3",
                                            "display": "Hepatic Function Panel (7)"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "status": "final"
                            }
                        },
                        {
                            "name": "labValue",
                            "resource":
                            {
                                "resourceType": "Observation",
                                "status": "final",
                                "code":
                                {
                                    "coding":
                                    [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "2885-2",
                                            "display": "Protein, Total"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity":
                                {
                                    "value": 9.6,
                                    "unit": "g/dL",
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange":
                                [
                                    {
                                        "low":
                                        {
                                            "value": 6.0
                                        },
                                        "high":
                                        {
                                            "value": 8.5
                                        },
                                        "text": "6.0-8.5"
                                    }
                                ],
                                "interpretation":
                                [
                                    {
                                        "text": "Abnormal",
                                        "coding":
                                        [
                                            {
                                                "code": "A",
                                                "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
                                                "display": "Abnormal"
                                            }
                                        ]
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource":
                            {
                                "resourceType": "Observation",
                                "status": "final",
                                "code":
                                {
                                    "coding":
                                    [
                                        {
                                            "code": "1751-7",
                                            "system": "http://loinc.org",
                                            "display": "Albumin"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity":
                                {
                                    "unit": "g/dL",
                                    "value": 3.8,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange":
                                [
                                    {
                                        "low":
                                        {
                                            "value": 3.6
                                        },
                                        "high":
                                        {
                                            "value": 4.6
                                        },
                                        "text": "3.6-4.6"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource":
                            {
                                "resourceType": "Observation",
                                "status": "final",
                                "code":
                                {
                                    "text": "Bilirubin, Total",
                                    "coding":
                                    [
                                        {
                                            "code": "1975-2",
                                            "system": "http://loinc.org",
                                            "display": "Bilirubin, Total"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity":
                                {
                                    "unit": "mg/dL",
                                    "value": 0.3,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange":
                                [
                                    {
                                        "low":
                                        {
                                            "value": 0.0
                                        },
                                        "high":
                                        {
                                            "value": 1.2
                                        },
                                        "text": "0.0-1.2"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource":
                            {
                                "resourceType": "Observation",
                                "status": "final",
                                "code":
                                {
                                    "text": "Alkaline Phosphatase",
                                    "coding":
                                    [
                                        {
                                            "code": "6768-6",
                                            "system": "http://loinc.org",
                                            "display": "Alkaline Phosphatase"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity":
                                {
                                    "unit": "IU/L",
                                    "value": 83.6,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange":
                                [
                                    {
                                        "low":
                                        {
                                            "value": 44.0
                                        },
                                        "high":
                                        {
                                            "value": 121.0
                                        },
                                        "text": "44-121"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource":
                            {
                                "resourceType": "Observation",
                                "status": "final",
                                "code":
                                {
                                    "text": "AST (SGOT)",
                                    "coding":
                                    [
                                        {
                                            "code": "1920-8",
                                            "system": "http://loinc.org",
                                            "display": "AST (SGOT)"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity":
                                {
                                    "unit": "IU/L",
                                    "value": 19.4,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange":
                                [
                                    {
                                        "low":
                                        {
                                            "value": 0.0
                                        },
                                        "high":
                                        {
                                            "value": 40.0
                                        },
                                        "text": "0-40"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource":
                            {
                                "resourceType": "Observation",
                                "status": "final",
                                "code":
                                {
                                    "text": "ALT (SGPT)",
                                    "coding":
                                    [
                                        {
                                            "code": "1742-6",
                                            "system": "http://loinc.org",
                                            "display": "ALT (SGPT)"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity":
                                {
                                    "unit": "IU/L",
                                    "value": 13.5,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange":
                                [
                                    {
                                        "low":
                                        {
                                            "value": 0.0
                                        },
                                        "high":
                                        {
                                            "value": 44.0
                                        },
                                        "text": "0-44"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DiagnosticReport/$create-lab-report"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Parameters",
            "parameter": [
                {
                    "name": "labReport",
                    "resource": {
                        "resourceType": "DiagnosticReport",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v2-0074",
                                        "code": "LAB",
                                        "display": "Laboratory"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/4cc6fd69f81042a0b6d123e2080a7c1a",
                            "type": "Patient"
                        },
                        "presentedForm": [
                            {
                                "data": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoVW50aXRsZWQgZG9jdW1lbnQpCi9Qcm9kdWNlciAoU2tpYS9QREYgbTEwNCBHb29nbGUgRG9jcyBSZW5kZXJlcik+PgplbmRvYmoKMyAwIG9iago8PC9jYSAxCi9CTSAvTm9ybWFsPj4KZW5kb2JqCjUgMCBvYmoKPDwvRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDE4Mj4+IHN0cmVhbQp4nHWQ0QrCMAxF3/MV+QG7pmmaFsQHQfes9A/UDYQ9OP8fbDfdQFhTmnIP9zaU0JbaUTk0ObwN8AKjMqm/XkTCWtcW58vYQ9My9m+oPFJAshJwfEAHl78EdXWXjK/jmKE5eyRvQl2KuQNapzBeUyTlhHmAqrFxquw5Yr7j3lrWA+YnqGEXUhAunhn4OIFoSIisxgVIWByRnKz6nOSNVUoqugDLG0B44wmvWyBN4JTLv3wAWrRKswplbmRzdHJlYW0KZW5kb2JqCjIgMCBvYmoKPDwvVHlwZSAvUGFnZQovUmVzb3VyY2VzIDw8L1Byb2NTZXQgWy9QREYgL1RleHQgL0ltYWdlQiAvSW1hZ2VDIC9JbWFnZUldCi9FeHRHU3RhdGUgPDwvRzMgMyAwIFI+PgovRm9udCA8PC9GNCA0IDAgUj4+Pj4KL01lZGlhQm94IFswIDAgNjEyIDc5Ml0KL0NvbnRlbnRzIDUgMCBSCi9TdHJ1Y3RQYXJlbnRzIDAKL1BhcmVudCA2IDAgUj4+CmVuZG9iago2IDAgb2JqCjw8L1R5cGUgL1BhZ2VzCi9Db3VudCAxCi9LaWRzIFsyIDAgUl0+PgplbmRvYmoKNyAwIG9iago8PC9UeXBlIC9DYXRhbG9nCi9QYWdlcyA2IDAgUj4+CmVuZG9iago4IDAgb2JqCjw8L0xlbmd0aDEgMTg0MjgKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCA5MTQxPj4gc3RyZWFtCnic7XoJeFRF1vapureXdLqT29k76aRv0kkD6bAlYY+kQxbAiOyYYJAEiIRFWQIIihLGPaIwqKjoCO64dxLEgDowbqO4gIo6boCIiuMgyCgqSu7/VnWHBHC+n/H/vu9/fJ65N+etU1Xnnqp7zqlT1d0hRkSxAJV6DS0pLWOFLI+I7UVr/tBRI8deMWV9IpFiRf2uoWPHD7H92bIC/UHUe40c2zN3ccLTLiK+AfXqCSUjKkatnvk9Ud86IuctUy+qmctXsLvRfw76q6YuWqDf437/ayLzL6BxF86dftHrSyrXEjlGoX7x9Jr6uZREEdBfAHlt+uwlF046+GkrUdeuRFGD66ZdtPiF63+4ARPeRmTdUFdbM21v3MvQx+NIDIqGmLyIdDyPOVJm3UULFmd8yf9MZLoLbdWz50ytydqe/hbe5370N19Us3iuqcXRgD4xP/3imotqE6t7fwJjVKCtZO6c+gVGNq0BP1v0z51fOzfrvRFbidx4v0joJYWsxMlJzDDAC1tW0BEqoD+RBe0a9aQJ0PYYZE2oKyQvo4vQ+SsXnrcMbjuXijU69uSxSzXZctJVIVts1AO3qWZ+zRTSpy6ZP5v06fNrZ5FeVztlPumzaxZcTHqHTrKHeU7mcJsiZ9sPN6OhNBw4FjfDbM8DimdMrrWPttz61uTogu+tKVb52L2fdckW5WujBm069uTx6RpZheaITrPk0iZEcWFrxCGuhqGMknYyY1bj6EKaSwtoPSxGsj4N9XpRNz47cU897c0V5Tq2Cla0mtaaRISmhErlLbqQx1hNPNKscnGp4RmcuEaMPHckBTDSetM7baNZnmUwaw4Ih2F81Wd6Rs5CDdt1CFWRIi2aE7KotKV4C+E3A1K8E8868Rh1Vu18yHbGsP2FHIcFmCSNQnPsgXGTw77oJ30w3PhI1IDDjFSaAIKPUPvfvpb/1zdbxW9VRpx+q8PFbZ5p8UgtFpoookDFeqaZ1BDmGay8KMxzxEVdmFfgo65hXu0kY4KNosK8GRxREc2nGVRDs2kEomcC1aJej5Y5JKK+D+zam3qhf4RsmYNYW4IIq0XfcLoI7dMhezFQp+6gDm06jYHUdFoIvgatJ9c65B6GZC5G6I1bxG+d1H36aMWozQcvsAbtoRn2kGPODo83AyPUoa8+PHq9fJtFwGnUw9x5YQ34X4+C/9FL/QwW/H95vp7KQOWwS+wZyl97gicqxHOZpi3kAiWbHiKX6sPOQ8aXoAOibJthHBD9ouR/x0OtYSLaQI+zGfQ4baXn2WE89SRtpo30CiVSCd1FS+kWjGRG7L9C18OnYxDBJXQLcxkbsRvcg0i+h96A7Hl0BW2hBJZkfEXL6GrlHTx1NTkoA9ExCpFyIzvHWIhstEe9EtnhHETOXNZgVBg3GauN++kB2qy8YhynSKyOqbjfML4x/c34GBFdRbfSHbSHrY54CivqPKy7zcqfEFNrlUkqM6YbxzCDdLoEc1ARs2+wbdwP7bX0JUtiS5ViaLnPCBovQspNkxCba2kL68OG8nRTlTHCeIMSMMZiaL2DmmkT7lZ6jj5kdtNh437jMLkoB6tsGezxJtumtB1f3lYIi5lgpW40AD1z6M/0V9rJvOwvfI7Jbso1BUyXGruQKXvTeMz2ITz5BfuBX4F7mfKyWmYMwZq/mv4orE0v0acsmfVkI9kE3o3P4Xcr85FRc+RKnIa1dD3dDu27mZ9t4na+Q7lPfVT92ZzatteIgkd8dCf25b8wB95UZ/XsD+w99hkv5pP5nXyfcov6sPq2pQZvfQGyxI30KP3AYlh/Npqdz+rYUnYt+yO7g73BdrIDvIiP47P4IaVOmac8pw7BPVatV680XWO6wXygraLtxba32n4wco1raDTiYTlmfyvdjTfbTDvoA9x7aB8zsUgWhVtn6Ww8uwz3FexGdi/bwB5mGzHKTraPfcWOsO/ZzxyJkpt5Ck/nGbi9fD6/hN/C7+I7cO/k/+A/KYlKhuJX+igFSqUyB7O6VlmF+ynlUzVZ3aEasHOuaY1pnWmD6VHT86bDZrvlD1ayvv7Lfcezj+9uo7br2ta0NbdtND6lePgwGVbw4BQzGnmrBrl7Mc4rDyDO32F22C6ZZbPB7BxYZjKbyeaxxbDkVWwte0DO/Qn2LKz0PjuEOTu4W865B+/Dh/CRuC/gtXweX8VX8438PX5MsSiRSrQSr2QrQ5VJSq2yQFmirFGCyuvKJ8o+5ajyC25DtakeNUP1qX51qDpZXajerX6pfmmqMr1m+txsM19kvsbcav7W0tcy2DLKMtoyybLSssmyy1qN6HyBnqKnO+cBtldZrpQqT9FNPE918Tf5m4jnyTRNGcELxTmWXccvZxt5pmmxeRAfxM6lw6oPtn6Zr+NH+SBlBCtnY2km7x3SZo5TH0FRoL5AB9Vn8W5vQvNis51dwQ+Z7dTMZN5mLym9VL/yGn2o7GEW9R76SLWxRHaQP6SMQhQ8pw42VVC6chc9ocxjl9NTvBRHkZ+tKxDH57JHkBfGsVz2o4ITJj8XUdRP+YyupFn8b3QQ6/g6uo1NU6fTTZTHltKX9CBWRTfTxeZsczx7lc9QG3ks20hcfVjsISyTKaY4uopNUtaaD/EPsLvtUG20W3kMs9/Bn8Aeftg0htVhBVxO19A8YzktMVWob7PppLAJlKXuRXZbquSq6SiXIatUIadtwuregjxQpIxASxIi5xzExXhkiLW4b0eeUBFBM7DGz0MWe5M2msfxVppuimLIOsjGr7WNoYnGg3SHMZ0uNlZTd+SDa42l0LiBPqeVtIFd3XYZ9tE0rJzd7BxTGd9hKjO680b+AR/L15zsX1g7iyXR33E/gcpgnO8a1fdxti00VhjvIrq7IsPeQVPobNqPt/wGIwxTtlFe27m8yShT5uJ999Bo4yHDw2xUZ8ymkfQsPWAxUY3FDx8H2dt438uolo8xFii1bTNgh5WwQgDWWoj8c32gePy4okDh4LMKBg0c0L9fn/y83N69evbonuPP7ta1iy8r05uRrnvSUt0pya6kxIT4uNgYpxYd5bBH2iKsFrNJVTijnFJvWbUe9FUHVZ932LDuou6tQUNNp4bqoI6mspNlgnq1FNNPlgxA8sJTJAMhycAJSabpBVTQPUcv9erBN0q8eiubOLoC/I0l3ko9eFDyIyS/SvIO8OnpeEAvTaor0YOsWi8Nli2qayytLoG6pkhbsbe41tY9h5pskWAjwQUTvXObWOJgJhmeWDqwCSdjByYVTPaWlAZd3hIxg6CSVVozLThqdEVpSUp6emX3nCArnuqdEiTvkGC0X4pQsRwmaC4OWuQw+gzxNnSD3pSzrXFFq0ZTqv32ad5pNVUVQaWmUozh9GPckmDipfuTOqpQHlNccW3n3hSlsTRphi6qjY3X6sH1oys696YLrKyEDjzLs8qqG8sw9AoYsXysjtH41ZUVQXY1htTFm4i3Cr1frbdUtFTP1IMR3iHeusaZ1XBNcmOQxixJb05ODmw29lJyqd44rsKbHixM8VbWlLib4qhxzJIWV0B3ndzTPadJc4YM2xQVHWbsjs5M7Yk+yUlxwZWPOWFZJmbkHY6ACOpTdcykwot36i+gtj81Tu0PMVyVDE8Fp8EjM4IRxdWN2kDRLp4PmrI0r974PSECvAf/cXJLTbjFnKV9T4IVcXIi1NDfzgf9/mB2tggRSzF8ijkOlvU+3XMWtXKvd66mo4D5aBRsW1M5sCfMn54uHHxDa4CmoBJsGF0Rqus0JaWZAj39lUFeLXq2tffEjxc9De09Jx6v9iKSN8oTd3zQ6jvxF60lxJbWDQyyhP+iuzbUXz7WWz56YoVe2lgdtm35uJNqof7+J/rCXDC2uEJJ4WGOpyiyF0FZdUJYVCrsQTULf2YZ1NNaLVZEpWxhellQqx4WwkpbevoZPtRqHBZPyaLjsfA0gwP9J9cHnVQ/aXr2RgUTxlZZPm5iY6PtpD6EWmjA4eECEU/jKtL14iCNx8rMwl+rsa2/oMqUYAAmKxYCiL9QU7h6kmBKmK/EJaKze04ZEl1jY5lXL2usbqxpNRqmeHXN27iZP8+fb5xbWt0eOK3GlhtSgmUrKmGrOjYQi4LTkCYvu250U4BdN3ZixWaNSL9uXEUzZ7y4ekhlUyb6KjbrRAHZykWraBQVXVSonOElm7lVyqdsDhA1yF5VNsj61FZGss3a3sZoaisPtWntbRxtaqgtINvEJXJM8biKztEjl2Rld7nh4XMLVUVarad873GGl/nUulnt3GeGTntExG/TbTm1blE694maw2YjUunfv/5vuqEzOjLyt+mOOKVutXZogZlFTbPb/3t0R0SonfuEbqfDIT4z/XfoNnXuE7pjo6J+m277KfXIyI7IgZlt0BmvaafH02/SbT9JtxgpKSbmdJ+fyRV1at1h6dxnRy0lLk769d++tFPq0dEduqOhHjpTExJ+m+5Tv9XQtA4tGDcaNT0p6XSf/xbdTqetg4d66Ex3uX6b7vhT6jGddMOFTujMcrvFd63//pV46lhxHVowbgxq2bp+ejydyZV86liJjs7jxkFnD68XCes36HafOlZyR1RiXDFSrs93eqyeyeU5dSx3hxaM60Ktb7duMh7/7Sv9lHpaWoeWNKwb1Abm5Jy+Ds7kyjylrusdWnSsG9SKc3NPj9UzubqdUs/K6tCSRZSBWnn//qfH6plc3U+pZ2d3aMkm8qE2dvDg02P1TK78U+o9eiR18FAPnVWlpafH6plcp35/nJeX0sFDPXROKy8/PVbP5Bp8Sr1//9QOHrENnZtpnNK1xZfk2fms0o32grjSrdmf6tmsdFFSmwd5Aq2KtyUmPje6qLui42zUU6IOnAN6ErRVEb/TTFbSxG8owGWgBtCToK2gnSDsFEDRq4PmgNaB9ooeJVVxN+seraiL4sKzLpy1opVEOgQyQAp5gD1BI0GTQStB60BmKSda5oCWgbaCDsuegJLYvDoPc09svkEWLTNn58pqTahaNUlWW86rDJUjRofKkuEhsYEhsd75oeYeQ0Jll5xQGZOV2yBKmyN3W1GCkoCXTMDE5wIZf5GiGUMCWK/EUxDEFXO4JaDEtGT6ctdtVVRiClcYTSOPsU1hzQ5nbpGNG/wQkrGHf8MPhnr4wZYoZ+66orP5PnoStBWk8H24P+Wf0jK+V9gcWAhaB9oK2gE6BDLzvbj34N7Nd1M0/4R6ggpBk0HrQFtBh0AW/glQ4x+Lz1ESBV8I4vxjoMY/wmt9BIzmH4L7kH+Iqb3T3G9A7mbJ+HuGGU9WmElMCTMxCbmt/O3mn7ohonzwNCLqGSUDoZmnZDRn9fa0KknNBTM8rfyzFt3vWV/Ui++iIIhjJrsw8i7SQaNA1aC5IDO498C9Rw2gVaD1oCAIUQbUQDrfDnod9B71AgVAo0BWvrMZw7TyHc2+IZ6iBP4m/ytSgoe/wV+R5ev8ZVm+xl+S5aso01Bu5y83p3moKBL9hGc0lBrKnug38b+0ZMZ4jCIn3wrbeYA9QYWgkaDJoJUgM9/KM5qneWKg5BnajoOChzfTV7J8kO61UmCmJ+ArRgDqAnwDzwIHWKev8/GAb80dqArw3bQanADfVSvACfBduhycAN/sReAE+KbNBCfAN3EyOAG+kePAAVr53U9ndvH0GzmL6UXR/BJY6RJY6RJY6RJS+SXipp9UMbc7m7OzYbG1AX+3bE/DFtbwLGsYwxruZQ21rOEK1rCcNRSwhgtYg581uFlDGmsIsIZnWH+YooEFNp5UHRBIYg3bWcPjrKGeNfhYQxZryGQNOusXaOXpzcPzZFEqi5YisehQnjUY2Seap8Oi6Yj5dOSErcAdIEPWAhDSM0LCrjRRZrRkF4bqPQbmzikaxl/Agy/ADS/QHpAKB72AMHoBSl6AgmhgIWgyaBvoEMgAmSGdgYmvlBgN7AkqBE0GLQMdApnldA6BOM0JT/FJObGe4UmPFDX+Am7xQ0E6Tw+kam7Nrw1TVrpZdBobmWak8X4kzqQ4mFmdrcyx6QfHjz84KKIogt/EV1IqHLEqXK5s/inV08pub/Y94ymKZ7dRmoqoYwPIx7JQ9qd6We9Dbqso88nNH0WZ2+yegMeim305ni0sSjy1yfOTe7/nK3crB3vA/Yznfb1VZc2ed9Hy6CbPLvf1nld7tlrR8qyvlaHYokvRze7+nse3S9Hl6Fjb7LlCFJs8l7uHema5ZUdtqOOCetQC0Z4xvomeYdBX4p7iCdRD5yZPofsCT0FIqo94ZpOnF6bgD7HZmGw3txzUmyYVju/XyuoCOZY1lgrLSEtfS64lx5Ju8VhSLSmWOGuMVbNGWe1Wm9VqNVtVK7eSNa7V2Bvwi9/548zynzbEZ2hGquQ1TvLfBuS/AnBm5XQ2BWOVcl4+dggrD26bSuVT9ODRsd5WZhs9MWjyDmHBmHIqHzck2N9f3moxxgT7+cuDllHnVzQxdlMlWoP8ulZG4ypamSGark4R319uJsacV9+YIsquV99YWUlJCYsKkwpjBjsHlJX8ClSH0d9xJZ3EpwbXlI+tCD6SWhnMFYyRWlkevFl8wbmZHWGHS0s2s29FUVmxWRnMjpSOEe3K4JLKyvJWNkHKkc6+hRwi5lspZ8XGLORIt6aF5NaG5LLwPOQyRQG5iAjKknJZERFSTmVCrqk+s7SkKTNTyiTqVC9l6hP1zjLbsyCTlSVlEhpou5TZntAgZIKDpYjbDZE0txRhyeSWIm6WLEUmdIj0DItcf0LkejmSwjpk3CEZx952GcdeyPjP9Kod4vezlkGVU6vEl8PV3tJaUHXwhkV1ScGGKbreNLUy/K2xr3rK1DpR1tQGK721JcGp3hK9aVDVr3RXie5B3pImnBfHVTRVBWpLmgcFBpV6a0oqW4aOyu930ljXnxgrf9SvKBsllOWLsYb2+5XufqJ7qBirnxirnxhraGCoHItkjI+qaLLSkMriqlDZwiNtiNfqlPTKIQna3MEyeAelJ12RsgWnlQ0U6a8M2r1Dgg6Q6Ope1L1IdGFNia4o8QtAuCvpikHpKVvYhnCXhmandwj5FyysX0hJpTNKQn/1uNC0YKEweAj99f/qQl9pMFBTUr8AnxKC2WPLg4WjJ1Y0WSxorRavFBzY3hYZWdpqbAs19kDjQNGoKCcERVuBaIuICAue7v+F4bJYrIIG/kwLC6SxBVRfqQTTysdxpIJx4a9at+AsJbaH+kq8YD3zs/p2HeFp+/0UqpN453ZasDDMhW2xIFyGnsQj9e0mOXEJY/lPWGwBFIrk1YtI3WLaQhbaHXCZud0+ZLxFotkSGQleIms1ftooGAITcArObLI70C0R3T9vFAy6fw44BWfiaarCSf74FdHK61t0lanIx0+bdcZ7KkwB/xRj4tNAq3EgEKlpfDxZo6O50HFko90umX0bHQ7J/IIWs2Da0CIYaLRuuiPJrx0NvdykAu070PH9k77QCrQCKiwsOF7QuxfreP10Z3qf9Ph0J49tS1Ub21JMjscfP/ZPpPAy44CyBxZwUirbGlhq46ojy5HvKHGY+sT1cZ/Hx9nGxI11T+fTTLURU+Oq3ds8u0zvxn7i+jz287hDiV+7Pk/d6zE8CR6PP7kgoSC5PHmuZ5XH0oNnOnokDOR9HOW81FEWN9x9nm2CY7rjc/OXCcfYd1Eai1eiIrVoSnFHWpxki3crkUmtxo94vyHjBfO0cEJSnrDPkael7bOc0e0CYL7bKATAHAl0Ed3RWZq208k0Z8BZ7Wxwqp5AZCQf7wkICzpjhH2deCjgFDZ2mqOigEmyT2iIjIw0j3dGaZpZ1L+R1naGBgsxgWoxmnNBjFUMH2MXtZgoMW5MpkWTUaOJnq2WHZY9FsOieiyF2GcVS5qYhSVJONSSJsaz2MVYFrvQbEkWA1lcafmjkvznat+FfTnP7x9xEMzxTtE7aV6BJtq04/6C/YjdwoOFBYKcA5wxA3r3okls3iSal97H7M3w+frkx/TNy01IdOY5WVxCXm7fPvk+b4ZZ6V/74rJ3F87cdWX1mp4tx/XHFi56YMNli++55u4VP9+3jimNo4t41LEyHvP69r+8/OHrL4r/fCw3Dqhp6mCKR3TcHUj0kDuej1cmmSZFjI+sVWaZ5kTURlrjW4397abaHxgjuFS3wC4xH5iOxR1NVnvHDHT1dhfFjEguco+OqXKNcdfEXJRc415sXhx/lB9N0iiBRTsSE0clVCfMxUdCd/Qqbb3GNU1NcdsstIU/QszYtlG4EattW0C6SmOM3RrrViMTW43DMhwSxeIRXgHz4ybhkMSAo9X4WK4jh/CsmBWYv0sXO4SqiC7Z+UEHcyR7UGvJ8uWL8uk0b34vD/MkYO0FqoSihDzNKobQpNc1GQdapiWQmZ3f7msZFcKzQL2T393S71HS727p8QTpffi9Xye/w8n+EcLn+9GGGDg6T7TJSIC7j09CR+HBmAE9JxUcn1fA4PYBwvNsEqHHz+bNZ4lmeJ+cGuXlkjPOkp4gXM/SfV2k8y/YkvPN5q/aDrG4j99lUeyXA7bmq6euOP4hH23vP+H6pQ+zCYn3bWQepjA769q2u+0nTX9ySx279ZriugdFpoxFODSY3qFE1i2QFhfBol09Xb1cAddc1532uxwPO6zJjq6OoGubS3UJswaSPfmpVodij3bbWDz3x8Wq+CRvWxfH4oxYacPYgJoomURpzERpvsQsFYf91Uys+20tvfvnizLgd3vyVxFzBcTqdQUcWL0UJ3NmV5kzM8R6ppxwtsR6lgk0TlichLNFtID5YmN0tGSOPS3z6X1JrmfZFkqno8xGOCYe7bzg/H7kVORSueoO+g9OEkm1AGm18OAAJwxfvCQQpznNERaz1czNWkRMCjnN0SnYwvzZy5czP9bj/Dynt09en/x+fbEcEy3CDfHxefFeZ/O6dbHJVy46pyqlf+6Ykh07lLUr5s3KLzsv5k+2suopK365ECvv2rYZajpWXgylsTWBBXatu3aWVq6phXpQ5x69m92bmhufmzokda6+SrcOTByYcnbi2SmV1vPtVYlVKTOts+wztIsSZ6Vs09+J+yTpk+R30vbH7U/bqxt6glf1a/74PupArUw9W5uofR75dWqbFumMwsJzmy3MnOCOiqQoV/tqcrWnW5dIhR7hLVfmThvTbAFbta3Bpuoy2eoy2dpg50CkcIstKVw/Jjc0m1h/wiU2oU54wib2vj7CFbYFLDaP54XTayixhpJsFtE2xlax9SzIDjPVwwrZSMSoWJepwutME4MwTYzANDENJjMsJI5Kv0vRBDEcs4uhWIxYfMzlGdoviXVefcix8wtGaGIFfrdfO97RGlqByLaFB50DwtkWsjQv1pkXL1ybkBAfx0Xm7eJUOuXba+8fuLruup0zF+65bOLKHs4HFy1+9KEF9U1tM0zPNY4evcK4/b62n284Z+Dxn5X733jxtXdf2/6+WGeF2I+b4PdeSlMgNrRAkiS6JHZt90WXdsbXzmS1M5ntjLedyWhn0tsZXeyGywSnZsRlDIw4O6Ikc0JGbcbSiJsirsp8MPbRnOcVR0RiclJir/Kc9xJNKXw851ousyVVWasiqmxVkVX2KsdM68yImbaZkTPtMx0bfRu7RHfxZXbJ7NY3c6KtMnKab1rXBd4FmQ2ZN9vusq/uelvOrb3utz1sv6/L/V1bfC/5EuS7CG9ktDPediaznQm/r7n9FcztL2Vuf01sNq3G7kBM2oCJ1i5ZdpuarPvi1cgeqcmt/JFAhitHHgRcha6RrsmuJ107XOZol8c1x7XHpXpcK13c9RxyRTyym9xjAnFCXGMBxjW2k3FiGuNiz2mJS8iXe48W5cxnrEdV6uxUnuqOt6hiGuIhVWQYEXKCCcSKkFPdPSI9ySw50xWITcrPFY/3kTksKYQidl0JInZdunjSpYunXJp4K5fcJUQvfL+Fn08W48gmeSjNzIaip9wDdmazbDGmeB7MgY1CqWTE89ki8wkVYL7bJLRkJ8sZpGPHq87dlssLcxtyea7YRjNJToU0ebzUQ8bnMkjkG8lo8Yi56TIK9cxoudai5dyjdSGMs9ixgE9MITpKjB8tzzjRZnlOy9hDrJBGIq+5eod3vUnzRrSvPbHCkJL8B+efq+H4E8rD88Te17E60YltEGXhwXnYBeVy9WOdygK7If6wKSaGMnOgS/c0rykux+fUYrRYTTFnOPQUiuhqSWGm7oC0OFTTo7wplOF12K3dbCmsa5cIm9mvppBHS01h+NAhDtIhkMfobP/y5cupU7Jgk+Yjx59oEEKx/RJCy7+Lr0sP3ie/b79QekDul8k/LjEBdxqPjxNbta+wOfr6y5Yu7pN188t3jCzqn/3HsZc/N9EZtNfPWDozIaFnylVbb5sw4+XLd3zAznLPml9bcpY3KSt3+PJzhy7p6vEPu2x60piqMf287tRYW2Ze0dKqievOe0xkkEzjCM823YGd2rOZ7PjMIDwQ2RpmrO2MpZ0xtzM2EeZeX36EiJKxYBpcjJjdYWMKJWgR/mgbdgYlMlrLoAzmOClZ20LJ2s4Mi7U0orTaMtfSYFllUcmiW9ZbgpZtlp0Ws0XsAGLbtoR2AMkc2SjSuCV02g4z8tgk9g0Re2AOiw0FnFmenkSAywPUFj6Tkljfpgs7PghJzyB9HywQCbxA2/9dgTwrHy8QqduZl6e9Ks5MYdGsxNB5WWzTzn5OsTXHCQ9yLfmcgimzc666quWpp2L9XdPuWacNrr2XT13BLLPbblxx/OYROaHfqxRSmLhMioI0wSjJ9I/IbfSj1SArWY02iqAI4zjZyCb/rz0SaIdLjpODHMAoidEUBdQoGugE/oI93wmMpRhgHMUC44E/UwLFARMpHpgEPEYuSgSfTC7wKZQMdEtMpRRgGrmNn8gjUadUYDp5gBmkA73AHymT0oFZlAH0AX+gLuQFdkUc/UDdyAfMluinLsZRyqGuwO4Se1A2sCf5gb2oO7A38HvKpR7APOoJzKdexnfUR2Jf6g3sR3nA/pRv/JMGSBxIfYCDJBZQX+BZ1A84mPoDC2mAcYQCNBBYRIOAQ6gAWAz8lkroLGApDQaWYfc8TEMpABxGRcDhNAR4tsRyKgaeQyXAEfjce4jOlTiShgJH0TDgaBpufENjJI6ls4Hj8BnoII2nEcAJEs+jc4EVNNL4B1XSKOBE4EE6n0aDr6KxwEk0DniBxMk03viaqmkCsIbOA04B/p2mUiVwGk0E1tL5wAupyviKpkuso0nAGXSBcYBmUjX4WRJnUw3wIpqC9otpKnCOxLk0zfiS5lEtcD5NB9ZLXEB1xhe0kGYAF9FM4CXAz2kxzQIuoYuAl9LFwMskLqU5wMtpLvAKmmfsp2USG6geuJwWAP9ACw3x/9qLgFdJvJouMfbRNbQYeC0tAV5HlwKvp8uMT6mRlgJvoMvRsgL4Kd1IVwBvomXAlbQcuAq4l/5IfwCupiuBN9NVxh66ReKtdDVwDV0LvI2uQ+/twD10B10PXEuNxm66k24A3kUrgH+SeDfdBFxHK4HraRXwHuAndC/9EXgfrQbeTzcDH6BbjI/pQbrV+IgeojXADXQb8GGJj9DtwEfpDuBjdCfwcYlP0F3AJ+lPwCDdDWwCfkjNtA7YQuuBG+le4wN6iu4z/kabJD5N9wNb6QHgZnoQuEXiM7QB+Cw9bLxPz9EjwD9L3EqPArfRY8C/0OPA5+kJ4Av0pPEevUhB4EvUZLxLL0v8KzUDX6EWYxe9ShuB2+kp4Gu0Cfg6PQ18A5+CdtGbtBm4Q+JO2gJ8i54Fvk3PGe/QO8C3aRf9GfgubQW+R9uMt+h9iX+j54Ef0AvAD+lF4EcSP6aXgJ/Qy8Dd9FdjJ+2RuJdeNXbQp7QduI9eA34mcT+9Dvyc3gB+QW8Cv6Sdxpt0QOJX9Bbw7/S28QZ9Te8A/yHxIO0CfkPvGa/TIXofeFjit/Q34BH6APhP+hD4ncTv6WPjNTpKnwB/oN3AH4Hb6SfaAzxGe4E/06fAXyQep8+MV6mN9gMN+hz4n5z+P5/Tv/2d5/Svzzinf/UvcvpXp+X0A/8ip395Wk7/4gxy+v4TOX3+STn9s3+R0z+TOf2z03L6PpnT93XK6ftkTt8nc/q+Tjn909Ny+l6Z0/fKnL73d5jTP/j/lNN3/Sen/yen/+5y+u/9nP77zen/6pz+n5z+n5z+6zn9ld9/Tv8/7yjp0QplbmRzdHJlYW0KZW5kb2JqCjkgMCBvYmoKPDwvVHlwZSAvRm9udERlc2NyaXB0b3IKL0ZvbnROYW1lIC9BQUFBQUErQXJpYWxNVAovRmxhZ3MgNAovQXNjZW50IDkwNS4yNzM0NAovRGVzY2VudCAtMjExLjkxNDA2Ci9TdGVtViA0NS44OTg0MzgKL0NhcEhlaWdodCA3MTUuODIwMzEKL0l0YWxpY0FuZ2xlIDAKL0ZvbnRCQm94IFstNjY0LjU1MDc4IC0zMjQuNzA3MDMgMjAwMCAxMDA1Ljg1OTM4XQovRm9udEZpbGUyIDggMCBSPj4KZW5kb2JqCjEwIDAgb2JqCjw8L1R5cGUgL0ZvbnQKL0ZvbnREZXNjcmlwdG9yIDkgMCBSCi9CYXNlRm9udCAvQUFBQUFBK0FyaWFsTVQKL1N1YnR5cGUgL0NJREZvbnRUeXBlMgovQ0lEVG9HSURNYXAgL0lkZW50aXR5Ci9DSURTeXN0ZW1JbmZvIDw8L1JlZ2lzdHJ5IChBZG9iZSkKL09yZGVyaW5nIChJZGVudGl0eSkKL1N1cHBsZW1lbnQgMD4+Ci9XIFswIFs3NTAgMCAwIDI3Ny44MzIwM10gNTUgWzYxMC44Mzk4NF0gNzEgNzIgNTU2LjE1MjM0IDczIFsyNzcuODMyMDNdIDgzIFs1NTYuMTUyMzQgMCAwIDUwMCAyNzcuODMyMDNdXQovRFcgMD4+CmVuZG9iagoxMSAwIG9iago8PC9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggMjYyPj4gc3RyZWFtCnicXZHNasQgFIX3PsVdTheDTpKZoRACZUohi/7QtA9g9CYVGhVjFnn7+pOmUEHlcO539Cq9tY+tVh7omzOiQw+D0tLhbBYnEHoclSanAqQSflNpFRO3hAa4W2ePU6sHQ+oagL4Hd/ZuhcODND3eEfrqJDqlRzh83rqgu8Xab5xQe2CkaUDiEJKeuX3hEwJN2LGVwVd+PQbmr+JjtQhF0qd8G2EkzpYLdFyPSGoWRgP1UxgNQS3/+WWm+kF8cZeqy1DNWMGaqMprUucqqXP2riwlbUzxm7AfWGWouk/bZWMvOSl713KLyFC8V3y/vWmxOBf6TY+cGo0tKo37P1hjIxXnDxIJhhgKZW5kc3RyZWFtCmVuZG9iago0IDAgb2JqCjw8L1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUwCi9CYXNlRm9udCAvQUFBQUFBK0FyaWFsTVQKL0VuY29kaW5nIC9JZGVudGl0eS1ICi9EZXNjZW5kYW50Rm9udHMgWzEwIDAgUl0KL1RvVW5pY29kZSAxMSAwIFI+PgplbmRvYmoKeHJlZgowIDEyCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxNSAwMDAwMCBuIAowMDAwMDAwMzk3IDAwMDAwIG4gCjAwMDAwMDAxMDggMDAwMDAgbiAKMDAwMDAxMDgxMSAwMDAwMCBuIAowMDAwMDAwMTQ1IDAwMDAwIG4gCjAwMDAwMDA2MDUgMDAwMDAgbiAKMDAwMDAwMDY2MCAwMDAwMCBuIAowMDAwMDAwNzA3IDAwMDAwIG4gCjAwMDAwMDk5MzQgMDAwMDAgbiAKMDAwMDAxMDE2OCAwMDAwMCBuIAowMDAwMDEwNDc4IDAwMDAwIG4gCnRyYWlsZXIKPDwvU2l6ZSAxMgovUm9vdCA3IDAgUgovSW5mbyAxIDAgUj4+CnN0YXJ0eHJlZgoxMDk1MAolJUVPRg==",
                                "contentType": "application/pdf"
                            }
                        ],
                        "effectiveDateTime": "2024-02-25T14:46:39.219042",
                        "code": {
                            "coding": []
                        }
                    }
                },
                {
                    "name": "labTestCollection",
                    "part": [
                        {
                            "name": "labTest",
                            "resource": {
                                "resourceType": "Observation",
                                "code": {
                                    "text": "Hepatic Function Panel (7)",
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "24325-3",
                                            "display": "Hepatic Function Panel (7)"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "status": "final"
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "2885-2",
                                            "display": "Protein, Total"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "value": 9.6,
                                    "unit": "g/dL",
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 6.0
                                        },
                                        "high": {
                                            "value": 8.5
                                        },
                                        "text": "6.0-8.5"
                                    }
                                ],
                                "interpretation": [
                                    {
                                        "text": "Abnormal",
                                        "coding": [
                                            {
                                                "code": "A",
                                                "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
                                                "display": "Abnormal"
                                            }
                                        ]
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "coding": [
                                        {
                                            "code": "1751-7",
                                            "system": "http://loinc.org",
                                            "display": "Albumin"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "g/dL",
                                    "value": 3.8,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 3.6
                                        },
                                        "high": {
                                            "value": 4.6
                                        },
                                        "text": "3.6-4.6"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "text": "Bilirubin, Total",
                                    "coding": [
                                        {
                                            "code": "1975-2",
                                            "system": "http://loinc.org",
                                            "display": "Bilirubin, Total"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "mg/dL",
                                    "value": 0.3,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 0.0
                                        },
                                        "high": {
                                            "value": 1.2
                                        },
                                        "text": "0.0-1.2"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "text": "Alkaline Phosphatase",
                                    "coding": [
                                        {
                                            "code": "6768-6",
                                            "system": "http://loinc.org",
                                            "display": "Alkaline Phosphatase"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "IU/L",
                                    "value": 83.6,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 44.0
                                        },
                                        "high": {
                                            "value": 121.0
                                        },
                                        "text": "44-121"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "text": "AST (SGOT)",
                                    "coding": [
                                        {
                                            "code": "1920-8",
                                            "system": "http://loinc.org",
                                            "display": "AST (SGOT)"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "IU/L",
                                    "value": 19.4,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 0.0
                                        },
                                        "high": {
                                            "value": 40.0
                                        },
                                        "text": "0-40"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "text": "ALT (SGPT)",
                                    "coding": [
                                        {
                                            "code": "1742-6",
                                            "system": "http://loinc.org",
                                            "display": "ALT (SGPT)"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "IU/L",
                                    "value": 13.5,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 0.0
                                        },
                                        "high": {
                                            "value": 44.0
                                        },
                                        "text": "0-44"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
###  Response 
A successful request returns `201 Created` with a `Parameters` resource containing a `valueReference` to the newly created `DiagnosticReport`:
    ```json
    {
        "resourceType": "Parameters",
        "parameter": [
            {
                "name": "return",
                "valueReference": {
                    "reference": "DiagnosticReport/9b90621b-059f-4f6e-9ef5-58171098e424"
                }
            }
        ]
    }
    ```
Standard error responses (`400 Bad Request`, `401 Unauthorized`, `403 Forbidden`) follow the FHIR `OperationOutcome` shape described in [Errors](/api/errors).
###  Additional JSON Examples 
  - **More than one lab test**
        ```json
        {
            "resourceType": "Parameters",
            "parameter": [
                {
                    "name": "labReport",
                    "resource": {
                        "resourceType": "DiagnosticReport",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v2-0074",
                                        "code": "LAB",
                                        "display": "Laboratory"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/4cc6fd69f81042a0b6d123e2080a7c1a",
                            "type": "Patient"
                        },
                        "presentedForm": [
                            {
                                "data": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoVW50aXRsZWQgZG9jdW1lbnQpCi9Qcm9kdWNlciAoU2tpYS9QREYgbTEwNCBHb29nbGUgRG9jcyBSZW5kZXJlcik+PgplbmRvYmoKMyAwIG9iago8PC9jYSAxCi9CTSAvTm9ybWFsPj4KZW5kb2JqCjUgMCBvYmoKPDwvRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDE4Mj4+IHN0cmVhbQp4nHWQ0QrCMAxF3/MV+QG7pmmaFsQHQfes9A/UDYQ9OP8fbDfdQFhTmnIP9zaU0JbaUTk0ObwN8AKjMqm/XkTCWtcW58vYQ9My9m+oPFJAshJwfEAHl78EdXWXjK/jmKE5eyRvQl2KuQNapzBeUyTlhHmAqrFxquw5Yr7j3lrWA+YnqGEXUhAunhn4OIFoSIisxgVIWByRnKz6nOSNVUoqugDLG0B44wmvWyBN4JTLv3wAWrRKswplbmRzdHJlYW0KZW5kb2JqCjIgMCBvYmoKPDwvVHlwZSAvUGFnZQovUmVzb3VyY2VzIDw8L1Byb2NTZXQgWy9QREYgL1RleHQgL0ltYWdlQiAvSW1hZ2VDIC9JbWFnZUldCi9FeHRHU3RhdGUgPDwvRzMgMyAwIFI+PgovRm9udCA8PC9GNCA0IDAgUj4+Pj4KL01lZGlhQm94IFswIDAgNjEyIDc5Ml0KL0NvbnRlbnRzIDUgMCBSCi9TdHJ1Y3RQYXJlbnRzIDAKL1BhcmVudCA2IDAgUj4+CmVuZG9iago2IDAgb2JqCjw8L1R5cGUgL1BhZ2VzCi9Db3VudCAxCi9LaWRzIFsyIDAgUl0+PgplbmRvYmoKNyAwIG9iago8PC9UeXBlIC9DYXRhbG9nCi9QYWdlcyA2IDAgUj4+CmVuZG9iago4IDAgb2JqCjw8L0xlbmd0aDEgMTg0MjgKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCA5MTQxPj4gc3RyZWFtCnic7XoJeFRF1vapureXdLqT29k76aRv0kkD6bAlYY+kQxbAiOyYYJAEiIRFWQIIihLGPaIwqKjoCO64dxLEgDowbqO4gIo6boCIiuMgyCgqSu7/VnWHBHC+n/H/vu9/fJ65N+etU1Xnnqp7zqlT1d0hRkSxAJV6DS0pLWOFLI+I7UVr/tBRI8deMWV9IpFiRf2uoWPHD7H92bIC/UHUe40c2zN3ccLTLiK+AfXqCSUjKkatnvk9Ud86IuctUy+qmctXsLvRfw76q6YuWqDf437/ayLzL6BxF86dftHrSyrXEjlGoX7x9Jr6uZREEdBfAHlt+uwlF046+GkrUdeuRFGD66ZdtPiF63+4ARPeRmTdUFdbM21v3MvQx+NIDIqGmLyIdDyPOVJm3UULFmd8yf9MZLoLbdWz50ytydqe/hbe5370N19Us3iuqcXRgD4xP/3imotqE6t7fwJjVKCtZO6c+gVGNq0BP1v0z51fOzfrvRFbidx4v0joJYWsxMlJzDDAC1tW0BEqoD+RBe0a9aQJ0PYYZE2oKyQvo4vQ+SsXnrcMbjuXijU69uSxSzXZctJVIVts1AO3qWZ+zRTSpy6ZP5v06fNrZ5FeVztlPumzaxZcTHqHTrKHeU7mcJsiZ9sPN6OhNBw4FjfDbM8DimdMrrWPttz61uTogu+tKVb52L2fdckW5WujBm069uTx6RpZheaITrPk0iZEcWFrxCGuhqGMknYyY1bj6EKaSwtoPSxGsj4N9XpRNz47cU897c0V5Tq2Cla0mtaaRISmhErlLbqQx1hNPNKscnGp4RmcuEaMPHckBTDSetM7baNZnmUwaw4Ih2F81Wd6Rs5CDdt1CFWRIi2aE7KotKV4C+E3A1K8E8868Rh1Vu18yHbGsP2FHIcFmCSNQnPsgXGTw77oJ30w3PhI1IDDjFSaAIKPUPvfvpb/1zdbxW9VRpx+q8PFbZ5p8UgtFpoookDFeqaZ1BDmGay8KMxzxEVdmFfgo65hXu0kY4KNosK8GRxREc2nGVRDs2kEomcC1aJej5Y5JKK+D+zam3qhf4RsmYNYW4IIq0XfcLoI7dMhezFQp+6gDm06jYHUdFoIvgatJ9c65B6GZC5G6I1bxG+d1H36aMWozQcvsAbtoRn2kGPODo83AyPUoa8+PHq9fJtFwGnUw9x5YQ34X4+C/9FL/QwW/H95vp7KQOWwS+wZyl97gicqxHOZpi3kAiWbHiKX6sPOQ8aXoAOibJthHBD9ouR/x0OtYSLaQI+zGfQ4baXn2WE89SRtpo30CiVSCd1FS+kWjGRG7L9C18OnYxDBJXQLcxkbsRvcg0i+h96A7Hl0BW2hBJZkfEXL6GrlHTx1NTkoA9ExCpFyIzvHWIhstEe9EtnhHETOXNZgVBg3GauN++kB2qy8YhynSKyOqbjfML4x/c34GBFdRbfSHbSHrY54CivqPKy7zcqfEFNrlUkqM6YbxzCDdLoEc1ARs2+wbdwP7bX0JUtiS5ViaLnPCBovQspNkxCba2kL68OG8nRTlTHCeIMSMMZiaL2DmmkT7lZ6jj5kdtNh437jMLkoB6tsGezxJtumtB1f3lYIi5lgpW40AD1z6M/0V9rJvOwvfI7Jbso1BUyXGruQKXvTeMz2ITz5BfuBX4F7mfKyWmYMwZq/mv4orE0v0acsmfVkI9kE3o3P4Xcr85FRc+RKnIa1dD3dDu27mZ9t4na+Q7lPfVT92ZzatteIgkd8dCf25b8wB95UZ/XsD+w99hkv5pP5nXyfcov6sPq2pQZvfQGyxI30KP3AYlh/Npqdz+rYUnYt+yO7g73BdrIDvIiP47P4IaVOmac8pw7BPVatV680XWO6wXygraLtxba32n4wco1raDTiYTlmfyvdjTfbTDvoA9x7aB8zsUgWhVtn6Ww8uwz3FexGdi/bwB5mGzHKTraPfcWOsO/ZzxyJkpt5Ck/nGbi9fD6/hN/C7+I7cO/k/+A/KYlKhuJX+igFSqUyB7O6VlmF+ynlUzVZ3aEasHOuaY1pnWmD6VHT86bDZrvlD1ayvv7Lfcezj+9uo7br2ta0NbdtND6lePgwGVbw4BQzGnmrBrl7Mc4rDyDO32F22C6ZZbPB7BxYZjKbyeaxxbDkVWwte0DO/Qn2LKz0PjuEOTu4W865B+/Dh/CRuC/gtXweX8VX8438PX5MsSiRSrQSr2QrQ5VJSq2yQFmirFGCyuvKJ8o+5ajyC25DtakeNUP1qX51qDpZXajerX6pfmmqMr1m+txsM19kvsbcav7W0tcy2DLKMtoyybLSssmyy1qN6HyBnqKnO+cBtldZrpQqT9FNPE918Tf5m4jnyTRNGcELxTmWXccvZxt5pmmxeRAfxM6lw6oPtn6Zr+NH+SBlBCtnY2km7x3SZo5TH0FRoL5AB9Vn8W5vQvNis51dwQ+Z7dTMZN5mLym9VL/yGn2o7GEW9R76SLWxRHaQP6SMQhQ8pw42VVC6chc9ocxjl9NTvBRHkZ+tKxDH57JHkBfGsVz2o4ITJj8XUdRP+YyupFn8b3QQ6/g6uo1NU6fTTZTHltKX9CBWRTfTxeZsczx7lc9QG3ks20hcfVjsISyTKaY4uopNUtaaD/EPsLvtUG20W3kMs9/Bn8Aeftg0htVhBVxO19A8YzktMVWob7PppLAJlKXuRXZbquSq6SiXIatUIadtwuregjxQpIxASxIi5xzExXhkiLW4b0eeUBFBM7DGz0MWe5M2msfxVppuimLIOsjGr7WNoYnGg3SHMZ0uNlZTd+SDa42l0LiBPqeVtIFd3XYZ9tE0rJzd7BxTGd9hKjO680b+AR/L15zsX1g7iyXR33E/gcpgnO8a1fdxti00VhjvIrq7IsPeQVPobNqPt/wGIwxTtlFe27m8yShT5uJ999Bo4yHDw2xUZ8ymkfQsPWAxUY3FDx8H2dt438uolo8xFii1bTNgh5WwQgDWWoj8c32gePy4okDh4LMKBg0c0L9fn/y83N69evbonuPP7ta1iy8r05uRrnvSUt0pya6kxIT4uNgYpxYd5bBH2iKsFrNJVTijnFJvWbUe9FUHVZ932LDuou6tQUNNp4bqoI6mspNlgnq1FNNPlgxA8sJTJAMhycAJSabpBVTQPUcv9erBN0q8eiubOLoC/I0l3ko9eFDyIyS/SvIO8OnpeEAvTaor0YOsWi8Nli2qayytLoG6pkhbsbe41tY9h5pskWAjwQUTvXObWOJgJhmeWDqwCSdjByYVTPaWlAZd3hIxg6CSVVozLThqdEVpSUp6emX3nCArnuqdEiTvkGC0X4pQsRwmaC4OWuQw+gzxNnSD3pSzrXFFq0ZTqv32ad5pNVUVQaWmUozh9GPckmDipfuTOqpQHlNccW3n3hSlsTRphi6qjY3X6sH1oys696YLrKyEDjzLs8qqG8sw9AoYsXysjtH41ZUVQXY1htTFm4i3Cr1frbdUtFTP1IMR3iHeusaZ1XBNcmOQxixJb05ODmw29lJyqd44rsKbHixM8VbWlLib4qhxzJIWV0B3ndzTPadJc4YM2xQVHWbsjs5M7Yk+yUlxwZWPOWFZJmbkHY6ACOpTdcykwot36i+gtj81Tu0PMVyVDE8Fp8EjM4IRxdWN2kDRLp4PmrI0r974PSECvAf/cXJLTbjFnKV9T4IVcXIi1NDfzgf9/mB2tggRSzF8ijkOlvU+3XMWtXKvd66mo4D5aBRsW1M5sCfMn54uHHxDa4CmoBJsGF0Rqus0JaWZAj39lUFeLXq2tffEjxc9De09Jx6v9iKSN8oTd3zQ6jvxF60lxJbWDQyyhP+iuzbUXz7WWz56YoVe2lgdtm35uJNqof7+J/rCXDC2uEJJ4WGOpyiyF0FZdUJYVCrsQTULf2YZ1NNaLVZEpWxhellQqx4WwkpbevoZPtRqHBZPyaLjsfA0gwP9J9cHnVQ/aXr2RgUTxlZZPm5iY6PtpD6EWmjA4eECEU/jKtL14iCNx8rMwl+rsa2/oMqUYAAmKxYCiL9QU7h6kmBKmK/EJaKze04ZEl1jY5lXL2usbqxpNRqmeHXN27iZP8+fb5xbWt0eOK3GlhtSgmUrKmGrOjYQi4LTkCYvu250U4BdN3ZixWaNSL9uXEUzZ7y4ekhlUyb6KjbrRAHZykWraBQVXVSonOElm7lVyqdsDhA1yF5VNsj61FZGss3a3sZoaisPtWntbRxtaqgtINvEJXJM8biKztEjl2Rld7nh4XMLVUVarad873GGl/nUulnt3GeGTntExG/TbTm1blE694maw2YjUunfv/5vuqEzOjLyt+mOOKVutXZogZlFTbPb/3t0R0SonfuEbqfDIT4z/XfoNnXuE7pjo6J+m277KfXIyI7IgZlt0BmvaafH02/SbT9JtxgpKSbmdJ+fyRV1at1h6dxnRy0lLk769d++tFPq0dEduqOhHjpTExJ+m+5Tv9XQtA4tGDcaNT0p6XSf/xbdTqetg4d66Ex3uX6b7vhT6jGddMOFTujMcrvFd63//pV46lhxHVowbgxq2bp+ejydyZV86liJjs7jxkFnD68XCes36HafOlZyR1RiXDFSrs93eqyeyeU5dSx3hxaM60Ktb7duMh7/7Sv9lHpaWoeWNKwb1Abm5Jy+Ds7kyjylrusdWnSsG9SKc3NPj9UzubqdUs/K6tCSRZSBWnn//qfH6plc3U+pZ2d3aMkm8qE2dvDg02P1TK78U+o9eiR18FAPnVWlpafH6plcp35/nJeX0sFDPXROKy8/PVbP5Bp8Sr1//9QOHrENnZtpnNK1xZfk2fms0o32grjSrdmf6tmsdFFSmwd5Aq2KtyUmPje6qLui42zUU6IOnAN6ErRVEb/TTFbSxG8owGWgBtCToK2gnSDsFEDRq4PmgNaB9ooeJVVxN+seraiL4sKzLpy1opVEOgQyQAp5gD1BI0GTQStB60BmKSda5oCWgbaCDsuegJLYvDoPc09svkEWLTNn58pqTahaNUlWW86rDJUjRofKkuEhsYEhsd75oeYeQ0Jll5xQGZOV2yBKmyN3W1GCkoCXTMDE5wIZf5GiGUMCWK/EUxDEFXO4JaDEtGT6ctdtVVRiClcYTSOPsU1hzQ5nbpGNG/wQkrGHf8MPhnr4wZYoZ+66orP5PnoStBWk8H24P+Wf0jK+V9gcWAhaB9oK2gE6BDLzvbj34N7Nd1M0/4R6ggpBk0HrQFtBh0AW/glQ4x+Lz1ESBV8I4vxjoMY/wmt9BIzmH4L7kH+Iqb3T3G9A7mbJ+HuGGU9WmElMCTMxCbmt/O3mn7ohonzwNCLqGSUDoZmnZDRn9fa0KknNBTM8rfyzFt3vWV/Ui++iIIhjJrsw8i7SQaNA1aC5IDO498C9Rw2gVaD1oCAIUQbUQDrfDnod9B71AgVAo0BWvrMZw7TyHc2+IZ6iBP4m/ytSgoe/wV+R5ev8ZVm+xl+S5aso01Bu5y83p3moKBL9hGc0lBrKnug38b+0ZMZ4jCIn3wrbeYA9QYWgkaDJoJUgM9/KM5qneWKg5BnajoOChzfTV7J8kO61UmCmJ+ArRgDqAnwDzwIHWKev8/GAb80dqArw3bQanADfVSvACfBduhycAN/sReAE+KbNBCfAN3EyOAG+kePAAVr53U9ndvH0GzmL6UXR/BJY6RJY6RJY6RJS+SXipp9UMbc7m7OzYbG1AX+3bE/DFtbwLGsYwxruZQ21rOEK1rCcNRSwhgtYg581uFlDGmsIsIZnWH+YooEFNp5UHRBIYg3bWcPjrKGeNfhYQxZryGQNOusXaOXpzcPzZFEqi5YisehQnjUY2Seap8Oi6Yj5dOSErcAdIEPWAhDSM0LCrjRRZrRkF4bqPQbmzikaxl/Agy/ADS/QHpAKB72AMHoBSl6AgmhgIWgyaBvoEMgAmSGdgYmvlBgN7AkqBE0GLQMdApnldA6BOM0JT/FJObGe4UmPFDX+Am7xQ0E6Tw+kam7Nrw1TVrpZdBobmWak8X4kzqQ4mFmdrcyx6QfHjz84KKIogt/EV1IqHLEqXK5s/inV08pub/Y94ymKZ7dRmoqoYwPIx7JQ9qd6We9Dbqso88nNH0WZ2+yegMeim305ni0sSjy1yfOTe7/nK3crB3vA/Yznfb1VZc2ed9Hy6CbPLvf1nld7tlrR8qyvlaHYokvRze7+nse3S9Hl6Fjb7LlCFJs8l7uHema5ZUdtqOOCetQC0Z4xvomeYdBX4p7iCdRD5yZPofsCT0FIqo94ZpOnF6bgD7HZmGw3txzUmyYVju/XyuoCOZY1lgrLSEtfS64lx5Ju8VhSLSmWOGuMVbNGWe1Wm9VqNVtVK7eSNa7V2Bvwi9/548zynzbEZ2hGquQ1TvLfBuS/AnBm5XQ2BWOVcl4+dggrD26bSuVT9ODRsd5WZhs9MWjyDmHBmHIqHzck2N9f3moxxgT7+cuDllHnVzQxdlMlWoP8ulZG4ypamSGark4R319uJsacV9+YIsquV99YWUlJCYsKkwpjBjsHlJX8ClSH0d9xJZ3EpwbXlI+tCD6SWhnMFYyRWlkevFl8wbmZHWGHS0s2s29FUVmxWRnMjpSOEe3K4JLKyvJWNkHKkc6+hRwi5lspZ8XGLORIt6aF5NaG5LLwPOQyRQG5iAjKknJZERFSTmVCrqk+s7SkKTNTyiTqVC9l6hP1zjLbsyCTlSVlEhpou5TZntAgZIKDpYjbDZE0txRhyeSWIm6WLEUmdIj0DItcf0LkejmSwjpk3CEZx952GcdeyPjP9Kod4vezlkGVU6vEl8PV3tJaUHXwhkV1ScGGKbreNLUy/K2xr3rK1DpR1tQGK721JcGp3hK9aVDVr3RXie5B3pImnBfHVTRVBWpLmgcFBpV6a0oqW4aOyu930ljXnxgrf9SvKBsllOWLsYb2+5XufqJ7qBirnxirnxhraGCoHItkjI+qaLLSkMriqlDZwiNtiNfqlPTKIQna3MEyeAelJ12RsgWnlQ0U6a8M2r1Dgg6Q6Ope1L1IdGFNia4o8QtAuCvpikHpKVvYhnCXhmandwj5FyysX0hJpTNKQn/1uNC0YKEweAj99f/qQl9pMFBTUr8AnxKC2WPLg4WjJ1Y0WSxorRavFBzY3hYZWdpqbAs19kDjQNGoKCcERVuBaIuICAue7v+F4bJYrIIG/kwLC6SxBVRfqQTTysdxpIJx4a9at+AsJbaH+kq8YD3zs/p2HeFp+/0UqpN453ZasDDMhW2xIFyGnsQj9e0mOXEJY/lPWGwBFIrk1YtI3WLaQhbaHXCZud0+ZLxFotkSGQleIms1ftooGAITcArObLI70C0R3T9vFAy6fw44BWfiaarCSf74FdHK61t0lanIx0+bdcZ7KkwB/xRj4tNAq3EgEKlpfDxZo6O50HFko90umX0bHQ7J/IIWs2Da0CIYaLRuuiPJrx0NvdykAu070PH9k77QCrQCKiwsOF7QuxfreP10Z3qf9Ph0J49tS1Ub21JMjscfP/ZPpPAy44CyBxZwUirbGlhq46ojy5HvKHGY+sT1cZ/Hx9nGxI11T+fTTLURU+Oq3ds8u0zvxn7i+jz287hDiV+7Pk/d6zE8CR6PP7kgoSC5PHmuZ5XH0oNnOnokDOR9HOW81FEWN9x9nm2CY7rjc/OXCcfYd1Eai1eiIrVoSnFHWpxki3crkUmtxo94vyHjBfO0cEJSnrDPkael7bOc0e0CYL7bKATAHAl0Ed3RWZq208k0Z8BZ7Wxwqp5AZCQf7wkICzpjhH2deCjgFDZ2mqOigEmyT2iIjIw0j3dGaZpZ1L+R1naGBgsxgWoxmnNBjFUMH2MXtZgoMW5MpkWTUaOJnq2WHZY9FsOieiyF2GcVS5qYhSVJONSSJsaz2MVYFrvQbEkWA1lcafmjkvznat+FfTnP7x9xEMzxTtE7aV6BJtq04/6C/YjdwoOFBYKcA5wxA3r3okls3iSal97H7M3w+frkx/TNy01IdOY5WVxCXm7fPvk+b4ZZ6V/74rJ3F87cdWX1mp4tx/XHFi56YMNli++55u4VP9+3jimNo4t41LEyHvP69r+8/OHrL4r/fCw3Dqhp6mCKR3TcHUj0kDuej1cmmSZFjI+sVWaZ5kTURlrjW4397abaHxgjuFS3wC4xH5iOxR1NVnvHDHT1dhfFjEguco+OqXKNcdfEXJRc415sXhx/lB9N0iiBRTsSE0clVCfMxUdCd/Qqbb3GNU1NcdsstIU/QszYtlG4EattW0C6SmOM3RrrViMTW43DMhwSxeIRXgHz4ybhkMSAo9X4WK4jh/CsmBWYv0sXO4SqiC7Z+UEHcyR7UGvJ8uWL8uk0b34vD/MkYO0FqoSihDzNKobQpNc1GQdapiWQmZ3f7msZFcKzQL2T393S71HS727p8QTpffi9Xye/w8n+EcLn+9GGGDg6T7TJSIC7j09CR+HBmAE9JxUcn1fA4PYBwvNsEqHHz+bNZ4lmeJ+cGuXlkjPOkp4gXM/SfV2k8y/YkvPN5q/aDrG4j99lUeyXA7bmq6euOP4hH23vP+H6pQ+zCYn3bWQepjA769q2u+0nTX9ySx279ZriugdFpoxFODSY3qFE1i2QFhfBol09Xb1cAddc1532uxwPO6zJjq6OoGubS3UJswaSPfmpVodij3bbWDz3x8Wq+CRvWxfH4oxYacPYgJoomURpzERpvsQsFYf91Uys+20tvfvnizLgd3vyVxFzBcTqdQUcWL0UJ3NmV5kzM8R6ppxwtsR6lgk0TlichLNFtID5YmN0tGSOPS3z6X1JrmfZFkqno8xGOCYe7bzg/H7kVORSueoO+g9OEkm1AGm18OAAJwxfvCQQpznNERaz1czNWkRMCjnN0SnYwvzZy5czP9bj/Dynt09en/x+fbEcEy3CDfHxefFeZ/O6dbHJVy46pyqlf+6Ykh07lLUr5s3KLzsv5k+2suopK365ECvv2rYZajpWXgylsTWBBXatu3aWVq6phXpQ5x69m92bmhufmzokda6+SrcOTByYcnbi2SmV1vPtVYlVKTOts+wztIsSZ6Vs09+J+yTpk+R30vbH7U/bqxt6glf1a/74PupArUw9W5uofR75dWqbFumMwsJzmy3MnOCOiqQoV/tqcrWnW5dIhR7hLVfmThvTbAFbta3Bpuoy2eoy2dpg50CkcIstKVw/Jjc0m1h/wiU2oU54wib2vj7CFbYFLDaP54XTayixhpJsFtE2xlax9SzIDjPVwwrZSMSoWJepwutME4MwTYzANDENJjMsJI5Kv0vRBDEcs4uhWIxYfMzlGdoviXVefcix8wtGaGIFfrdfO97RGlqByLaFB50DwtkWsjQv1pkXL1ybkBAfx0Xm7eJUOuXba+8fuLruup0zF+65bOLKHs4HFy1+9KEF9U1tM0zPNY4evcK4/b62n284Z+Dxn5X733jxtXdf2/6+WGeF2I+b4PdeSlMgNrRAkiS6JHZt90WXdsbXzmS1M5ntjLedyWhn0tsZXeyGywSnZsRlDIw4O6Ikc0JGbcbSiJsirsp8MPbRnOcVR0RiclJir/Kc9xJNKXw851ousyVVWasiqmxVkVX2KsdM68yImbaZkTPtMx0bfRu7RHfxZXbJ7NY3c6KtMnKab1rXBd4FmQ2ZN9vusq/uelvOrb3utz1sv6/L/V1bfC/5EuS7CG9ktDPediaznQm/r7n9FcztL2Vuf01sNq3G7kBM2oCJ1i5ZdpuarPvi1cgeqcmt/JFAhitHHgRcha6RrsmuJ107XOZol8c1x7XHpXpcK13c9RxyRTyym9xjAnFCXGMBxjW2k3FiGuNiz2mJS8iXe48W5cxnrEdV6uxUnuqOt6hiGuIhVWQYEXKCCcSKkFPdPSI9ySw50xWITcrPFY/3kTksKYQidl0JInZdunjSpYunXJp4K5fcJUQvfL+Fn08W48gmeSjNzIaip9wDdmazbDGmeB7MgY1CqWTE89ki8wkVYL7bJLRkJ8sZpGPHq87dlssLcxtyea7YRjNJToU0ebzUQ8bnMkjkG8lo8Yi56TIK9cxoudai5dyjdSGMs9ixgE9MITpKjB8tzzjRZnlOy9hDrJBGIq+5eod3vUnzRrSvPbHCkJL8B+efq+H4E8rD88Te17E60YltEGXhwXnYBeVy9WOdygK7If6wKSaGMnOgS/c0rykux+fUYrRYTTFnOPQUiuhqSWGm7oC0OFTTo7wplOF12K3dbCmsa5cIm9mvppBHS01h+NAhDtIhkMfobP/y5cupU7Jgk+Yjx59oEEKx/RJCy7+Lr0sP3ie/b79QekDul8k/LjEBdxqPjxNbta+wOfr6y5Yu7pN188t3jCzqn/3HsZc/N9EZtNfPWDozIaFnylVbb5sw4+XLd3zAznLPml9bcpY3KSt3+PJzhy7p6vEPu2x60piqMf287tRYW2Ze0dKqievOe0xkkEzjCM823YGd2rOZ7PjMIDwQ2RpmrO2MpZ0xtzM2EeZeX36EiJKxYBpcjJjdYWMKJWgR/mgbdgYlMlrLoAzmOClZ20LJ2s4Mi7U0orTaMtfSYFllUcmiW9ZbgpZtlp0Ws0XsAGLbtoR2AMkc2SjSuCV02g4z8tgk9g0Re2AOiw0FnFmenkSAywPUFj6Tkljfpgs7PghJzyB9HywQCbxA2/9dgTwrHy8QqduZl6e9Ks5MYdGsxNB5WWzTzn5OsTXHCQ9yLfmcgimzc666quWpp2L9XdPuWacNrr2XT13BLLPbblxx/OYROaHfqxRSmLhMioI0wSjJ9I/IbfSj1SArWY02iqAI4zjZyCb/rz0SaIdLjpODHMAoidEUBdQoGugE/oI93wmMpRhgHMUC44E/UwLFARMpHpgEPEYuSgSfTC7wKZQMdEtMpRRgGrmNn8gjUadUYDp5gBmkA73AHymT0oFZlAH0AX+gLuQFdkUc/UDdyAfMluinLsZRyqGuwO4Se1A2sCf5gb2oO7A38HvKpR7APOoJzKdexnfUR2Jf6g3sR3nA/pRv/JMGSBxIfYCDJBZQX+BZ1A84mPoDC2mAcYQCNBBYRIOAQ6gAWAz8lkroLGApDQaWYfc8TEMpABxGRcDhNAR4tsRyKgaeQyXAEfjce4jOlTiShgJH0TDgaBpufENjJI6ls4Hj8BnoII2nEcAJEs+jc4EVNNL4B1XSKOBE4EE6n0aDr6KxwEk0DniBxMk03viaqmkCsIbOA04B/p2mUiVwGk0E1tL5wAupyviKpkuso0nAGXSBcYBmUjX4WRJnUw3wIpqC9otpKnCOxLk0zfiS5lEtcD5NB9ZLXEB1xhe0kGYAF9FM4CXAz2kxzQIuoYuAl9LFwMskLqU5wMtpLvAKmmfsp2USG6geuJwWAP9ACw3x/9qLgFdJvJouMfbRNbQYeC0tAV5HlwKvp8uMT6mRlgJvoMvRsgL4Kd1IVwBvomXAlbQcuAq4l/5IfwCupiuBN9NVxh66ReKtdDVwDV0LvI2uQ+/twD10B10PXEuNxm66k24A3kUrgH+SeDfdBFxHK4HraRXwHuAndC/9EXgfrQbeTzcDH6BbjI/pQbrV+IgeojXADXQb8GGJj9DtwEfpDuBjdCfwcYlP0F3AJ+lPwCDdDWwCfkjNtA7YQuuBG+le4wN6iu4z/kabJD5N9wNb6QHgZnoQuEXiM7QB+Cw9bLxPz9EjwD9L3EqPArfRY8C/0OPA5+kJ4Av0pPEevUhB4EvUZLxLL0v8KzUDX6EWYxe9ShuB2+kp4Gu0Cfg6PQ18A5+CdtGbtBm4Q+JO2gJ8i54Fvk3PGe/QO8C3aRf9GfgubQW+R9uMt+h9iX+j54Ef0AvAD+lF4EcSP6aXgJ/Qy8Dd9FdjJ+2RuJdeNXbQp7QduI9eA34mcT+9Dvyc3gB+QW8Cv6Sdxpt0QOJX9Bbw7/S28QZ9Te8A/yHxIO0CfkPvGa/TIXofeFjit/Q34BH6APhP+hD4ncTv6WPjNTpKnwB/oN3AH4Hb6SfaAzxGe4E/06fAXyQep8+MV6mN9gMN+hz4n5z+P5/Tv/2d5/Svzzinf/UvcvpXp+X0A/8ip395Wk7/4gxy+v4TOX3+STn9s3+R0z+TOf2z03L6PpnT93XK6ftkTt8nc/q+Tjn909Ny+l6Z0/fKnL73d5jTP/j/lNN3/Sen/yen/+5y+u/9nP77zen/6pz+n5z+n5z+6zn9ld9/Tv8/7yjp0QplbmRzdHJlYW0KZW5kb2JqCjkgMCBvYmoKPDwvVHlwZSAvRm9udERlc2NyaXB0b3IKL0ZvbnROYW1lIC9BQUFBQUErQXJpYWxNVAovRmxhZ3MgNAovQXNjZW50IDkwNS4yNzM0NAovRGVzY2VudCAtMjExLjkxNDA2Ci9TdGVtViA0NS44OTg0MzgKL0NhcEhlaWdodCA3MTUuODIwMzEKL0l0YWxpY0FuZ2xlIDAKL0ZvbnRCQm94IFstNjY0LjU1MDc4IC0zMjQuNzA3MDMgMjAwMCAxMDA1Ljg1OTM4XQovRm9udEZpbGUyIDggMCBSPj4KZW5kb2JqCjEwIDAgb2JqCjw8L1R5cGUgL0ZvbnQKL0ZvbnREZXNjcmlwdG9yIDkgMCBSCi9CYXNlRm9udCAvQUFBQUFBK0FyaWFsTVQKL1N1YnR5cGUgL0NJREZvbnRUeXBlMgovQ0lEVG9HSURNYXAgL0lkZW50aXR5Ci9DSURTeXN0ZW1JbmZvIDw8L1JlZ2lzdHJ5IChBZG9iZSkKL09yZGVyaW5nIChJZGVudGl0eSkKL1N1cHBsZW1lbnQgMD4+Ci9XIFswIFs3NTAgMCAwIDI3Ny44MzIwM10gNTUgWzYxMC44Mzk4NF0gNzEgNzIgNTU2LjE1MjM0IDczIFsyNzcuODMyMDNdIDgzIFs1NTYuMTUyMzQgMCAwIDUwMCAyNzcuODMyMDNdXQovRFcgMD4+CmVuZG9iagoxMSAwIG9iago8PC9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggMjYyPj4gc3RyZWFtCnicXZHNasQgFIX3PsVdTheDTpKZoRACZUohi/7QtA9g9CYVGhVjFnn7+pOmUEHlcO539Cq9tY+tVh7omzOiQw+D0tLhbBYnEHoclSanAqQSflNpFRO3hAa4W2ePU6sHQ+oagL4Hd/ZuhcODND3eEfrqJDqlRzh83rqgu8Xab5xQe2CkaUDiEJKeuX3hEwJN2LGVwVd+PQbmr+JjtQhF0qd8G2EkzpYLdFyPSGoWRgP1UxgNQS3/+WWm+kF8cZeqy1DNWMGaqMprUucqqXP2riwlbUzxm7AfWGWouk/bZWMvOSl713KLyFC8V3y/vWmxOBf6TY+cGo0tKo37P1hjIxXnDxIJhhgKZW5kc3RyZWFtCmVuZG9iago0IDAgb2JqCjw8L1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUwCi9CYXNlRm9udCAvQUFBQUFBK0FyaWFsTVQKL0VuY29kaW5nIC9JZGVudGl0eS1ICi9EZXNjZW5kYW50Rm9udHMgWzEwIDAgUl0KL1RvVW5pY29kZSAxMSAwIFI+PgplbmRvYmoKeHJlZgowIDEyCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxNSAwMDAwMCBuIAowMDAwMDAwMzk3IDAwMDAwIG4gCjAwMDAwMDAxMDggMDAwMDAgbiAKMDAwMDAxMDgxMSAwMDAwMCBuIAowMDAwMDAwMTQ1IDAwMDAwIG4gCjAwMDAwMDA2MDUgMDAwMDAgbiAKMDAwMDAwMDY2MCAwMDAwMCBuIAowMDAwMDAwNzA3IDAwMDAwIG4gCjAwMDAwMDk5MzQgMDAwMDAgbiAKMDAwMDAxMDE2OCAwMDAwMCBuIAowMDAwMDEwNDc4IDAwMDAwIG4gCnRyYWlsZXIKPDwvU2l6ZSAxMgovUm9vdCA3IDAgUgovSW5mbyAxIDAgUj4+CnN0YXJ0eHJlZgoxMDk1MAolJUVPRg==",
                                "contentType": "application/pdf"
                            }
                        ],
                        "effectiveDateTime": "2024-02-25T15:10:56.296677",
                        "code": {
                            "coding": []
                        }
                    }
                },
                {
                    "name": "labTestCollection",
                    "part": [
                        {
                            "name": "labTest",
                            "resource": {
                                "resourceType": "Observation",
                                "code": {
                                    "text": "Hepatic Function Panel (7)",
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "24325-3",
                                            "display": "Hepatic Function Panel (7)"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "status": "final"
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "2885-2",
                                            "display": "Protein, Total"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "value": 9.6,
                                    "unit": "g/dL",
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 6.0
                                        },
                                        "high": {
                                            "value": 8.5
                                        },
                                        "text": "6.0-8.5"
                                    }
                                ],
                                "interpretation": [
                                    {
                                        "text": "Abnormal",
                                        "coding": [
                                            {
                                                "code": "A",
                                                "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
                                                "display": "Abnormal"
                                            }
                                        ]
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "coding": [
                                        {
                                            "code": "1751-7",
                                            "system": "http://loinc.org",
                                            "display": "Albumin"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "g/dL",
                                    "value": 3.8,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 3.6
                                        },
                                        "high": {
                                            "value": 4.6
                                        },
                                        "text": "3.6-4.6"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "text": "Bilirubin, Total",
                                    "coding": [
                                        {
                                            "code": "1975-2",
                                            "system": "http://loinc.org",
                                            "display": "Bilirubin, Total"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "mg/dL",
                                    "value": 0.3,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 0.0
                                        },
                                        "high": {
                                            "value": 1.2
                                        },
                                        "text": "0.0-1.2"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "text": "Alkaline Phosphatase",
                                    "coding": [
                                        {
                                            "code": "6768-6",
                                            "system": "http://loinc.org",
                                            "display": "Alkaline Phosphatase"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "IU/L",
                                    "value": 83.6,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 44.0
                                        },
                                        "high": {
                                            "value": 121.0
                                        },
                                        "text": "44-121"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "text": "AST (SGOT)",
                                    "coding": [
                                        {
                                            "code": "1920-8",
                                            "system": "http://loinc.org",
                                            "display": "AST (SGOT)"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "IU/L",
                                    "value": 19.4,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 0.0
                                        },
                                        "high": {
                                            "value": 40.0
                                        },
                                        "text": "0-40"
                                    }
                                ]
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "text": "ALT (SGPT)",
                                    "coding": [
                                        {
                                            "code": "1742-6",
                                            "system": "http://loinc.org",
                                            "display": "ALT (SGPT)"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-01-11T17:37:30.756832+00:00",
                                "valueQuantity": {
                                    "unit": "IU/L",
                                    "value": 13.5,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 0.0
                                        },
                                        "high": {
                                            "value": 44.0
                                        },
                                        "text": "0-44"
                                    }
                                ]
                            }
                        }
                    ]
                },
                {
                    "name": "labTestCollection",
                    "part": [
                        {
                            "name": "labTest",
                            "resource": {
                                "resourceType": "Observation",
                                "code": {
                                    "text": "Vitamin D, 25-Hydroxy",
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "62292-8",
                                            "display": "Vitamin D, 25-Hydroxy"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-02-25T15:10:56.296677",
                                "status": "final"
                            }
                        },
                        {
                            "name": "labValue",
                            "resource": {
                                "resourceType": "Observation",
                                "status": "final",
                                "code": {
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "62292-8",
                                            "display": "Vitamin D, 25-Hydroxy"
                                        }
                                    ]
                                },
                                "effectiveDateTime": "2024-02-25T15:10:56.296677",
                                "valueQuantity": {
                                    "unit": "ng/mL",
                                    "value": 41.0,
                                    "system": "http://unitsofmeasure.org"
                                },
                                "referenceRange": [
                                    {
                                        "low": {
                                            "value": 30.0
                                        },
                                        "high": {
                                            "value": 100.0
                                        },
                                        "text": "30.0-100.0"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
        ```
  - **Only report data (no tests or values)**
        ```json
        {
            "resourceType": "Parameters",
            "parameter": [
                {
                    "name": "labReport",
                    "resource": {
                        "resourceType": "DiagnosticReport",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v2-0074",
                                        "code": "LAB",
                                        "display": "Laboratory"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/4cc6fd69f81042a0b6d123e2080a7c1a",
                            "type": "Patient"
                        },
                        "presentedForm": [
                            {
                                "data": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoVW50aXRsZWQgZG9jdW1lbnQpCi9Qcm9kdWNlciAoU2tpYS9QREYgbTEwNCBHb29nbGUgRG9jcyBSZW5kZXJlcik+PgplbmRvYmoKMyAwIG9iago8PC9jYSAxCi9CTSAvTm9ybWFsPj4KZW5kb2JqCjUgMCBvYmoKPDwvRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDE4Mj4+IHN0cmVhbQp4nHWQ0QrCMAxF3/MV+QG7pmmaFsQHQfes9A/UDYQ9OP8fbDfdQFhTmnIP9zaU0JbaUTk0ObwN8AKjMqm/XkTCWtcW58vYQ9My9m+oPFJAshJwfEAHl78EdXWXjK/jmKE5eyRvQl2KuQNapzBeUyTlhHmAqrFxquw5Yr7j3lrWA+YnqGEXUhAunhn4OIFoSIisxgVIWByRnKz6nOSNVUoqugDLG0B44wmvWyBN4JTLv3wAWrRKswplbmRzdHJlYW0KZW5kb2JqCjIgMCBvYmoKPDwvVHlwZSAvUGFnZQovUmVzb3VyY2VzIDw8L1Byb2NTZXQgWy9QREYgL1RleHQgL0ltYWdlQiAvSW1hZ2VDIC9JbWFnZUldCi9FeHRHU3RhdGUgPDwvRzMgMyAwIFI+PgovRm9udCA8PC9GNCA0IDAgUj4+Pj4KL01lZGlhQm94IFswIDAgNjEyIDc5Ml0KL0NvbnRlbnRzIDUgMCBSCi9TdHJ1Y3RQYXJlbnRzIDAKL1BhcmVudCA2IDAgUj4+CmVuZG9iago2IDAgb2JqCjw8L1R5cGUgL1BhZ2VzCi9Db3VudCAxCi9LaWRzIFsyIDAgUl0+PgplbmRvYmoKNyAwIG9iago8PC9UeXBlIC9DYXRhbG9nCi9QYWdlcyA2IDAgUj4+CmVuZG9iago4IDAgb2JqCjw8L0xlbmd0aDEgMTg0MjgKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCA5MTQxPj4gc3RyZWFtCnic7XoJeFRF1vapureXdLqT29k76aRv0kkD6bAlYY+kQxbAiOyYYJAEiIRFWQIIihLGPaIwqKjoCO64dxLEgDowbqO4gIo6boCIiuMgyCgqSu7/VnWHBHC+n/H/vu9/fJ65N+etU1Xnnqp7zqlT1d0hRkSxAJV6DS0pLWOFLI+I7UVr/tBRI8deMWV9IpFiRf2uoWPHD7H92bIC/UHUe40c2zN3ccLTLiK+AfXqCSUjKkatnvk9Ud86IuctUy+qmctXsLvRfw76q6YuWqDf437/ayLzL6BxF86dftHrSyrXEjlGoX7x9Jr6uZREEdBfAHlt+uwlF046+GkrUdeuRFGD66ZdtPiF63+4ARPeRmTdUFdbM21v3MvQx+NIDIqGmLyIdDyPOVJm3UULFmd8yf9MZLoLbdWz50ytydqe/hbe5370N19Us3iuqcXRgD4xP/3imotqE6t7fwJjVKCtZO6c+gVGNq0BP1v0z51fOzfrvRFbidx4v0joJYWsxMlJzDDAC1tW0BEqoD+RBe0a9aQJ0PYYZE2oKyQvo4vQ+SsXnrcMbjuXijU69uSxSzXZctJVIVts1AO3qWZ+zRTSpy6ZP5v06fNrZ5FeVztlPumzaxZcTHqHTrKHeU7mcJsiZ9sPN6OhNBw4FjfDbM8DimdMrrWPttz61uTogu+tKVb52L2fdckW5WujBm069uTx6RpZheaITrPk0iZEcWFrxCGuhqGMknYyY1bj6EKaSwtoPSxGsj4N9XpRNz47cU897c0V5Tq2Cla0mtaaRISmhErlLbqQx1hNPNKscnGp4RmcuEaMPHckBTDSetM7baNZnmUwaw4Ih2F81Wd6Rs5CDdt1CFWRIi2aE7KotKV4C+E3A1K8E8868Rh1Vu18yHbGsP2FHIcFmCSNQnPsgXGTw77oJ30w3PhI1IDDjFSaAIKPUPvfvpb/1zdbxW9VRpx+q8PFbZ5p8UgtFpoookDFeqaZ1BDmGay8KMxzxEVdmFfgo65hXu0kY4KNosK8GRxREc2nGVRDs2kEomcC1aJej5Y5JKK+D+zam3qhf4RsmYNYW4IIq0XfcLoI7dMhezFQp+6gDm06jYHUdFoIvgatJ9c65B6GZC5G6I1bxG+d1H36aMWozQcvsAbtoRn2kGPODo83AyPUoa8+PHq9fJtFwGnUw9x5YQ34X4+C/9FL/QwW/H95vp7KQOWwS+wZyl97gicqxHOZpi3kAiWbHiKX6sPOQ8aXoAOibJthHBD9ouR/x0OtYSLaQI+zGfQ4baXn2WE89SRtpo30CiVSCd1FS+kWjGRG7L9C18OnYxDBJXQLcxkbsRvcg0i+h96A7Hl0BW2hBJZkfEXL6GrlHTx1NTkoA9ExCpFyIzvHWIhstEe9EtnhHETOXNZgVBg3GauN++kB2qy8YhynSKyOqbjfML4x/c34GBFdRbfSHbSHrY54CivqPKy7zcqfEFNrlUkqM6YbxzCDdLoEc1ARs2+wbdwP7bX0JUtiS5ViaLnPCBovQspNkxCba2kL68OG8nRTlTHCeIMSMMZiaL2DmmkT7lZ6jj5kdtNh437jMLkoB6tsGezxJtumtB1f3lYIi5lgpW40AD1z6M/0V9rJvOwvfI7Jbso1BUyXGruQKXvTeMz2ITz5BfuBX4F7mfKyWmYMwZq/mv4orE0v0acsmfVkI9kE3o3P4Xcr85FRc+RKnIa1dD3dDu27mZ9t4na+Q7lPfVT92ZzatteIgkd8dCf25b8wB95UZ/XsD+w99hkv5pP5nXyfcov6sPq2pQZvfQGyxI30KP3AYlh/Npqdz+rYUnYt+yO7g73BdrIDvIiP47P4IaVOmac8pw7BPVatV680XWO6wXygraLtxba32n4wco1raDTiYTlmfyvdjTfbTDvoA9x7aB8zsUgWhVtn6Ww8uwz3FexGdi/bwB5mGzHKTraPfcWOsO/ZzxyJkpt5Ck/nGbi9fD6/hN/C7+I7cO/k/+A/KYlKhuJX+igFSqUyB7O6VlmF+ynlUzVZ3aEasHOuaY1pnWmD6VHT86bDZrvlD1ayvv7Lfcezj+9uo7br2ta0NbdtND6lePgwGVbw4BQzGnmrBrl7Mc4rDyDO32F22C6ZZbPB7BxYZjKbyeaxxbDkVWwte0DO/Qn2LKz0PjuEOTu4W865B+/Dh/CRuC/gtXweX8VX8438PX5MsSiRSrQSr2QrQ5VJSq2yQFmirFGCyuvKJ8o+5ajyC25DtakeNUP1qX51qDpZXajerX6pfmmqMr1m+txsM19kvsbcav7W0tcy2DLKMtoyybLSssmyy1qN6HyBnqKnO+cBtldZrpQqT9FNPE918Tf5m4jnyTRNGcELxTmWXccvZxt5pmmxeRAfxM6lw6oPtn6Zr+NH+SBlBCtnY2km7x3SZo5TH0FRoL5AB9Vn8W5vQvNis51dwQ+Z7dTMZN5mLym9VL/yGn2o7GEW9R76SLWxRHaQP6SMQhQ8pw42VVC6chc9ocxjl9NTvBRHkZ+tKxDH57JHkBfGsVz2o4ITJj8XUdRP+YyupFn8b3QQ6/g6uo1NU6fTTZTHltKX9CBWRTfTxeZsczx7lc9QG3ks20hcfVjsISyTKaY4uopNUtaaD/EPsLvtUG20W3kMs9/Bn8Aeftg0htVhBVxO19A8YzktMVWob7PppLAJlKXuRXZbquSq6SiXIatUIadtwuregjxQpIxASxIi5xzExXhkiLW4b0eeUBFBM7DGz0MWe5M2msfxVppuimLIOsjGr7WNoYnGg3SHMZ0uNlZTd+SDa42l0LiBPqeVtIFd3XYZ9tE0rJzd7BxTGd9hKjO680b+AR/L15zsX1g7iyXR33E/gcpgnO8a1fdxti00VhjvIrq7IsPeQVPobNqPt/wGIwxTtlFe27m8yShT5uJ999Bo4yHDw2xUZ8ymkfQsPWAxUY3FDx8H2dt438uolo8xFii1bTNgh5WwQgDWWoj8c32gePy4okDh4LMKBg0c0L9fn/y83N69evbonuPP7ta1iy8r05uRrnvSUt0pya6kxIT4uNgYpxYd5bBH2iKsFrNJVTijnFJvWbUe9FUHVZ932LDuou6tQUNNp4bqoI6mspNlgnq1FNNPlgxA8sJTJAMhycAJSabpBVTQPUcv9erBN0q8eiubOLoC/I0l3ko9eFDyIyS/SvIO8OnpeEAvTaor0YOsWi8Nli2qayytLoG6pkhbsbe41tY9h5pskWAjwQUTvXObWOJgJhmeWDqwCSdjByYVTPaWlAZd3hIxg6CSVVozLThqdEVpSUp6emX3nCArnuqdEiTvkGC0X4pQsRwmaC4OWuQw+gzxNnSD3pSzrXFFq0ZTqv32ad5pNVUVQaWmUozh9GPckmDipfuTOqpQHlNccW3n3hSlsTRphi6qjY3X6sH1oys696YLrKyEDjzLs8qqG8sw9AoYsXysjtH41ZUVQXY1htTFm4i3Cr1frbdUtFTP1IMR3iHeusaZ1XBNcmOQxixJb05ODmw29lJyqd44rsKbHixM8VbWlLib4qhxzJIWV0B3ndzTPadJc4YM2xQVHWbsjs5M7Yk+yUlxwZWPOWFZJmbkHY6ACOpTdcykwot36i+gtj81Tu0PMVyVDE8Fp8EjM4IRxdWN2kDRLp4PmrI0r974PSECvAf/cXJLTbjFnKV9T4IVcXIi1NDfzgf9/mB2tggRSzF8ijkOlvU+3XMWtXKvd66mo4D5aBRsW1M5sCfMn54uHHxDa4CmoBJsGF0Rqus0JaWZAj39lUFeLXq2tffEjxc9De09Jx6v9iKSN8oTd3zQ6jvxF60lxJbWDQyyhP+iuzbUXz7WWz56YoVe2lgdtm35uJNqof7+J/rCXDC2uEJJ4WGOpyiyF0FZdUJYVCrsQTULf2YZ1NNaLVZEpWxhellQqx4WwkpbevoZPtRqHBZPyaLjsfA0gwP9J9cHnVQ/aXr2RgUTxlZZPm5iY6PtpD6EWmjA4eECEU/jKtL14iCNx8rMwl+rsa2/oMqUYAAmKxYCiL9QU7h6kmBKmK/EJaKze04ZEl1jY5lXL2usbqxpNRqmeHXN27iZP8+fb5xbWt0eOK3GlhtSgmUrKmGrOjYQi4LTkCYvu250U4BdN3ZixWaNSL9uXEUzZ7y4ekhlUyb6KjbrRAHZykWraBQVXVSonOElm7lVyqdsDhA1yF5VNsj61FZGss3a3sZoaisPtWntbRxtaqgtINvEJXJM8biKztEjl2Rld7nh4XMLVUVarad873GGl/nUulnt3GeGTntExG/TbTm1blE694maw2YjUunfv/5vuqEzOjLyt+mOOKVutXZogZlFTbPb/3t0R0SonfuEbqfDIT4z/XfoNnXuE7pjo6J+m277KfXIyI7IgZlt0BmvaafH02/SbT9JtxgpKSbmdJ+fyRV1at1h6dxnRy0lLk769d++tFPq0dEduqOhHjpTExJ+m+5Tv9XQtA4tGDcaNT0p6XSf/xbdTqetg4d66Ex3uX6b7vhT6jGddMOFTujMcrvFd63//pV46lhxHVowbgxq2bp+ejydyZV86liJjs7jxkFnD68XCes36HafOlZyR1RiXDFSrs93eqyeyeU5dSx3hxaM60Ktb7duMh7/7Sv9lHpaWoeWNKwb1Abm5Jy+Ds7kyjylrusdWnSsG9SKc3NPj9UzubqdUs/K6tCSRZSBWnn//qfH6plc3U+pZ2d3aMkm8qE2dvDg02P1TK78U+o9eiR18FAPnVWlpafH6plcp35/nJeX0sFDPXROKy8/PVbP5Bp8Sr1//9QOHrENnZtpnNK1xZfk2fms0o32grjSrdmf6tmsdFFSmwd5Aq2KtyUmPje6qLui42zUU6IOnAN6ErRVEb/TTFbSxG8owGWgBtCToK2gnSDsFEDRq4PmgNaB9ooeJVVxN+seraiL4sKzLpy1opVEOgQyQAp5gD1BI0GTQStB60BmKSda5oCWgbaCDsuegJLYvDoPc09svkEWLTNn58pqTahaNUlWW86rDJUjRofKkuEhsYEhsd75oeYeQ0Jll5xQGZOV2yBKmyN3W1GCkoCXTMDE5wIZf5GiGUMCWK/EUxDEFXO4JaDEtGT6ctdtVVRiClcYTSOPsU1hzQ5nbpGNG/wQkrGHf8MPhnr4wZYoZ+66orP5PnoStBWk8H24P+Wf0jK+V9gcWAhaB9oK2gE6BDLzvbj34N7Nd1M0/4R6ggpBk0HrQFtBh0AW/glQ4x+Lz1ESBV8I4vxjoMY/wmt9BIzmH4L7kH+Iqb3T3G9A7mbJ+HuGGU9WmElMCTMxCbmt/O3mn7ohonzwNCLqGSUDoZmnZDRn9fa0KknNBTM8rfyzFt3vWV/Ui++iIIhjJrsw8i7SQaNA1aC5IDO498C9Rw2gVaD1oCAIUQbUQDrfDnod9B71AgVAo0BWvrMZw7TyHc2+IZ6iBP4m/ytSgoe/wV+R5ev8ZVm+xl+S5aso01Bu5y83p3moKBL9hGc0lBrKnug38b+0ZMZ4jCIn3wrbeYA9QYWgkaDJoJUgM9/KM5qneWKg5BnajoOChzfTV7J8kO61UmCmJ+ArRgDqAnwDzwIHWKev8/GAb80dqArw3bQanADfVSvACfBduhycAN/sReAE+KbNBCfAN3EyOAG+kePAAVr53U9ndvH0GzmL6UXR/BJY6RJY6RJY6RJS+SXipp9UMbc7m7OzYbG1AX+3bE/DFtbwLGsYwxruZQ21rOEK1rCcNRSwhgtYg581uFlDGmsIsIZnWH+YooEFNp5UHRBIYg3bWcPjrKGeNfhYQxZryGQNOusXaOXpzcPzZFEqi5YisehQnjUY2Seap8Oi6Yj5dOSErcAdIEPWAhDSM0LCrjRRZrRkF4bqPQbmzikaxl/Agy/ADS/QHpAKB72AMHoBSl6AgmhgIWgyaBvoEMgAmSGdgYmvlBgN7AkqBE0GLQMdApnldA6BOM0JT/FJObGe4UmPFDX+Am7xQ0E6Tw+kam7Nrw1TVrpZdBobmWak8X4kzqQ4mFmdrcyx6QfHjz84KKIogt/EV1IqHLEqXK5s/inV08pub/Y94ymKZ7dRmoqoYwPIx7JQ9qd6We9Dbqso88nNH0WZ2+yegMeim305ni0sSjy1yfOTe7/nK3crB3vA/Yznfb1VZc2ed9Hy6CbPLvf1nld7tlrR8qyvlaHYokvRze7+nse3S9Hl6Fjb7LlCFJs8l7uHema5ZUdtqOOCetQC0Z4xvomeYdBX4p7iCdRD5yZPofsCT0FIqo94ZpOnF6bgD7HZmGw3txzUmyYVju/XyuoCOZY1lgrLSEtfS64lx5Ju8VhSLSmWOGuMVbNGWe1Wm9VqNVtVK7eSNa7V2Bvwi9/548zynzbEZ2hGquQ1TvLfBuS/AnBm5XQ2BWOVcl4+dggrD26bSuVT9ODRsd5WZhs9MWjyDmHBmHIqHzck2N9f3moxxgT7+cuDllHnVzQxdlMlWoP8ulZG4ypamSGark4R319uJsacV9+YIsquV99YWUlJCYsKkwpjBjsHlJX8ClSH0d9xJZ3EpwbXlI+tCD6SWhnMFYyRWlkevFl8wbmZHWGHS0s2s29FUVmxWRnMjpSOEe3K4JLKyvJWNkHKkc6+hRwi5lspZ8XGLORIt6aF5NaG5LLwPOQyRQG5iAjKknJZERFSTmVCrqk+s7SkKTNTyiTqVC9l6hP1zjLbsyCTlSVlEhpou5TZntAgZIKDpYjbDZE0txRhyeSWIm6WLEUmdIj0DItcf0LkejmSwjpk3CEZx952GcdeyPjP9Kod4vezlkGVU6vEl8PV3tJaUHXwhkV1ScGGKbreNLUy/K2xr3rK1DpR1tQGK721JcGp3hK9aVDVr3RXie5B3pImnBfHVTRVBWpLmgcFBpV6a0oqW4aOyu930ljXnxgrf9SvKBsllOWLsYb2+5XufqJ7qBirnxirnxhraGCoHItkjI+qaLLSkMriqlDZwiNtiNfqlPTKIQna3MEyeAelJ12RsgWnlQ0U6a8M2r1Dgg6Q6Ope1L1IdGFNia4o8QtAuCvpikHpKVvYhnCXhmandwj5FyysX0hJpTNKQn/1uNC0YKEweAj99f/qQl9pMFBTUr8AnxKC2WPLg4WjJ1Y0WSxorRavFBzY3hYZWdpqbAs19kDjQNGoKCcERVuBaIuICAue7v+F4bJYrIIG/kwLC6SxBVRfqQTTysdxpIJx4a9at+AsJbaH+kq8YD3zs/p2HeFp+/0UqpN453ZasDDMhW2xIFyGnsQj9e0mOXEJY/lPWGwBFIrk1YtI3WLaQhbaHXCZud0+ZLxFotkSGQleIms1ftooGAITcArObLI70C0R3T9vFAy6fw44BWfiaarCSf74FdHK61t0lanIx0+bdcZ7KkwB/xRj4tNAq3EgEKlpfDxZo6O50HFko90umX0bHQ7J/IIWs2Da0CIYaLRuuiPJrx0NvdykAu070PH9k77QCrQCKiwsOF7QuxfreP10Z3qf9Ph0J49tS1Ub21JMjscfP/ZPpPAy44CyBxZwUirbGlhq46ojy5HvKHGY+sT1cZ/Hx9nGxI11T+fTTLURU+Oq3ds8u0zvxn7i+jz287hDiV+7Pk/d6zE8CR6PP7kgoSC5PHmuZ5XH0oNnOnokDOR9HOW81FEWN9x9nm2CY7rjc/OXCcfYd1Eai1eiIrVoSnFHWpxki3crkUmtxo94vyHjBfO0cEJSnrDPkael7bOc0e0CYL7bKATAHAl0Ed3RWZq208k0Z8BZ7Wxwqp5AZCQf7wkICzpjhH2deCjgFDZ2mqOigEmyT2iIjIw0j3dGaZpZ1L+R1naGBgsxgWoxmnNBjFUMH2MXtZgoMW5MpkWTUaOJnq2WHZY9FsOieiyF2GcVS5qYhSVJONSSJsaz2MVYFrvQbEkWA1lcafmjkvznat+FfTnP7x9xEMzxTtE7aV6BJtq04/6C/YjdwoOFBYKcA5wxA3r3okls3iSal97H7M3w+frkx/TNy01IdOY5WVxCXm7fPvk+b4ZZ6V/74rJ3F87cdWX1mp4tx/XHFi56YMNli++55u4VP9+3jimNo4t41LEyHvP69r+8/OHrL4r/fCw3Dqhp6mCKR3TcHUj0kDuej1cmmSZFjI+sVWaZ5kTURlrjW4397abaHxgjuFS3wC4xH5iOxR1NVnvHDHT1dhfFjEguco+OqXKNcdfEXJRc415sXhx/lB9N0iiBRTsSE0clVCfMxUdCd/Qqbb3GNU1NcdsstIU/QszYtlG4EattW0C6SmOM3RrrViMTW43DMhwSxeIRXgHz4ybhkMSAo9X4WK4jh/CsmBWYv0sXO4SqiC7Z+UEHcyR7UGvJ8uWL8uk0b34vD/MkYO0FqoSihDzNKobQpNc1GQdapiWQmZ3f7msZFcKzQL2T393S71HS727p8QTpffi9Xye/w8n+EcLn+9GGGDg6T7TJSIC7j09CR+HBmAE9JxUcn1fA4PYBwvNsEqHHz+bNZ4lmeJ+cGuXlkjPOkp4gXM/SfV2k8y/YkvPN5q/aDrG4j99lUeyXA7bmq6euOP4hH23vP+H6pQ+zCYn3bWQepjA769q2u+0nTX9ySx279ZriugdFpoxFODSY3qFE1i2QFhfBol09Xb1cAddc1532uxwPO6zJjq6OoGubS3UJswaSPfmpVodij3bbWDz3x8Wq+CRvWxfH4oxYacPYgJoomURpzERpvsQsFYf91Uys+20tvfvnizLgd3vyVxFzBcTqdQUcWL0UJ3NmV5kzM8R6ppxwtsR6lgk0TlichLNFtID5YmN0tGSOPS3z6X1JrmfZFkqno8xGOCYe7bzg/H7kVORSueoO+g9OEkm1AGm18OAAJwxfvCQQpznNERaz1czNWkRMCjnN0SnYwvzZy5czP9bj/Dynt09en/x+fbEcEy3CDfHxefFeZ/O6dbHJVy46pyqlf+6Ykh07lLUr5s3KLzsv5k+2suopK365ECvv2rYZajpWXgylsTWBBXatu3aWVq6phXpQ5x69m92bmhufmzokda6+SrcOTByYcnbi2SmV1vPtVYlVKTOts+wztIsSZ6Vs09+J+yTpk+R30vbH7U/bqxt6glf1a/74PupArUw9W5uofR75dWqbFumMwsJzmy3MnOCOiqQoV/tqcrWnW5dIhR7hLVfmThvTbAFbta3Bpuoy2eoy2dpg50CkcIstKVw/Jjc0m1h/wiU2oU54wib2vj7CFbYFLDaP54XTayixhpJsFtE2xlax9SzIDjPVwwrZSMSoWJepwutME4MwTYzANDENJjMsJI5Kv0vRBDEcs4uhWIxYfMzlGdoviXVefcix8wtGaGIFfrdfO97RGlqByLaFB50DwtkWsjQv1pkXL1ybkBAfx0Xm7eJUOuXba+8fuLruup0zF+65bOLKHs4HFy1+9KEF9U1tM0zPNY4evcK4/b62n284Z+Dxn5X733jxtXdf2/6+WGeF2I+b4PdeSlMgNrRAkiS6JHZt90WXdsbXzmS1M5ntjLedyWhn0tsZXeyGywSnZsRlDIw4O6Ikc0JGbcbSiJsirsp8MPbRnOcVR0RiclJir/Kc9xJNKXw851ousyVVWasiqmxVkVX2KsdM68yImbaZkTPtMx0bfRu7RHfxZXbJ7NY3c6KtMnKab1rXBd4FmQ2ZN9vusq/uelvOrb3utz1sv6/L/V1bfC/5EuS7CG9ktDPediaznQm/r7n9FcztL2Vuf01sNq3G7kBM2oCJ1i5ZdpuarPvi1cgeqcmt/JFAhitHHgRcha6RrsmuJ107XOZol8c1x7XHpXpcK13c9RxyRTyym9xjAnFCXGMBxjW2k3FiGuNiz2mJS8iXe48W5cxnrEdV6uxUnuqOt6hiGuIhVWQYEXKCCcSKkFPdPSI9ySw50xWITcrPFY/3kTksKYQidl0JInZdunjSpYunXJp4K5fcJUQvfL+Fn08W48gmeSjNzIaip9wDdmazbDGmeB7MgY1CqWTE89ki8wkVYL7bJLRkJ8sZpGPHq87dlssLcxtyea7YRjNJToU0ebzUQ8bnMkjkG8lo8Yi56TIK9cxoudai5dyjdSGMs9ixgE9MITpKjB8tzzjRZnlOy9hDrJBGIq+5eod3vUnzRrSvPbHCkJL8B+efq+H4E8rD88Te17E60YltEGXhwXnYBeVy9WOdygK7If6wKSaGMnOgS/c0rykux+fUYrRYTTFnOPQUiuhqSWGm7oC0OFTTo7wplOF12K3dbCmsa5cIm9mvppBHS01h+NAhDtIhkMfobP/y5cupU7Jgk+Yjx59oEEKx/RJCy7+Lr0sP3ie/b79QekDul8k/LjEBdxqPjxNbta+wOfr6y5Yu7pN188t3jCzqn/3HsZc/N9EZtNfPWDozIaFnylVbb5sw4+XLd3zAznLPml9bcpY3KSt3+PJzhy7p6vEPu2x60piqMf287tRYW2Ze0dKqievOe0xkkEzjCM823YGd2rOZ7PjMIDwQ2RpmrO2MpZ0xtzM2EeZeX36EiJKxYBpcjJjdYWMKJWgR/mgbdgYlMlrLoAzmOClZ20LJ2s4Mi7U0orTaMtfSYFllUcmiW9ZbgpZtlp0Ws0XsAGLbtoR2AMkc2SjSuCV02g4z8tgk9g0Re2AOiw0FnFmenkSAywPUFj6Tkljfpgs7PghJzyB9HywQCbxA2/9dgTwrHy8QqduZl6e9Ks5MYdGsxNB5WWzTzn5OsTXHCQ9yLfmcgimzc666quWpp2L9XdPuWacNrr2XT13BLLPbblxx/OYROaHfqxRSmLhMioI0wSjJ9I/IbfSj1SArWY02iqAI4zjZyCb/rz0SaIdLjpODHMAoidEUBdQoGugE/oI93wmMpRhgHMUC44E/UwLFARMpHpgEPEYuSgSfTC7wKZQMdEtMpRRgGrmNn8gjUadUYDp5gBmkA73AHymT0oFZlAH0AX+gLuQFdkUc/UDdyAfMluinLsZRyqGuwO4Se1A2sCf5gb2oO7A38HvKpR7APOoJzKdexnfUR2Jf6g3sR3nA/pRv/JMGSBxIfYCDJBZQX+BZ1A84mPoDC2mAcYQCNBBYRIOAQ6gAWAz8lkroLGApDQaWYfc8TEMpABxGRcDhNAR4tsRyKgaeQyXAEfjce4jOlTiShgJH0TDgaBpufENjJI6ls4Hj8BnoII2nEcAJEs+jc4EVNNL4B1XSKOBE4EE6n0aDr6KxwEk0DniBxMk03viaqmkCsIbOA04B/p2mUiVwGk0E1tL5wAupyviKpkuso0nAGXSBcYBmUjX4WRJnUw3wIpqC9otpKnCOxLk0zfiS5lEtcD5NB9ZLXEB1xhe0kGYAF9FM4CXAz2kxzQIuoYuAl9LFwMskLqU5wMtpLvAKmmfsp2USG6geuJwWAP9ACw3x/9qLgFdJvJouMfbRNbQYeC0tAV5HlwKvp8uMT6mRlgJvoMvRsgL4Kd1IVwBvomXAlbQcuAq4l/5IfwCupiuBN9NVxh66ReKtdDVwDV0LvI2uQ+/twD10B10PXEuNxm66k24A3kUrgH+SeDfdBFxHK4HraRXwHuAndC/9EXgfrQbeTzcDH6BbjI/pQbrV+IgeojXADXQb8GGJj9DtwEfpDuBjdCfwcYlP0F3AJ+lPwCDdDWwCfkjNtA7YQuuBG+le4wN6iu4z/kabJD5N9wNb6QHgZnoQuEXiM7QB+Cw9bLxPz9EjwD9L3EqPArfRY8C/0OPA5+kJ4Av0pPEevUhB4EvUZLxLL0v8KzUDX6EWYxe9ShuB2+kp4Gu0Cfg6PQ18A5+CdtGbtBm4Q+JO2gJ8i54Fvk3PGe/QO8C3aRf9GfgubQW+R9uMt+h9iX+j54Ef0AvAD+lF4EcSP6aXgJ/Qy8Dd9FdjJ+2RuJdeNXbQp7QduI9eA34mcT+9Dvyc3gB+QW8Cv6Sdxpt0QOJX9Bbw7/S28QZ9Te8A/yHxIO0CfkPvGa/TIXofeFjit/Q34BH6APhP+hD4ncTv6WPjNTpKnwB/oN3AH4Hb6SfaAzxGe4E/06fAXyQep8+MV6mN9gMN+hz4n5z+P5/Tv/2d5/Svzzinf/UvcvpXp+X0A/8ip395Wk7/4gxy+v4TOX3+STn9s3+R0z+TOf2z03L6PpnT93XK6ftkTt8nc/q+Tjn909Ny+l6Z0/fKnL73d5jTP/j/lNN3/Sen/yen/+5y+u/9nP77zen/6pz+n5z+n5z+6zn9ld9/Tv8/7yjp0QplbmRzdHJlYW0KZW5kb2JqCjkgMCBvYmoKPDwvVHlwZSAvRm9udERlc2NyaXB0b3IKL0ZvbnROYW1lIC9BQUFBQUErQXJpYWxNVAovRmxhZ3MgNAovQXNjZW50IDkwNS4yNzM0NAovRGVzY2VudCAtMjExLjkxNDA2Ci9TdGVtViA0NS44OTg0MzgKL0NhcEhlaWdodCA3MTUuODIwMzEKL0l0YWxpY0FuZ2xlIDAKL0ZvbnRCQm94IFstNjY0LjU1MDc4IC0zMjQuNzA3MDMgMjAwMCAxMDA1Ljg1OTM4XQovRm9udEZpbGUyIDggMCBSPj4KZW5kb2JqCjEwIDAgb2JqCjw8L1R5cGUgL0ZvbnQKL0ZvbnREZXNjcmlwdG9yIDkgMCBSCi9CYXNlRm9udCAvQUFBQUFBK0FyaWFsTVQKL1N1YnR5cGUgL0NJREZvbnRUeXBlMgovQ0lEVG9HSURNYXAgL0lkZW50aXR5Ci9DSURTeXN0ZW1JbmZvIDw8L1JlZ2lzdHJ5IChBZG9iZSkKL09yZGVyaW5nIChJZGVudGl0eSkKL1N1cHBsZW1lbnQgMD4+Ci9XIFswIFs3NTAgMCAwIDI3Ny44MzIwM10gNTUgWzYxMC44Mzk4NF0gNzEgNzIgNTU2LjE1MjM0IDczIFsyNzcuODMyMDNdIDgzIFs1NTYuMTUyMzQgMCAwIDUwMCAyNzcuODMyMDNdXQovRFcgMD4+CmVuZG9iagoxMSAwIG9iago8PC9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggMjYyPj4gc3RyZWFtCnicXZHNasQgFIX3PsVdTheDTpKZoRACZUohi/7QtA9g9CYVGhVjFnn7+pOmUEHlcO539Cq9tY+tVh7omzOiQw+D0tLhbBYnEHoclSanAqQSflNpFRO3hAa4W2ePU6sHQ+oagL4Hd/ZuhcODND3eEfrqJDqlRzh83rqgu8Xab5xQe2CkaUDiEJKeuX3hEwJN2LGVwVd+PQbmr+JjtQhF0qd8G2EkzpYLdFyPSGoWRgP1UxgNQS3/+WWm+kF8cZeqy1DNWMGaqMprUucqqXP2riwlbUzxm7AfWGWouk/bZWMvOSl713KLyFC8V3y/vWmxOBf6TY+cGo0tKo37P1hjIxXnDxIJhhgKZW5kc3RyZWFtCmVuZG9iago0IDAgb2JqCjw8L1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUwCi9CYXNlRm9udCAvQUFBQUFBK0FyaWFsTVQKL0VuY29kaW5nIC9JZGVudGl0eS1ICi9EZXNjZW5kYW50Rm9udHMgWzEwIDAgUl0KL1RvVW5pY29kZSAxMSAwIFI+PgplbmRvYmoKeHJlZgowIDEyCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxNSAwMDAwMCBuIAowMDAwMDAwMzk3IDAwMDAwIG4gCjAwMDAwMDAxMDggMDAwMDAgbiAKMDAwMDAxMDgxMSAwMDAwMCBuIAowMDAwMDAwMTQ1IDAwMDAwIG4gCjAwMDAwMDA2MDUgMDAwMDAgbiAKMDAwMDAwMDY2MCAwMDAwMCBuIAowMDAwMDAwNzA3IDAwMDAwIG4gCjAwMDAwMDk5MzQgMDAwMDAgbiAKMDAwMDAxMDE2OCAwMDAwMCBuIAowMDAwMDEwNDc4IDAwMDAwIG4gCnRyYWlsZXIKPDwvU2l6ZSAxMgovUm9vdCA3IDAgUgovSW5mbyAxIDAgUj4+CnN0YXJ0eHJlZgoxMDk1MAolJUVPRg==",
                                "contentType": "application/pdf"
                            }
                        ],
                        "effectiveDateTime": "2024-02-25T15:12:12.837429",
                        "code": {
                            "coding": []
                        }
                    }
                }
            ]
        }
        ```

---

# DiagnosticReport

Source: https://docs.canvasmedical.com/api/diagnosticreport/

### 
The findings and interpretation of diagnostic tests performed on patients, groups of patients, devices, and locations, and/or specimens derived from these. The report includes clinical context such as requesting and provider information, and some mix of atomic results, images, textual and coded interpretations, and formatted representation of diagnostic reports.   
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-lab.html>  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-note.html>  
This endpoint implements the US Core DiagnosticReport Profile for Report. The following USCDI data elements are retrievable from this endpoint:  
Clinical Notes:  
\- Imaging Narrative  
\- Laboratory Report Narrative  
\- Pathology Report Narrative  
\- Procedure Note  
Laboratory:  
\- Tests  
\- Values/Results
### Endpoints
get/DiagnosticReport/{id} get/DiagnosticReport
get
/DiagnosticReport/{id}
#### DiagnosticReport read
Read a DiagnosticReport resource
### Path Parameters
id required
string
The unique identifier for the DiagnosticReport   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Diagnostic Report.
status
enum [ final | preliminary | entered-in-error ]
Status of the Diagnostic Report, see <https://hl7.org/fhir/R4/valueset-diagnostic-report-status.html>.   
  - `final`: the current version of the report.
  - `preliminary`: an earlier version of a lab report received electronically from a lab. Labs send an updated copy of a report each time more results are released, and Canvas keeps each copy as a separate DiagnosticReport with its own `presentedForm`. When a new copy arrives, it becomes `final` and every earlier copy becomes `preliminary`.
  - `entered-in-error`: the report was removed from the patient's chart.
For electronic lab reports, `final` means this is the newest copy Canvas has received. It does not mean the lab has finished every test on the order, and a newer copy may still arrive.   
DiagnosticReport search does not filter on status, so a search returns every version. To work with only the current version of each lab report, filter on `status` in your client, or search [DocumentReference](/api/documentreference) with `status=current`.
category
array[json]
Service category <https://hl7.org/fhir/R4/valueset-diagnostic-service-sections.html>. Use this attribute to help distinguish the type of report in Canvas.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v2-0074
  - http://loinc.org
code
string
The code of the category.
**Value Options Supported:**
  - LAB
  - LP29684-5
  - LP7839-6
  - LP29708-2
display
string
The display name of the coding.
**Value Options Supported:**
  - Laboratory
  - Radiology
  - Cardiology
  - Pathology
code
json
Name/Code for this diagnostic report.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the category.
display
string
The display name of the coding.
text
string
Plain text representation of the Lab or Imaging Report.
subject
json
The subject of the report.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Health care event when test ordered or reviewed.   
Lab and Imaging Reports in Canvas will have an Encounter associated with the payload if there has been a Lab Results Review, Imaging Report Review, or a POC Lab Test command committed in a note on the patient's chart.
Click to view child attributes
reference
string
The reference string of the Encounter in the format of `"Encounter/912542cf-3bfb-4609-99f6-26ce94feb70d"`.
effectiveDateTime
datetime | date
Clinically relevant date/time for report.
issued
datetime
DateTime this version was made.
performer
array[json]
Responsible Diagnostic Service. In Canvas this will be the Practitioner who is assigned to the Report.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
type
string
Type the reference refers to (e.g. "Practitioner").
result
array[json]
Observations associated with the Diagnostic Report.
Click to view child attributes
reference
string
The reference string of the observation in the format of `"Observation/dcc3239b-ffc9-4d02-9cb6-a486bb9d406e"`.
type
string
Type the reference refers to (e.g. "Observation").
presentedForm
array[json]
Entire report as issued. There is also a [DocumentReference](/api/documentreference) resource specifically for this Report PDF being created.   
The PDF is not updated in place. When a lab sends an updated copy of an electronic lab report, Canvas creates a new DiagnosticReport with its own `presentedForm`, and the earlier one becomes `preliminary`.
Click to view child attributes
url
string
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/DiagnosticReport
#### DiagnosticReport search
Search for DiagnosticReport resources
### Query Parameters
****
_id
string
A Canvas-issued unique identifier for a specific diagnostic report.
category
string
The DiagnosticReport category. Filters by the code and/or system under `category.coding` attribute. You can search by just the code value or you can search by the system and code in the format `system|code`.
**Search Values Supported:**
  - http://terminology.hl7.org/CodeSystem/v2-0074|code
  - http://loinc.org|code
code
string
The DiagnosticReport code. Filters by the code and/or system under `code.coding` attribute. You can search by just the code value or you can search by the system and code in the format `system|code`.
date
date
Filter by effectiveDateTime. See [Date Filtering](/api/date-filtering) for more information.
patient
string
The patient reference associated to the Diagnostic Report in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Diagnostic Report.
status
enum [ final | preliminary | entered-in-error ]
Status of the Diagnostic Report, see <https://hl7.org/fhir/R4/valueset-diagnostic-report-status.html>.   
  - `final`: the current version of the report.
  - `preliminary`: an earlier version of a lab report received electronically from a lab. Labs send an updated copy of a report each time more results are released, and Canvas keeps each copy as a separate DiagnosticReport with its own `presentedForm`. When a new copy arrives, it becomes `final` and every earlier copy becomes `preliminary`.
  - `entered-in-error`: the report was removed from the patient's chart.
For electronic lab reports, `final` means this is the newest copy Canvas has received. It does not mean the lab has finished every test on the order, and a newer copy may still arrive.   
DiagnosticReport search does not filter on status, so a search returns every version. To work with only the current version of each lab report, filter on `status` in your client, or search [DocumentReference](/api/documentreference) with `status=current`.
category
array[json]
Service category <https://hl7.org/fhir/R4/valueset-diagnostic-service-sections.html>. Use this attribute to help distinguish the type of report in Canvas.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v2-0074
  - http://loinc.org
code
string
The code of the category.
**Value Options Supported:**
  - LAB
  - LP29684-5
  - LP7839-6
  - LP29708-2
display
string
The display name of the coding.
**Value Options Supported:**
  - Laboratory
  - Radiology
  - Cardiology
  - Pathology
code
json
Name/Code for this diagnostic report.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the category.
display
string
The display name of the coding.
text
string
Plain text representation of the Lab or Imaging Report.
subject
json
The subject of the report.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Health care event when test ordered or reviewed.   
Lab and Imaging Reports in Canvas will have an Encounter associated with the payload if there has been a Lab Results Review, Imaging Report Review, or a POC Lab Test command committed in a note on the patient's chart.
Click to view child attributes
reference
string
The reference string of the Encounter in the format of `"Encounter/912542cf-3bfb-4609-99f6-26ce94feb70d"`.
effectiveDateTime
datetime | date
Clinically relevant date/time for report.
issued
datetime
DateTime this version was made.
performer
array[json]
Responsible Diagnostic Service. In Canvas this will be the Practitioner who is assigned to the Report.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
type
string
Type the reference refers to (e.g. "Practitioner").
result
array[json]
Observations associated with the Diagnostic Report.
Click to view child attributes
reference
string
The reference string of the observation in the format of `"Observation/dcc3239b-ffc9-4d02-9cb6-a486bb9d406e"`.
type
string
Type the reference refers to (e.g. "Observation").
presentedForm
array[json]
Entire report as issued. There is also a [DocumentReference](/api/documentreference) resource specifically for this Report PDF being created.   
The PDF is not updated in place. When a lab sends an updated copy of an electronic lab report, Canvas creates a new DiagnosticReport with its own `presentedForm`, and the earlier one becomes `preliminary`.
Click to view child attributes
url
string
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/DiagnosticReport/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DiagnosticReport/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "DiagnosticReport",
            "id": "9b90621b-059f-4f6e-9ef5-58171098e424",
            "status": "final",
            "category":
            [
                {
                    "coding":
                    [
                        {
                            "system": "http://loinc.org",
                            "code": "LP29684-5",
                            "display": "Radiology"
                        }
                    ]
                }
            ],
            "code":
            {
                "coding":
                [
                    {
                        "system": "http://www.ama-assn.org/go/cpt",
                        "code": "73562",
                        "display": "XRAY, knee; 3 views"
                    }
                ],
                "text": "XRAY, knee; 3 views"
            },
            "subject":
            {
                "reference": "Patient/a1197fa9e65b4a5195af15e0234f61c2",
                "type": "Patient"
            },
            "encounter":
            {
                "reference": "Encounter/6a077e6f-ead2-4af7-803d-0a203bedfb1c",
                "type": "Encounter"
            },
            "effectiveDateTime": "2023-08-22",
            "issued": "2023-08-22T21:35:01.909441+00:00",
            "performer":
            [
                {
                    "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                    "type": "Practitioner"
                }
            ],
            "presentedForm":
            [
                {
                    "url": "https://fumage-example.canvasmedical.com/DiagnosticReport/9b90621b-059f-4f6e-9ef5-58171098e424/files/presentedForm"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown DiagnosticReport resource '9b814d81-fb56-456b-a46d-c67fdaaec2ac'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/DiagnosticReport?patient=Patient/ca52f2b76011429d8a0e4aa2b56b18bc&code=73562&date=ge2023-09-12' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DiagnosticReport?patient=Patient/ca52f2b76011429d8a0e4aa2b56b18bc&code=73562&date=ge2023-09-12"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 2,
            "link":
            [
                {
                    "relation": "self",
                    "url": "/DiagnosticReport?patient=Patient/ca52f2b76011429d8a0e4aa2b56b18bc&code=73562&date=ge2023-09-12&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/DiagnosticReport?patient=Patient/ca52f2b76011429d8a0e4aa2b56b18bc&code=73562&date=ge2023-09-12&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/DiagnosticReport?patient=Patient/ca52f2b76011429d8a0e4aa2b56b18bc&code=73562&date=ge2023-09-12&_count=10&_offset=0"
                }
            ],
            "entry":
            [
                {
                    "resource":
                    {
                        "resourceType": "DiagnosticReport",
                        "id": "197d1b7a-374e-4aa8-82b2-6960a62ecf7a",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v2-0074",
                                        "code": "LAB",
                                        "display": "Laboratory"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "6690-2",
                                    "display": "WBC"
                                },
                                {
                                    "system": "http://loinc.org",
                                    "code": "785-6",
                                    "display": "MCH"
                                },
                                {
                                    "system": "http://loinc.org",
                                    "code": "5905-5",
                                    "display": "Monocytes"
                                }
                            ],
                            "text": "Complete Blood Count (Cbc) With Differential"
                        },
                        "subject": {
                            "reference": "Patient/ca52f2b76011429d8a0e4aa2b56b18bc",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2022-04-01T07:00:00+00:00",
                        "issued": "2022-04-15T15:24:22.522951+00:00",
                        "performer": [
                            {
                                "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                "type": "Practitioner"
                            }
                        ],
                        "result": [
                            {
                                "reference": "Observation/422f9f0f-151a-4488-bcad-ab4b0c3967da",
                                "type": "Observation"
                            }
                        ],
                        "presentedForm": [
                            {
                                "url": "https://fumage-example.canvasmedical.com/DiagnosticReport/197d1b7a-374e-4aa8-82b2-6960a62ecf7a/files/presentedForm"
                            }
                        ]
                    }
                },
                {
                    "resource":
                    {
                        "resourceType": "DiagnosticReport",
                        "id": "9b814d81-fb56-456b-a46d-c67fdaaec2ad",
                        "status": "final",
                        "category":
                        [
                            {
                                "coding":
                                [
                                    {
                                        "system": "http://loinc.org",
                                        "code": "LP29684-5",
                                        "display": "Radiology"
                                    }
                                ]
                            }
                        ],
                        "code":
                        {
                            "coding":
                            [
                                {
                                    "system": "http://www.ama-assn.org/go/cpt",
                                    "code": "73562",
                                    "display": "XRAY, knee; 3 views"
                                }
                            ]
                        },
                        "subject":
                        {
                            "reference": "Patient/ca52f2b76011429d8a0e4aa2b56b18bc",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2023-09-15",
                        "issued": "2023-09-15T19:52:56.711871+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/3640cd20de8a470aa570a852859ac87e",
                                "type": "Practitioner"
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# DocumentReference

Source: https://docs.canvasmedical.com/api/documentreference/

### 
A reference to a document of any kind for any purpose. Provides metadata about the document so that the document can be discovered and managed. The scope of a document is any seralized object with a mime-type, so includes formal patient centric documents (CDA), clinical notes, scanned paper, and non-patient specific documents like policy text.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-documentreference.html>  
A Document Reference can represent many different PDFs generated in Canvas:
  - A [Letter](https://canvas-medical.help.usepylon.com/articles/8181146406-letters) that has been faxed or printed from the patient's chart.
  - All documents uploaded via [Data Integration](https://help.canvasmedical.com/articles/7371085164-data-integration) and linked to a Patient. This includes Lab Reports, Imaging Reports, Referral Reports, Clinical, and Administrative Documents.
  - [POC Lab Commands](https://canvas-medical.help.usepylon.com/articles/7060961677-point-of-care-poc-tests) committed on the Patient's chart
  - [Clinical Notes](https://canvas-medical.help.usepylon.com/articles/1679996479-print-patient-chart) representing a PDF of each locked note. This also includes superseded versions on notes.
  - Any [Educational Material](https://canvas-medical.help.usepylon.com/articles/4966226408-educational-material-command) committed on a patient's chart.
  - Any [Invoices](https://help.canvasmedical.com/articles/9992348572-claim-management#invoicing-statements-128) generated for a patient.
#### Additional information
  - Every DocumentReference belongs to a patient. Patient-agnostic and practitioner-only documents are not supported.
  - To download a document's file, see [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files/).
  - The create request body, including the base64-encoded file in `content.attachment.data`, is limited to roughly 1MB. Larger payloads return `413 Request Entity Too Large`.
### Endpoints
post/DocumentReference get/DocumentReference/{id} get/DocumentReference
post
/DocumentReference
#### DocumentReference create
Create DocumentReference with provided fields and values. The request body is limited to roughly 1MB.
### Attributes
resourceType
string
The FHIR Resource name.
extension
array[json] required
Specific FHIR extensions on this resource are supported to be able to map some Canvas specific attributes for a comment, clinical date, review mode, reviewer, priority, and if it requires a signature.
In order to identify which extension maps to specific fields in Canvas, the url field is used as an exact string match.  
**A few of the extensions are required:******
  - clinical-date
  - A reviewer is required, it can either be a practitioner or a group of practitioners. Provide one or the other, not both.
  - requires-signature
Click to view child attributes
url
string required
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/document-reference-comment
  - http://schemas.canvasmedical.com/fhir/document-reference-clinical-date
  - http://schemas.canvasmedical.com/fhir/document-reference-review-mode
  - http://schemas.canvasmedical.com/fhir/document-reference-reviewer
  - http://schemas.canvasmedical.com/fhir/document-reference-reviewer-group
  - http://schemas.canvasmedical.com/fhir/document-reference-priority
  - http://schemas.canvasmedical.com/fhir/document-reference-requires-signature
valueString
string
Value of extensions for Comment.
The `valueString` attribute is needed for the Comment's extension where the `url` is `http://schemas.canvasmedical.com/fhir/document-reference-comment`.  
Comment is a comment on the underlying Canvas document that is related to this DocumentReference resource.
valueCode
string
Value of extensions for Review Mode.
The `valueCode` attribute is needed for the Review Mode extension where the `url` is `http://schemas.canvasmedical.com/fhir/document-reference-review-mode`.   
Review Mode is a field on the underlying Canvas document record which determines the review mode values (`RR` for Review Required, `AR` for Already Reviewed and `RN` for Review Not Required).
**Value Options Supported:**
  - RR
  - AR
  - RN
valueDate
date required
Value of extension for Clinical Date.
The `valueDate` attribute is needed for the Clinical Date extension where the `url` is `http://schemas.canvasmedical.com/fhir/document-reference-clinical-date`. This attribute is required and determines the Clinical Date on the underlying document record related to this DocumentReference resource. It's the `original_date` field on the related Canvas document record. Expected date value format for this field is `YYYY-MM-DD`.
valueReference
json required
Value of extension for Reviewer(s). The reviewer can be an individual practitioner and/or a group of practitioners.
The `valueReference` attribute is needed for expressing the Reviewer of the document where the `url` can be `http://schemas.canvasmedical.com/fhir/document-reference-reviewer` for an individual practitioner or `http://schemas.canvasmedical.com/fhir/document-reference-reviewer-group` for a group/team of practitioners. This attribute is required and will be the reference to the Practitioner (Canvas Staff) and/or Group (Canvas Team) that's assigned as the reviewer of this document.
Click to view child attributes
reference
string required
The reference string of the Practitioner or Group in the format of `"Practitioner/95b9ac2d-e963-4d7a-b165-7901870f1663"` or `"Group/a6ae9198-19ba-4c27-b8e2-a8d5d3395b78"`.
type
string
Type the reference refers to (e.g. "Practitioner" or "Group").
valueBoolean
boolean required
Value of extensions for Priority and Requires Signature.
The `valueBoolean` attribute is needed for the Priority extension where the `url` is `http://schemas.canvasmedical.com/fhir/document-reference-priority` and for the Requires Signature where the `url` is `http://schemas.canvasmedical.com/fhir/document-reference-requires-signature`.   
Priority is a field on the underlying Canvas document that is related to this DocumentReference resource and determines if the document should be prioritized. If the priority is omitted from the request, it will default to False.   
Requires Signature is also a field on the underlying Canvas document that determines whether the related document requires Practitioner's signature.
status
required
Status must be set to `current` on creation; the value has no further effect.
**Value Options Supported:**
  - current
type
json required
A coding for the type of document.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
code
string required
The code value.
**Value Options Supported:**
  - 51852-2 (Letters) (read-only)
  - 34895-3 (Educational Material) (read-only)
  - 94093-2 (Invoices/Itemized Bill) (read-only)
  - 53243-2 (Advance Beneficiary Notice)
  - 42348-3 (Advance Directive / Living Will)
  - 91983-7 (Care Management)
  - 53245-7 (CDL (Commercial Driver License))
  - 96335-5 (Emergency Department Report)
  - 11503-0 (External Medical Records)
  - 75503-3 (Home Care Report)
  - 34105-7 (Hospital Discharge Summary)
  - 47039-3 (Hospital History & Physical)
  - 64290-0 (Insurance Card)
  - 52034-6 (Insurer Prior Authorization)
  - 34113-1 (Nursing Home)
  - 11504-8 (Operative Report)
  - 80570-5 (Patient Agreement)
  - 64285-0 (Patient Clinical Intake Form)
  - 51848-0 (Physical Exams)
  - 46209-3 (POLST (Provider Order for Life Sustaining-Treatment))
  - 64298-3 (Power of Attorney)
  - 57833-6 (Prescription Refill Request)
  - 34823-5 (Rehabilitation Report)
  - 101904-1 (Release of Information Request)
  - 34109-9 (Uncategorized Clinical Document)
  - 51851-4 (Uncategorized Administrative Document)
  - 52070-0 (Worker's Compensation Documents)
category
array[json] required
The categorization of the document.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/document-reference-category
code
string required
The code value.
**Value Options Supported:**
  - patientadministrativedocument
  - uncategorizedclinicaldocument
subject
json required
Who/what is the subject of the document. Must reference a Patient.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`. Must be a Patient reference.
type
string
Type the reference refers to. Must be "Patient".
author
array[json]
Who and/or what authored the document.
Click to view child attributes
reference
string required
The reference string of the author in the format of `"Practitioner/0e46396e-9cbc-48c6-94cc-f75f08b66c80"`.
type
string
Type the reference refers to (e.g. "Practitioner").
description
string
The title of the underlying Canvas Document related to this DocumentReference resource.
content
array[json] required
Document referenced
Click to view child attributes
attachment
json required
Where to access the document.  
The create request body, including the base64-encoded file in `content.attachment.data`, is limited to roughly 1MB. Larger payloads return `413 Request Entity Too Large`.
Click to view child attributes
contentType
string required
Mime type of the content, with charset etc.
data
string required
Base64 encoded document file as a string.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/DocumentReference/{id}
#### DocumentReference read
Read DocumentReference resource.
### Path Parameters
id required
string
The unique identifier for the DocumentReference   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the document reference.
identifier
array[json]
Other identifiers for the document.
Click to view child attributes
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/document-reference-identifier
value
string
The identifier value that is unique.
extension
array[json]
Specific FHIR extensions on this resource are supported to be able to map some Canvas specific attributes for a comment, clinical date, review mode, reviewer, priority, and if it requires a signature.
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/document-reference-comment
  - http://schemas.canvasmedical.com/fhir/document-reference-clinical-date
  - http://schemas.canvasmedical.com/fhir/document-reference-review-mode
  - http://schemas.canvasmedical.com/fhir/document-reference-reviewer
  - http://schemas.canvasmedical.com/fhir/document-reference-reviewer-group
  - http://schemas.canvasmedical.com/fhir/document-reference-priority
  - http://schemas.canvasmedical.com/fhir/document-reference-requires-signature
valueString
string
Value of extensions for Comment.
valueCode
string
Value of extensions for Review Mode.
**Value Options Supported:**
  - RR
  - AR
  - RN
valueDate
date
Value of extension for Clinical Date.
valueReference
json
Value of extension for Reviewer(s). The reviewer can be an individual practitioner and/or a group of practitioners.
Click to view child attributes
reference
string
The reference string of the Practitioner or Group in the format of `"Practitioner/95b9ac2d-e963-4d7a-b165-7901870f1663"` or `"Group/a6ae9198-19ba-4c27-b8e2-a8d5d3395b78"`.
type
string
Type the reference refers to (e.g. "Practitioner" or "Group").
valueBoolean
boolean
Value of extensions for Priority and Requires Signature.
status
The status of the document reference.   
  - Letters and POC Lab Reports will always have a status of `current`.
  - For Lab Reports received electronically from a lab, the status will be `current` for the newest version of the report and `superseded` for earlier versions. Labs send an updated copy of a report each time more results are released, and each copy has its own DocumentReference. If the report is removed from the patient's chart, the status will be `entered-in-error`.
  - Documents uploaded in Data Integration will have a status of `current` when created. If a document is removed from the patient's chart, it will have a status of `entered-in-error`.
  - For Clinical Note documents, the status will be `current` if it is the latest PDF of the locked note. If it is an older version due to a practitioner unlocking/ammending the note, the status will be `superseded`. If the note is deleted on the patient's chart, the status will be `entered-in-error`.
  - For Educational Material, the status will be `current` if the command is committed. If the command was entered-in-error in the chart, the status will also be `entered-in-error`.
  - For Invoices, the status will be `current` if it is a latest version or an adhoc invoice. The status will be `entered-in-error` if there was a problem generating or sending out the invoice to the patient. The status will be `superseded` if an automated invoice gets archived as it is older than the invoice interval defined Constance Config in Settings.
**Value Options Supported:**
  - current
  - superseded
  - entered-in-error
type
json
A coding for the type of document.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
code
string
The code value.
**Value Options Supported:**
  - 51852-2 (Letters) (read-only)
  - 34895-3 (Educational Material) (read-only)
  - 94093-2 (Invoices/Itemized Bill) (read-only)
  - 53243-2 (Advance Beneficiary Notice)
  - 42348-3 (Advance Directive / Living Will)
  - 91983-7 (Care Management)
  - 53245-7 (CDL (Commercial Driver License))
  - 96335-5 (Emergency Department Report)
  - 11503-0 (External Medical Records)
  - 75503-3 (Home Care Report)
  - 34105-7 (Hospital Discharge Summary)
  - 47039-3 (Hospital History & Physical)
  - 64290-0 (Insurance Card)
  - 52034-6 (Insurer Prior Authorization)
  - 34113-1 (Nursing Home)
  - 11504-8 (Operative Report)
  - 80570-5 (Patient Agreement)
  - 64285-0 (Patient Clinical Intake Form)
  - 51848-0 (Physical Exams)
  - 46209-3 (POLST (Provider Order for Life Sustaining-Treatment))
  - 64298-3 (Power of Attorney)
  - 57833-6 (Prescription Refill Request)
  - 34823-5 (Rehabilitation Report)
  - 101904-1 (Release of Information Request)
  - 34109-9 (Uncategorized Clinical Document)
  - 51851-4 (Uncategorized Administrative Document)
  - 52070-0 (Worker's Compensation Documents)
display
string
The display name of the coding.
text
string
Plain text representation of the type of document.
category
array[json]
The categorization of the document. For non-administrative documents, the response also includes an additional `category` entry with system `http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category` and code `clinical-note` (for US Core compliance).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/document-reference-category
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category
code
string
The code value.
**Value Options Supported:**
  - clinical-note
  - correspondence
  - educationalmaterial
  - imagingreport
  - invoicefull
  - labreport
  - patientadministrativedocument
  - referralreport
  - uncategorizedclinicaldocument
subject
json
Who/what is the subject of the document. Must reference a Patient.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`. Must be a Patient reference.
type
string
Type the reference refers to. Must be "Patient".
date
datetime
When this document reference was created in Canvas.
author
array[json]
Who and/or what authored the document.
  - For letters, it is the practitioner who signed the letter determined by the practitioner dropdown in the UI when creating the letter.
  - For Lab Reports the author will be the practitioner who linked the report to the patient in Data Integration or if it the report has been reviewed, it will be the practitioner who committed a Lab Review. If the lab report that came through Health Gorilla was automtically linked to a Patient, there will be no author.
  - For POC Lab Reports, the author will be the practitioner who committed the command in the patient's chart.
  - For Clinical and Administrative submitted through Data Integration, the author will be the practitioner who linked the doc to the patient in Data Integration.
  - For Educational Material docs, the author will be the practitioner who originated the command on the patient's chart
  - For Invoices, the author will either be the practitioner who asked for the invoice when invoice was created adhoc or it will be Canvas Bot if the invoice was automtically generated.
  - There are no authors on Imaging Reports or Clinical Notes.
Click to view child attributes
reference
string
The reference string of the author in the format of `"Practitioner/0e46396e-9cbc-48c6-94cc-f75f08b66c80"`.
type
string
Type the reference refers to (e.g. "Practitioner").
custodian
json
Organization which maintains the document.
Click to view child attributes
reference
string
The reference string of the custodian in the format of `"Organization/00000000-0000-0000-0002-000000000000"`.
type
string
Type the reference refers to (e.g. "Organization").
description
string
The title of the underlying Canvas Document related to this DocumentReference resource.
content
array[json]
Document referenced
Click to view child attributes
attachment
json
Where to access the document.  
The create request body, including the base64-encoded file in `content.attachment.data`, is limited to roughly 1MB. Larger payloads return `413 Request Entity Too Large`.
Click to view child attributes
contentType
string
Mime type of the content, with charset etc.
url
string
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
format
json
Format/content rules for the document
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem
code
string
The code value.
**Value Options Supported:**
  - urn:ihe:iti:xds:2017:mimeTypeSufficient
display
string
The display name of the coding.
**Value Options Supported:**
  - mimeType Sufficient
context
json
Clinical context of document.   
  - For clinical note documents, the context will contain information about the encounter associated with the note if applicable.
  - For POC Lab Reports or Educational Material documents, the context will contain information about the encounter of the note the commands were committed with if applicable.
  - For Lab Reports that have a Lab Review committed in a note, the context will have information about any encounter associated with that note.
Click to view child attributes
encounter
array[json]
Context of the document content
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/879b35fd-3bc2-4ccd-98d7-954dd9b6d0a9"`.
type
string
Type the reference refers to (e.g. "Encounter").
period
json
Time of service that is being documented
Click to view child attributes
start
datetime
Starting time with inclusive boundary of the encounter
end
datetime
End time with inclusive boundary, if not ongoing of the encounter
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/DocumentReference
#### DocumentReference search
Search for DocumentReference resources.
### Query Parameters
****
_id
string
A Canvas-issued unique identifier
category
string
Categorization of document. Filters by the code and/or system under `category.coding` attribute. You can search by just the code value or you can search by the system and code in the format `system|code` (e.g `http://schemas.canvasmedical.com/fhir/document-reference-category|labreport`).
date
date or datetime
Filter by the date or specific datetime the document was created. See [Date Filtering](/api/date-filtering) for more information.
patient
string
The patient reference associated to the document in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
status
string
The status of the document reference
**Search Values Supported:**
  - current
  - superseded
  - entered-in-error
subject
string
The patient reference associated to the document in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`. Can be used interchangeably with the patient parameter.
type
string
Kind of document (LOINC if possible). Filters by the code and/or system under `type.coding` attribute. You can search by just the code value or you can search by the system and code in the format `system|code` (e.g `http://loinc.org|11502-2`).
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the document reference.
identifier
array[json]
Other identifiers for the document.
Click to view child attributes
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/document-reference-identifier
value
string
The identifier value that is unique.
extension
array[json]
Specific FHIR extensions on this resource are supported to be able to map some Canvas specific attributes for a comment, clinical date, review mode, reviewer, priority, and if it requires a signature.
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/document-reference-comment
  - http://schemas.canvasmedical.com/fhir/document-reference-clinical-date
  - http://schemas.canvasmedical.com/fhir/document-reference-review-mode
  - http://schemas.canvasmedical.com/fhir/document-reference-reviewer
  - http://schemas.canvasmedical.com/fhir/document-reference-reviewer-group
  - http://schemas.canvasmedical.com/fhir/document-reference-priority
  - http://schemas.canvasmedical.com/fhir/document-reference-requires-signature
valueString
string
Value of extensions for Comment.
valueCode
string
Value of extensions for Review Mode.
**Value Options Supported:**
  - RR
  - AR
  - RN
valueDate
date
Value of extension for Clinical Date.
valueReference
json
Value of extension for Reviewer(s). The reviewer can be an individual practitioner and/or a group of practitioners.
Click to view child attributes
reference
string
The reference string of the Practitioner or Group in the format of `"Practitioner/95b9ac2d-e963-4d7a-b165-7901870f1663"` or `"Group/a6ae9198-19ba-4c27-b8e2-a8d5d3395b78"`.
type
string
Type the reference refers to (e.g. "Practitioner" or "Group").
valueBoolean
boolean
Value of extensions for Priority and Requires Signature.
status
The status of the document reference.   
  - Letters and POC Lab Reports will always have a status of `current`.
  - For Lab Reports received electronically from a lab, the status will be `current` for the newest version of the report and `superseded` for earlier versions. Labs send an updated copy of a report each time more results are released, and each copy has its own DocumentReference. If the report is removed from the patient's chart, the status will be `entered-in-error`.
  - Documents uploaded in Data Integration will have a status of `current` when created. If a document is removed from the patient's chart, it will have a status of `entered-in-error`.
  - For Clinical Note documents, the status will be `current` if it is the latest PDF of the locked note. If it is an older version due to a practitioner unlocking/ammending the note, the status will be `superseded`. If the note is deleted on the patient's chart, the status will be `entered-in-error`.
  - For Educational Material, the status will be `current` if the command is committed. If the command was entered-in-error in the chart, the status will also be `entered-in-error`.
  - For Invoices, the status will be `current` if it is a latest version or an adhoc invoice. The status will be `entered-in-error` if there was a problem generating or sending out the invoice to the patient. The status will be `superseded` if an automated invoice gets archived as it is older than the invoice interval defined Constance Config in Settings.
**Value Options Supported:**
  - current
  - superseded
  - entered-in-error
type
json
A coding for the type of document.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
code
string
The code value.
**Value Options Supported:**
  - 51852-2 (Letters) (read-only)
  - 34895-3 (Educational Material) (read-only)
  - 94093-2 (Invoices/Itemized Bill) (read-only)
  - 53243-2 (Advance Beneficiary Notice)
  - 42348-3 (Advance Directive / Living Will)
  - 91983-7 (Care Management)
  - 53245-7 (CDL (Commercial Driver License))
  - 96335-5 (Emergency Department Report)
  - 11503-0 (External Medical Records)
  - 75503-3 (Home Care Report)
  - 34105-7 (Hospital Discharge Summary)
  - 47039-3 (Hospital History & Physical)
  - 64290-0 (Insurance Card)
  - 52034-6 (Insurer Prior Authorization)
  - 34113-1 (Nursing Home)
  - 11504-8 (Operative Report)
  - 80570-5 (Patient Agreement)
  - 64285-0 (Patient Clinical Intake Form)
  - 51848-0 (Physical Exams)
  - 46209-3 (POLST (Provider Order for Life Sustaining-Treatment))
  - 64298-3 (Power of Attorney)
  - 57833-6 (Prescription Refill Request)
  - 34823-5 (Rehabilitation Report)
  - 101904-1 (Release of Information Request)
  - 34109-9 (Uncategorized Clinical Document)
  - 51851-4 (Uncategorized Administrative Document)
  - 52070-0 (Worker's Compensation Documents)
display
string
The display name of the coding.
text
string
Plain text representation of the type of document.
category
array[json]
The categorization of the document. For non-administrative documents, the response also includes an additional `category` entry with system `http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category` and code `clinical-note` (for US Core compliance).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/document-reference-category
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category
code
string
The code value.
**Value Options Supported:**
  - clinical-note
  - correspondence
  - educationalmaterial
  - imagingreport
  - invoicefull
  - labreport
  - patientadministrativedocument
  - referralreport
  - uncategorizedclinicaldocument
subject
json
Who/what is the subject of the document. Must reference a Patient.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`. Must be a Patient reference.
type
string
Type the reference refers to. Must be "Patient".
date
datetime
When this document reference was created in Canvas.
author
array[json]
Who and/or what authored the document.
  - For letters, it is the practitioner who signed the letter determined by the practitioner dropdown in the UI when creating the letter.
  - For Lab Reports the author will be the practitioner who linked the report to the patient in Data Integration or if it the report has been reviewed, it will be the practitioner who committed a Lab Review. If the lab report that came through Health Gorilla was automtically linked to a Patient, there will be no author.
  - For POC Lab Reports, the author will be the practitioner who committed the command in the patient's chart.
  - For Clinical and Administrative submitted through Data Integration, the author will be the practitioner who linked the doc to the patient in Data Integration.
  - For Educational Material docs, the author will be the practitioner who originated the command on the patient's chart
  - For Invoices, the author will either be the practitioner who asked for the invoice when invoice was created adhoc or it will be Canvas Bot if the invoice was automtically generated.
  - There are no authors on Imaging Reports or Clinical Notes.
Click to view child attributes
reference
string
The reference string of the author in the format of `"Practitioner/0e46396e-9cbc-48c6-94cc-f75f08b66c80"`.
type
string
Type the reference refers to (e.g. "Practitioner").
custodian
json
Organization which maintains the document.
Click to view child attributes
reference
string
The reference string of the custodian in the format of `"Organization/00000000-0000-0000-0002-000000000000"`.
type
string
Type the reference refers to (e.g. "Organization").
description
string
The title of the underlying Canvas Document related to this DocumentReference resource.
content
array[json]
Document referenced
Click to view child attributes
attachment
json
Where to access the document.  
The create request body, including the base64-encoded file in `content.attachment.data`, is limited to roughly 1MB. Larger payloads return `413 Request Entity Too Large`.
Click to view child attributes
contentType
string
Mime type of the content, with charset etc.
url
string
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
format
json
Format/content rules for the document
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem
code
string
The code value.
**Value Options Supported:**
  - urn:ihe:iti:xds:2017:mimeTypeSufficient
display
string
The display name of the coding.
**Value Options Supported:**
  - mimeType Sufficient
context
json
Clinical context of document.   
  - For clinical note documents, the context will contain information about the encounter associated with the note if applicable.
  - For POC Lab Reports or Educational Material documents, the context will contain information about the encounter of the note the commands were committed with if applicable.
  - For Lab Reports that have a Lab Review committed in a note, the context will have information about any encounter associated with that note.
Click to view child attributes
encounter
array[json]
Context of the document content
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/879b35fd-3bc2-4ccd-98d7-954dd9b6d0a9"`.
type
string
Type the reference refers to (e.g. "Encounter").
period
json
Time of service that is being documented
Click to view child attributes
start
datetime
Starting time with inclusive boundary of the encounter
end
datetime
End time with inclusive boundary, if not ongoing of the encounter
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/DocumentReference' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
          {
            "resourceType": "DocumentReference",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                    "valueString": "Some comment on Document"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                    "valueDate": "2024-04-01"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                    "valueCode": "RN"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                    "valueReference": {
                        "reference": "Practitioner/5843991a8c934118ab4f424c839b340f",
                        "type": "Practitioner"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-priority",
                    "valueBoolean": true
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-requires-signature",
                    "valueBoolean": true
                }
            ],
            "status": "current",
            "type": {
                "coding": [
                    {
                        "system": "http://loinc.org",
                        "code": "34105-7"
                    }
                ]
            },
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                            "code": "uncategorizedclinicaldocument"
                        }
                    ]
                }
            ],
            "subject": {
                "reference": "Patient/aabcf98215eb4356ad773a0ec9cd3369",
                "type": "Patient"
            },
            "author": [
                {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                    "type": "Practitioner"
                }
            ],
            "description": "Hospital Discharge Summary",
            "content": [
                {
                    "attachment": {
                        "contentType": "application/pdf",
                        "data": "JVBERi0xLjIgCjkgMCBvYmoKPDwKPj4Kc3RyZWFtCkJULyAzMiBUZiggIFlPVVIgVEVYVCBIRVJFICAgKScgRVQKZW5kc3RyZWFtCmVuZG9iago0IDAgb2JqCjw8Ci9UeXBlIC9QYWdlCi9QYXJlbnQgNSAwIFIKL0NvbnRlbnRzIDkgMCBSCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9LaWRzIFs0IDAgUiBdCi9Db3VudCAxCi9UeXBlIC9QYWdlcwovTWVkaWFCb3ggWyAwIDAgMjUwIDUwIF0KPj4KZW5kb2JqCjMgMCBvYmoKPDwKL1BhZ2VzIDUgMCBSCi9UeXBlIC9DYXRhbG9nCj4+CmVuZG9iagp0cmFpbGVyCjw8Ci9Sb290IDMgMCBSCj4+CiUlRU9G"
                    }
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DocumentReference"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json",
        }
        payload = {
            "resourceType": "DocumentReference",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                    "valueString": "Some comment on Document",
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                    "valueDate": "2024-04-01",
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                    "valueCode": "RN",
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                    "valueReference": {
                        "reference": "Practitioner/5843991a8c934118ab4f424c839b340f",
                        "type": "Practitioner",
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-priority",
                    "valueBoolean": True,
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-requires-signature",
                    "valueBoolean": True,
                }
            ],
            "status": "current",
            "type": {
                "coding": [
                    {
                        "system": "http://loinc.org",
                        "code": "34105-7",
                    }
                ]
            },
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                            "code": "uncategorizedclinicaldocument",
                        }
                    ]
                }
            ],
            "subject": {
                "reference": "Patient/aabcf98215eb4356ad773a0ec9cd3369",
                "type": "Patient",
            },
            "author": [
                {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                    "type": "Practitioner",
                }
            ],
            "description": "Hospital Discharge Summary",
            "content": [
                {
                    "attachment": {
                        "contentType": "application/pdf",
                        "data": "JVBERi0xLjIgCjkgMCBvYmoKPDwKPj4Kc3RyZWFtCkJULyAzMiBUZiggIFlPVVIgVEVYVCBIRVJFICAgKScgRVQKZW5kc3RyZWFtCmVuZG9iago0IDAgb2JqCjw8Ci9UeXBlIC9QYWdlCi9QYXJlbnQgNSAwIFIKL0NvbnRlbnRzIDkgMCBSCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9LaWRzIFs0IDAgUiBdCi9Db3VudCAxCi9UeXBlIC9QYWdlcwovTWVkaWFCb3ggWyAwIDAgMjUwIDUwIF0KPj4KZW5kb2JqCjMgMCBvYmoKPDwKL1BhZ2VzIDUgMCBSCi9UeXBlIC9DYXRhbG9nCj4+CmVuZG9iagp0cmFpbGVyCjw8Ci9Sb290IDMgMCBSCj4+CiUlRU9G",
                    }
                }
            ]
        }
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/DocumentReference/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DocumentReference/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "DocumentReference",
            "id": "6f60ed1c-a6b3-4791-99f0-f618704e33d1",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                    "valueString": "Some comment on Document"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                    "valueDate": "2024-04-01"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                    "valueCode": "RN"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                    "valueReference": {
                        "reference": "Practitioner/5843991a8c934118ab4f424c839b340f",
                        "type": "Practitioner"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-priority",
                    "valueBoolean": true
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/document-reference-requires-signature",
                    "valueBoolean": true
                }
            ],
            "status": "current",
            "type": {
                "coding": [
                    {
                        "system": "http://loinc.org",
                        "code": "34105-7",
                        "display": "Hospital Discharge summary"
                    }
                ]
            },
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                            "code": "uncategorizedclinicaldocument"
                        }
                    ]
                },
                {
                    "coding": [
                        {
                            "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
                            "code": "clinical-note"
                        }
                    ]
                }
            ],
            "subject": {
                "reference": "Patient/aabcf98215eb4356ad773a0ec9cd3369",
                "type": "Patient"
            },
            "date": "2024-04-22T00:00:00+00:00",
            "author": [
                {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                    "type": "Practitioner"
                }
            ],
            "custodian": {
                "reference": "Organization/00000000-0000-0000-0002-000000000000",
                "type": "Organization"
            },
            "description": "Hospital Discharge Summary",
            "content": [
                {
                    "attachment": {
                        "contentType": "application/pdf",
                        "url": "https://fumage-example.canvasmedical.com/DocumentReference/6f60ed1c-a6b3-4791-99f0-f618704e33d1/files/content"
                    },
                    "format": {
                        "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                        "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                        "display": "mimeType Sufficient"
                    }
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown DocumentReference resource '9b814d81-fb56-456b-a46d-c67fdaaec2ac'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/DocumentReference?subject=Patient/cfd91cd3bd9046db81199aa8ee4afd7f&status=current&type=http://loinc.org|11502-2' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/DocumentReference?subject=Patient/cfd91cd3bd9046db81199aa8ee4afd7f&status=current&type=http://loinc.org|11502-2"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 12,
            "link": [
                {
                    "relation": "self",
                    "url": "/DocumentReference?subject=Patient%2Fcfd91cd3bd9046db81199aa8ee4afd7f&status=current&type=http%3A%2F%2Floinc.org%7C11502-2&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/DocumentReference?subject=Patient%2Fcfd91cd3bd9046db81199aa8ee4afd7f&status=current&type=http%3A%2F%2Floinc.org%7C11502-2&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/DocumentReference?subject=Patient%2Fcfd91cd3bd9046db81199aa8ee4afd7f&status=current&type=http%3A%2F%2Floinc.org%7C11502-2&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "4b640065-ae64-4775-b5a8-8264314cf5fc",
                        "status": "current",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "94093-2",
                                    "display": "Itemized bill"
                                }
                            ],
                            "text": "Itemized bill"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "invoicefull"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-24T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Itemized bill",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/4b640065-ae64-4775-b5a8-8264314cf5fc/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "5a0cf7ae-bd88-4f04-bd7e-60a33e5e2824",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                                "valueString": "Some comment on LabReport Document"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                                "valueDate": "2024-04-02"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                                "valueCode": "AR"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                                "valueReference": {
                                    "reference": "Practitioner/5843991a8c934118ab4f424c839b340f",
                                    "type": "Practitioner"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer-group",
                                "valueReference": {
                                    "reference": "Group/a6ae9198-19ba-4c27-b8e2-a8d5d3395b78",
                                    "type": "Group"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-requires-signature",
                                "valueBoolean": true
                            }
                        ],
                        "status": "current",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "11502-2",
                                    "display": "Laboratory report"
                                }
                            ],
                            "text": "Laboratory report"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "labreport"
                                    }
                                ]
                            },
                            {
                                "coding": [
                                    {
                                        "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
                                        "code": "clinical-note"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-04-22T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Lab Report",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/5a0cf7ae-bd88-4f04-bd7e-60a33e5e2824/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ],
                        "context": {
                            "encounter": [
                                {
                                    "reference": "Encounter/879b35fd-3bc2-4ccd-98d7-954dd9b6d0a9",
                                    "type": "Encounter"
                                }
                            ],
                            "period": {
                                "start": "2024-02-22T23:10:12.409838+00:00"
                            }
                        }
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "b9f82cd0-6644-4b3f-a9d1-7585c3e71498",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                                "valueString": "Some comment on ImagingReport Document"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                                "valueDate": "2024-04-03"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                                "valueCode": "RN"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                                "valueReference": {
                                    "reference": "Practitioner/5843991a8c934118ab4f424c839b340f",
                                    "type": "Practitioner"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-requires-signature",
                                "valueBoolean": true
                            }
                        ],
                        "status": "entered-in-error",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "18748-4",
                                    "display": "Diagnostic imaging study"
                                }
                            ],
                            "text": "Diagnostic imaging study"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "imagingreport"
                                    }
                                ]
                            },
                            {
                                "coding": [
                                    {
                                        "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
                                        "code": "clinical-note"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-04-21T00:00:00+00:00",
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Imaging Report",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/b9f82cd0-6644-4b3f-a9d1-7585c3e71498/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "51a49fef-eb67-4b8d-a992-b3dd9e754dea",
                        "status": "current",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "51852-2",
                                    "display": "Letter"
                                }
                            ],
                            "text": "Letter"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "correspondence"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-21T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Letter",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/51a49fef-eb67-4b8d-a992-b3dd9e754dea/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "713394da-f250-4c59-8b47-96458155f687",
                        "status": "entered-in-error",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "clinical-note"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-22T00:00:00+00:00",
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/713394da-f250-4c59-8b47-96458155f687/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ],
                        "description": "Lab visit",
                        "context": {
                            "encounter": [
                                {
                                    "reference": "Encounter/aaefb326-8601-4c03-84d4-d6151b3a96bf",
                                    "type": "Encounter"
                                }
                            ],
                            "period": {
                                "start": "2024-02-21T21:52:42.777590+00:00",
                                "end": "2024-02-22T19:37:10.850120+00:00"
                            }
                        }
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "6ebf590d-ff90-412e-a5e7-9be30d6e4c35",
                        "status": "current",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "11488-4",
                                    "display": "Consult note"
                                }
                            ],
                            "text": "Consult note"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "referralreport"
                                    }
                                ]
                            },
                            {
                                "coding": [
                                    {
                                        "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
                                        "code": "clinical-note"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-22T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Consultancy Report",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/6ebf590d-ff90-412e-a5e7-9be30d6e4c35/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "d9a1304d-159d-4518-be88-3f9a1ea93cd1",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                                "valueString": "Disability form comment"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                                "valueDate": "2023-12-12"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                                "valueCode": "RN"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                                "valueReference": {
                                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                    "type": "Practitioner"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-priority",
                                "valueBoolean": false
                            }
                        ],
                        "status": "current",
                        "type": {
                            "text": "Disability Form"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "patientadministrativedocument"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-22T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Disability Form",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/d9a1304d-159d-4518-be88-3f9a1ea93cd1/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "bce56cc4-268a-4562-a699-16e8869415ad",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                                "valueString": "Hospital discharge summary comment"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                                "valueDate": "2024-01-14"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                                "valueCode": "AR"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                                "valueReference": {
                                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                    "type": "Practitioner"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-priority",
                                "valueBoolean": true
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-requires-signature",
                                "valueBoolean": false
                            }
                        ],
                        "status": "current",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "34105-7",
                                    "display": "Hospital Discharge summary"
                                }
                            ],
                            "text": "Hospital Discharge summary"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "uncategorizedclinicaldocument"
                                    }
                                ]
                            },
                            {
                                "coding": [
                                    {
                                        "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
                                        "code": "clinical-note"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-22T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/fdb06c59cecd43d095884222fcd93717",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Hospital Discharge Summary",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/bce56cc4-268a-4562-a699-16e8869415ad/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "d220fa24-2b2f-44cf-9843-5a1b681f0805",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                                "valueString": "Advance beneficiary comment"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                                "valueDate": "2024-02-13"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                                "valueCode": "RN"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                                "valueReference": {
                                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                    "type": "Practitioner"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-priority",
                                "valueBoolean": true
                            }
                        ],
                        "status": "current",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "53243-2",
                                    "display": "Advanced beneficiary notice"
                                }
                            ],
                            "text": "Advanced beneficiary notice"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "patientadministrativedocument"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-22T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Advanced Beneficiary Notice",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/d220fa24-2b2f-44cf-9843-5a1b681f0805/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "04a71b54-89b0-49bf-96be-60b5bdfa6450",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                                "valueString": "Handicap Parking Permit comment"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                                "valueDate": "2024-04-01"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                                "valueCode": "RN"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                                "valueReference": {
                                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                    "type": "Practitioner"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-priority",
                                "valueBoolean": true
                            }
                        ],
                        "status": "current",
                        "type": {
                            "text": "Handicap Parking Permit"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "patientadministrativedocument"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-22T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Handicap Parking Permit",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/04a71b54-89b0-49bf-96be-60b5bdfa6450/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "efe6c0d6-97c0-42a6-91ba-926a2dc3c66f",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-comment",
                                "valueString": "Disability form comment"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-clinical-date",
                                "valueDate": "2024-01-15"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-review-mode",
                                "valueCode": "RN"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-reviewer",
                                "valueReference": {
                                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                    "type": "Practitioner"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/document-reference-priority",
                                "valueBoolean": false
                            }
                        ],
                        "status": "current",
                        "type": {
                            "text": "Disability Form"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "patientadministrativedocument"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-22T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Disability Form",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/efe6c0d6-97c0-42a6-91ba-926a2dc3c66f/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "DocumentReference",
                        "id": "380ad499-ec8f-4f1f-b1f0-5f25b04fd574",
                        "status": "current",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "34895-3",
                                    "display": "Education note"
                                }
                            ],
                            "text": "Education note"
                        },
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/document-reference-category",
                                        "code": "educationalmaterial"
                                    }
                                ]
                            },
                            {
                                "coding": [
                                    {
                                        "system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
                                        "code": "clinical-note"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/c0df2c04a0e64b46ba7fe3f836068e49",
                            "type": "Patient"
                        },
                        "date": "2024-02-22T00:00:00+00:00",
                        "author": [
                            {
                                "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                "type": "Practitioner"
                            }
                        ],
                        "custodian": {
                            "reference": "Organization/00000000-0000-0000-0002-000000000000",
                            "type": "Organization"
                        },
                        "description": "Making a birth plan",
                        "content": [
                            {
                                "attachment": {
                                    "contentType": "application/pdf",
                                    "url": "https://fumage-example.canvasmedical.com/DocumentReference/380ad499-ec8f-4f1f-b1f0-5f25b04fd574/files/content"
                                },
                                "format": {
                                    "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
                                    "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
                                    "display": "mimeType Sufficient"
                                }
                            }
                        ],
                        "context": {
                            "encounter": [
                                {
                                    "reference": "Encounter/879b35fd-3bc2-4ccd-98d7-954dd9b6d0a9",
                                    "type": "Encounter"
                                }
                            ],
                            "period": {
                                "start": "2024-02-22T23:10:12.409838+00:00"
                            }
                        }
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Encounter

Source: https://docs.canvasmedical.com/api/encounter/

### 
An interaction between a patient and healthcare provider(s) for the purpose of providing healthcare service(s) or assessing the health status of a patient.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-encounter.html>  
**Encounter creation in Canvas**  
An encounter is associated with some of our notes in Canvas. For our default base notes, an encounter will be created with these note types:   
\- Lab visit   
\- Phone visit   
\- Telehealth visit   
\- Office visit   
\- Home Visit   
\- In-patient Visit   
With our [Configurable Note Types Feature](https://help.canvasmedical.com/articles/6785045644-appointment-event-note-types) all custom note types will be associated with an encounter by default.
### Endpoints
get/Encounter/{id} get/Encounter
get
/Encounter/{id}
#### Encounter read
Read an Encounter resource
### Path Parameters
id required
string
The unique identifier for the Encounter   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the encounter.
extension
array[json]
Canvas supports a note identifier extension on this resource for read and search interactions. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
identifier
array[json]
Identifier(s) by which this encounter is known.
Click to view child attributes
id
string
The identifier of the encounter.
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - http://canvasmedical.com
value
string
The value that is unique.
status
enum [ planned | cancelled | finished | in-progress ]
The status of the encounter.   
\- A `planned` encounter is an Appointment note that has not been check-in.   
\- A `cancelled` encounter is either 1) an Appointment that was cancelled or no-showed or 2) a Note that was deleted from the patient's chart.   
\- A `finished` encounter is a Note that has been locked at least once. Notes that are in an unlocked/ammended state, will have a finished status; however, they will not have a period.end datetime.   
\- An `in-progress` encounter is a note that has not yet been locked.
class
json
Classification of patient encounter.
Click to view child attributes
system
string
Identity of the terminology system.
**Value Options Supported:**
  - https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
type
array[json]
Specific type of encounter.   
In Canvas this will represent the Note Type the encounter is associated with. If the Note is in a `planned` status, the coding will correspond to Canvas' appointment note type until the note is checked-in and converted to the scheduled note type.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code.
display
string
The display name of the coding.
subject
json
The patient or group present at the encounter.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
participant
array[json]
List of participants involved in the encounter. Participants may include Practitioner references and RelatedPerson references for patient contacts associated with the encounter.
Click to view child attributes
type
array[json]
Role of participant in encounter.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-ParticipationType
code
string
The code.
**Value Options Supported:**
  - PART
display
string
The display name of the coding.
**Value Options Supported:**
  - Participation
period
json
Period of time during the encounter that the participant participated
Click to view child attributes
start
datetime
Starting time with inclusive boundary.
end
datetime
End time with inclusive boundary, if not ongoing.
individual
json
Persons involved in the encounter other than the patient. May reference a Practitioner or a RelatedPerson.
Click to view child attributes
reference
string
The reference string of the participant in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"` or `"RelatedPerson/3fcea5ee-8961-43b4-9d47-3e8a2a625e95"`.
type
string
Type the reference refers to (e.g. "Practitioner" or "RelatedPerson").
display
string
Text alternative for the resource (e.g Credendialed name of the Practitioner).
appointment
array[json]
The appointment that scheduled this encounter if applicable. If an appointment was rescheduled at any point within the Canvas UI, there may be multiple appointments in this array.
Click to view child attributes
reference
string
The reference string of the appointment in the format of `"Appointment/79f99d7d-2e55-41ec-8e39-01bd9408aacf"`.
type
string
Type the reference refers to (e.g. "Appointment").
period
json
The start and end time of the encounter.   
Appointment notes in Canvas will not have a period until the note is checked-in.   
Encounter notes will not have period.end datetime until the note is locked/signed.   
Notes that are in an unlocked/ammended state, will not have a period.end datetime until relocked/signed.
Click to view child attributes
start
datetime
Starting time with inclusive boundary.
end
datetime
End time with inclusive boundary, if not ongoing.
reasonCode
array[json]
Coded reason the encounter takes place.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://snomed.info/sct
code
string
The code.
**Value Options Supported:**
  - 308335008
display
string
The display name of the coding.
**Value Options Supported:**
  - Patient encounter procedure (procedure)
reasonReference
array[json]
Reason the encounter takes place (reference).   
In Canvas this represents the conditions that were **created** during the encounter, via the Diagnose command or another command that creates a condition.   
This list does **not** include conditions that were only assessed during the encounter. An Assess command records an assessment against a condition that already exists in the chart, and it does not change which encounter that condition belongs to, so an encounter whose only condition activity was an Assess returns an empty `reasonReference`. To retrieve the conditions assessed during an encounter, use the [Assessment](/sdk/data-assessment) model in the Canvas SDK, which links each assessment to both the note it was documented on and the condition it assessed. For the diagnoses associated with a billed service, use `diagnosis` and `item.diagnosisSequence` on the [Claim](/api/claim) resource.
Click to view child attributes
reference
string
The reference string of the condition in the format of `"Condition/e8921649-ec92-46b5-b663-8a4097c10513"`.
type
string
Type the reference refers to (e.g. "Condition").
hospitalization
json
Details about the admission to a healthcare service.
Click to view child attributes
dischargeDisposition
json
Category or kind of location after discharge.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/discharge-disposition
code
string
The code.
**Value Options Supported:**
  - oth
display
string
The display name of the coding.
**Value Options Supported:**
  - Other
location
array[json]
List of locations where the patient has been during the encounter.
Click to view child attributes
location
json
Location the encounter takes place.
Click to view child attributes
reference
string
The reference string of the location in the format of `"Location/3c01c6ea-b7dc-4109-9d1c-1cf4ba7c211e"`.
type
string
Type the reference refers to (e.g. "Location").
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Encounter
#### Encounter search
Search for Encounter resources
### Query Parameters
****
_id
string
A Canvas-issued unique identifier for a specific encounter.
appointment
string
The appointment that scheduled this encounter in the format `Appointment/6e5234c4-2dd0-495d-98cf-ad04add1316e`.
date
string
Filter by period.start time. See [Date Filtering](/api/date-filtering) for more information.
patient
string
The patient or group present at the encounter in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
subject
string
Encounter subject in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the encounter.
extension
array[json]
Canvas supports a note identifier extension on this resource for read and search interactions. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
identifier
array[json]
Identifier(s) by which this encounter is known.
Click to view child attributes
id
string
The identifier of the encounter.
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - http://canvasmedical.com
value
string
The value that is unique.
status
enum [ planned | cancelled | finished | in-progress ]
The status of the encounter.   
\- A `planned` encounter is an Appointment note that has not been check-in.   
\- A `cancelled` encounter is either 1) an Appointment that was cancelled or no-showed or 2) a Note that was deleted from the patient's chart.   
\- A `finished` encounter is a Note that has been locked at least once. Notes that are in an unlocked/ammended state, will have a finished status; however, they will not have a period.end datetime.   
\- An `in-progress` encounter is a note that has not yet been locked.
class
json
Classification of patient encounter.
Click to view child attributes
system
string
Identity of the terminology system.
**Value Options Supported:**
  - https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
type
array[json]
Specific type of encounter.   
In Canvas this will represent the Note Type the encounter is associated with. If the Note is in a `planned` status, the coding will correspond to Canvas' appointment note type until the note is checked-in and converted to the scheduled note type.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code.
display
string
The display name of the coding.
subject
json
The patient or group present at the encounter.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
participant
array[json]
List of participants involved in the encounter. Participants may include Practitioner references and RelatedPerson references for patient contacts associated with the encounter.
Click to view child attributes
type
array[json]
Role of participant in encounter.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-ParticipationType
code
string
The code.
**Value Options Supported:**
  - PART
display
string
The display name of the coding.
**Value Options Supported:**
  - Participation
period
json
Period of time during the encounter that the participant participated
Click to view child attributes
start
datetime
Starting time with inclusive boundary.
end
datetime
End time with inclusive boundary, if not ongoing.
individual
json
Persons involved in the encounter other than the patient. May reference a Practitioner or a RelatedPerson.
Click to view child attributes
reference
string
The reference string of the participant in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"` or `"RelatedPerson/3fcea5ee-8961-43b4-9d47-3e8a2a625e95"`.
type
string
Type the reference refers to (e.g. "Practitioner" or "RelatedPerson").
display
string
Text alternative for the resource (e.g Credendialed name of the Practitioner).
appointment
array[json]
The appointment that scheduled this encounter if applicable. If an appointment was rescheduled at any point within the Canvas UI, there may be multiple appointments in this array.
Click to view child attributes
reference
string
The reference string of the appointment in the format of `"Appointment/79f99d7d-2e55-41ec-8e39-01bd9408aacf"`.
type
string
Type the reference refers to (e.g. "Appointment").
period
json
The start and end time of the encounter.   
Appointment notes in Canvas will not have a period until the note is checked-in.   
Encounter notes will not have period.end datetime until the note is locked/signed.   
Notes that are in an unlocked/ammended state, will not have a period.end datetime until relocked/signed.
Click to view child attributes
start
datetime
Starting time with inclusive boundary.
end
datetime
End time with inclusive boundary, if not ongoing.
reasonCode
array[json]
Coded reason the encounter takes place.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://snomed.info/sct
code
string
The code.
**Value Options Supported:**
  - 308335008
display
string
The display name of the coding.
**Value Options Supported:**
  - Patient encounter procedure (procedure)
reasonReference
array[json]
Reason the encounter takes place (reference).   
In Canvas this represents the conditions that were **created** during the encounter, via the Diagnose command or another command that creates a condition.   
This list does **not** include conditions that were only assessed during the encounter. An Assess command records an assessment against a condition that already exists in the chart, and it does not change which encounter that condition belongs to, so an encounter whose only condition activity was an Assess returns an empty `reasonReference`. To retrieve the conditions assessed during an encounter, use the [Assessment](/sdk/data-assessment) model in the Canvas SDK, which links each assessment to both the note it was documented on and the condition it assessed. For the diagnoses associated with a billed service, use `diagnosis` and `item.diagnosisSequence` on the [Claim](/api/claim) resource.
Click to view child attributes
reference
string
The reference string of the condition in the format of `"Condition/e8921649-ec92-46b5-b663-8a4097c10513"`.
type
string
Type the reference refers to (e.g. "Condition").
hospitalization
json
Details about the admission to a healthcare service.
Click to view child attributes
dischargeDisposition
json
Category or kind of location after discharge.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/discharge-disposition
code
string
The code.
**Value Options Supported:**
  - oth
display
string
The display name of the coding.
**Value Options Supported:**
  - Other
location
array[json]
List of locations where the patient has been during the encounter.
Click to view child attributes
location
json
Location the encounter takes place.
Click to view child attributes
reference
string
The reference string of the location in the format of `"Location/3c01c6ea-b7dc-4109-9d1c-1cf4ba7c211e"`.
type
string
Type the reference refers to (e.g. "Location").
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Encounter/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Encounter/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Encounter",
            "id": "7720a218-c0bd-4cee-82a2-729bd9c101f3",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "identifier": [
                {
                    "id": "7720a218-c0bd-4cee-82a2-729bd9c101f3",
                    "system": "http://canvasmedical.com",
                    "value": "7720a218-c0bd-4cee-82a2-729bd9c101f3"
                }
            ],
            "status": "in-progress",
            "class": {
                "system": "https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html"
            },
            "type": [
                {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "308335008",
                            "display": "Office Visit"
                        }
                    ]
                }
            ],
            "subject": {
                "reference": "Patient/a1197fa9e65b4a5195af15e0234f61c2",
                "type": "Patient"
            },
            "participant": [
                {
                    "type": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
                                    "code": "PART",
                                    "display": "Participation"
                                }
                            ]
                        }
                    ],
                    "period": {
                        "start": "2022-04-04T05:26:34.711718+00:00"
                    },
                    "individual": {
                        "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                        "type": "Practitioner",
                        "display": "Canvas Support MD"
                    }
                }
            ],
            "period": {
                "start": "2022-04-04T05:26:34.711718+00:00"
            },
            "reasonCode": [
                {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "308335008",
                            "display": "Patient encounter procedure (procedure)"
                        }
                    ]
                }
            ],
            "reasonReference": [
                {
                    "reference": "Condition/b06982fa-9bcb-4695-a2f4-09cfdb21f03d",
                    "type": "Condition"
                },
                {
                    "reference": "Condition/e3df5e12-8ea4-46f8-922e-89a229945ef4",
                    "type": "Condition"
                },
                {
                    "reference": "Condition/266eae2b-4983-42b7-94ca-1397f80a7968",
                    "type": "Condition"
                }
            ],
            "hospitalization": {
                "dischargeDisposition": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/discharge-disposition",
                            "code": "oth",
                            "display": "Other"
                        }
                    ]
                }
            },
            "location": [
                {
                    "location": {
                        "reference": "Location/50ea08f9-f4a5-4315-90e3-10d38922daa8",
                        "type": "Location"
                    }
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
            "resourceType": "OperationOutcome",
            "issue": [
                {
                    "severity": "error",
                    "code": "not-found",
                    "details": {
                        "text": "Unknown Encounter resource '7d1ce256fcd7408193b0459650937a07'"
                    }
                }
            ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Encounter",
                        "id": "06e0ee68-59f8-4899-b906-1298a36870ab",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                                "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                            }
                        ],
                        "identifier": [
                            {
                                "id": "06e0ee68-59f8-4899-b906-1298a36870ab",
                                "system": "http://canvasmedical.com",
                                "value": "06e0ee68-59f8-4899-b906-1298a36870ab"
                            }
                        ],
                        "status": "finished",
                        "class": {
                            "system": "https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html"
                        },
                        "type": [
                            {
                                "coding": [
                                    {
                                        "system": "http://snomed.info/sct",
                                        "code": "308335008",
                                        "display": "Office Visit"
                                    }
                                ]
                            }
                        ],
                        "subject": {
                            "reference": "Patient/8f19219e36054ea89c4d98c9b258c2f1",
                            "type": "Patient"
                        },
                        "participant": [
                            {
                                "type": [
                                    {
                                        "coding": [
                                            {
                                                "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
                                                "code": "PART",
                                                "display": "Participation"
                                            }
                                        ]
                                    }
                                ],
                                "period": {
                                    "start": "2023-09-20T18:41:54.885110+00:00",
                                    "end": "2023-09-20T18:57:47.490741+00:00"
                                },
                                "individual": {
                                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                    "type": "Practitioner",
                                    "display": "Larry Weed"
                                }
                            }
                        ],
                        "period": {
                            "start": "2023-09-20T18:41:54.885110+00:00",
                            "end": "2023-09-20T18:57:47.490741+00:00"
                        },
                        "reasonCode": [
                            {
                                "coding": [
                                    {
                                        "system": "http://snomed.info/sct",
                                        "code": "308335008",
                                        "display": "Patient encounter procedure (procedure)"
                                    }
                                ]
                            }
                        ],
                        "reasonReference": [
                            {
                                "reference": "Condition/82e02680-c37d-4705-876d-b845d85efc20",
                                "type": "Condition"
                            }
                        ],
                        "hospitalization": {
                            "dischargeDisposition": {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/discharge-disposition",
                                        "code": "oth",
                                        "display": "Other"
                                    }
                                ]
                            }
                        },
                        "location": [
                            {
                                "location": {
                                    "reference": "Location/e332ff73-7fa4-4432-abe9-2adc43b1bb2c",
                                    "type": "Location"
                                }
                            }
                        ]
                    }
                },
                {
                    "resourceType": "Encounter",
                    "id": "f7663d7b-13bd-4236-843e-086306aea125",
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                            "valueId": "8c83a639-05c0-43e8-a39b-8b99ea75d7d2"
                        }
                    ],
                    "identifier": [
                        {
                            "id": "f7663d7b-13bd-4236-843e-086306aea125",
                            "system": "http://canvasmedical.com",
                            "value": "f7663d7b-13bd-4236-843e-086306aea125"
                        }
                    ],
                    "status": "planned",
                    "class": {
                        "system": "https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html"
                    },
                    "type": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "185418009",
                                    "display": "Method appointment made"
                                }
                            ]
                        }
                    ],
                    "subject": {
                        "reference": "Patient/8f19219e36054ea89c4d98c9b258c2f1",
                        "type": "Patient"
                    },
                    "participant": [
                        {
                            "type": [
                                {
                                    "coding": [
                                        {
                                            "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
                                            "code": "PART",
                                            "display": "Participation"
                                        }
                                    ]
                                }
                            ],
                            "individual": {
                                "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                "type": "Practitioner",
                                "display": "Canvas Support MD"
                            }
                        }
                    ],
                    "appointment": [
                        {
                            "reference": "Appointment/65463607-866c-4c6f-812f-bf8616a5f755",
                            "type": "Appointment"
                        },
                        {
                            "reference": "Appointment/6e5234c4-2dd0-495d-98cf-ad04add1316e",
                            "type": "Appointment"
                        }
                    ],
                    "reasonCode": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "308335008",
                                    "display": "Patient encounter procedure (procedure)"
                                }
                            ]
                        }
                    ],
                    "hospitalization": {
                        "dischargeDisposition": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/discharge-disposition",
                                    "code": "oth",
                                    "display": "Other"
                                }
                            ]
                        }
                    },
                    "location": [
                        {
                            "location": {
                                "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060",
                                "type": "Location"
                            }
                        }
                    ]
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Errors

Source: https://docs.canvasmedical.com/api/errors/

Canvas uses conventional HTTP response codes to indicate success or failure of an API request. In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a request wasn't found, etc.). Codes in the `5xx` range indicate an error with Canvas' server.
All `4xx` errors that could be handled programmatically (e.g., resource not found) include an [OperationOutcome](https://www.hl7.org/fhir/operationoutcome.html) that explains the error reported
Error Code| Description  
---|---  
200 - OK| Everything worked as expected.  
400 - Bad Request| The request was malformed or rejected by validation.  
401 - Unauthorized| No valid Bearer token provided.  
403 - Forbidden| Token bearer is forbidden from performing the operation.  
404 - Not Found| The requested resource doesn't exist.  
412 - Precondition Failed| A conditional request failed because the resource has been modified since the precondition was specified.  
422 - Unprocessable Entity| The request was syntactically correct but failed due to request semantics, database state, or a business rule.  
5XX - Server Error| Something went wrong on Canvas's end.  
**400**
    ```json
    {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "invalid",
          "details": {
            "text": "The request was malformed or failed validation."
          }
        }
      ]
    }
    ```
**401**
    ```json
    {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "unknown",
          "details": {
            "text": "Authentication failed"
          }
        }
      ]
    }
    ```
**403**
    ```json
    {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "forbidden",
          "details": {
            "text": "Authorization failed"
          }
        }
      ]
    }
    ```
**404**
    ```json
    {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "not-found",
          "details": {
            "text": "Unknown Patient resource 'a47c7b0ebbb442cdbc4adf259d148ea1'"
          }
        }
      ]
    }
    ```
**412**
    ```json
    {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "conflict",
          "details": {
            "text": "The resource has been modified since the precondition was specified."
          }
        }
      ]
    }
    ```
**422**
    ```json
    {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "business-rule",
          "details": {
            "text": "This appointment time is no longer available."
          }
        }
      ]
    }
    ```
**5XX**
    ```json
    {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "exception",
          "details": {
            "text": "Internal server error"
          }
        }
      ]
    }
    ```

---

# Goal

Source: https://docs.canvasmedical.com/api/goal/

### 
Describes the intended objective(s) for a patient, group or organization  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-goal.html>  
To learn more about how to create goals within the Canvas UI see this [Zendesk article](https://canvas-medical.help.usepylon.com/articles/6744190871-goals-command).
### Endpoints
get/Goal/{id} get/Goal
get
/Goal/{id}
#### Goal read
### Path Parameters
id required
string
The unique identifier for the Goal   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The Canvas identifier of the goal.
lifecycleStatus
enum [ proposed | planned | accepted | active | on-hold | completed | cancelled | entered-in-error | rejected ]
State the goal is in throughout its lifecycle.   
\- Goals that have been closed using a Close Goal Command will have a status of `completed`.   
\- Goal commands that were entered-in-error will have a status of `entered-in-error`.   
\- Goals that are not closed will have the `active` status.   
\- Goals with no lifecycle state set in Canvas will fall back to `accepted`.
achievementStatus
json
Describes progress made on goal, from **http://terminology.hl7.org/CodeSystem/goal-achievement**. This corresponds to the `Status` field on the latest committed goal related command.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/goal-achievement
code
string
The code.
**Value Options Supported:**
  - in-progress
  - improving
  - worsening
  - no-change
  - achieved
  - sustaining
  - not-achieved
  - no-progress
  - not-attainable
display
string
The display name of the coding.
priority
json
Level of importance associated with the reaching/sustaining goal, from **http://terminology.hl7.org/CodeSystem/goal-priority**. This corresponds to the `Priority` field on the latest committed goal related command.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/goal-priority
code
string
The code.
**Value Options Supported:**
  - high-priority
  - medium-priority
  - low-priority
display
string
The display name of the coding.
description
json
Human readable text of the goal.
Click to view child attributes
text
string
Plain text representation of the concept.
subject
json
Canvas Patient resource the goal is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
startDate
date
When goal pursuit begins.
target
array[json]
A single iteration of this field with the **dueDate** , if available. This corresponds to the `Due date` field on the latest committed goal related command.
Click to view child attributes
dueDate
date
Reach goal on or before.
expressedBy
json
Who created the goal, a **Practitioner** resource. This is the committer of the goal command in the patient's chart.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Practitioner").
note
array[json]
Comments about the goal and who wrote them. Notes correspond to any progress/barriers submitted on any of goal related commands.
Click to view child attributes
id
string
The Canvas identifier of the goal's note.
authorReference
json
Individual responsible for the annotation.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Practitioner").
time
datetime
When the annotation was made.
text
string
The annotation - text content.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Goal
#### Goal search
### Query Parameters
****
_id
string
A Canvas-issued unique identifier for a specific goal.
patient
string
Who this goal is intended for in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The Canvas identifier of the goal.
lifecycleStatus
enum [ proposed | planned | accepted | active | on-hold | completed | cancelled | entered-in-error | rejected ]
State the goal is in throughout its lifecycle.   
\- Goals that have been closed using a Close Goal Command will have a status of `completed`.   
\- Goal commands that were entered-in-error will have a status of `entered-in-error`.   
\- Goals that are not closed will have the `active` status.   
\- Goals with no lifecycle state set in Canvas will fall back to `accepted`.
achievementStatus
json
Describes progress made on goal, from **http://terminology.hl7.org/CodeSystem/goal-achievement**. This corresponds to the `Status` field on the latest committed goal related command.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/goal-achievement
code
string
The code.
**Value Options Supported:**
  - in-progress
  - improving
  - worsening
  - no-change
  - achieved
  - sustaining
  - not-achieved
  - no-progress
  - not-attainable
display
string
The display name of the coding.
priority
json
Level of importance associated with the reaching/sustaining goal, from **http://terminology.hl7.org/CodeSystem/goal-priority**. This corresponds to the `Priority` field on the latest committed goal related command.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/goal-priority
code
string
The code.
**Value Options Supported:**
  - high-priority
  - medium-priority
  - low-priority
display
string
The display name of the coding.
description
json
Human readable text of the goal.
Click to view child attributes
text
string
Plain text representation of the concept.
subject
json
Canvas Patient resource the goal is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
startDate
date
When goal pursuit begins.
target
array[json]
A single iteration of this field with the **dueDate** , if available. This corresponds to the `Due date` field on the latest committed goal related command.
Click to view child attributes
dueDate
date
Reach goal on or before.
expressedBy
json
Who created the goal, a **Practitioner** resource. This is the committer of the goal command in the patient's chart.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Practitioner").
note
array[json]
Comments about the goal and who wrote them. Notes correspond to any progress/barriers submitted on any of goal related commands.
Click to view child attributes
id
string
The Canvas identifier of the goal's note.
authorReference
json
Individual responsible for the annotation.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Practitioner").
time
datetime
When the annotation was made.
text
string
The annotation - text content.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Goal/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Goal/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Goal",
          "id": "e04a62f8-e6ab-46a1-af34-b635f901e37b",
          "lifecycleStatus": "active",
          "achievementStatus": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/goal-achievement",
                  "code": "improving",
                  "display": "Improving"
                }
              ]
          },
          "priority": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/goal-priority",
                  "code": "medium-priority",
                  "display": "Medium Priority"
                }
              ]
          },
          "description": {
              "text": "Drink more water"
          },
          "subject": {
              "reference": "Patient/f3d750f5d77d403c96baef6a6055c6e7",
              "type": "Patient"
          },
          "startDate": "2022-01-27",
          "target": [
            {
              "dueDate": "2023-09-28"
            }
          ],
          "expressedBy": {
              "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
              "type": "Practitioner"
          },
          "note": [
            {
              "id": "c2a45d52-b3d7-4e57-bb70-2b82b8819305",
              "authorReference": {
                  "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                  "type": "Practitioner"
              },
              "time": "2023-09-19T20:50:25.955348+00:00",
              "text": "Patient unable to find time to drink during work hours, shows signs of dehydration and fatigue"
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Goal resource 'a47c7b0ebbb442cdbc4adf259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Goal?patient=Patient/f3d750f5d77d403c96baef6a6055c6e7' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Goal?patient=Patient/f3d750f5d77d403c96baef6a6055c6e7"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 2,
            "link": [
            {
                "relation": "self",
                "url": "/Goal?patient=Patient/f3d750f5d77d403c96baef6a6055c6e7&_count=10&_offset=0"
              },
              {
                "relation": "first",
                "url": "/Goal?patient=Patient/f3d750f5d77d403c96baef6a6055c6e7&_count=10&_offset=0"
              },
              {
                "relation": "last",
                "url": "/Goal?patient=Patient/f3d750f5d77d403c96baef6a6055c6e7&_count=10&_offset=0"
              }
            ],
            "entry": [
              {
                "resource": {
                    "resourceType": "Goal",
                    "id": "d942b2b6-5c87-4f95-b7d6-51e2355aabf5",
                    "lifecycleStatus": "completed",
                    "achievementStatus": {
                        "coding": [
                          {
                            "system": "http://terminology.hl7.org/CodeSystem/goal-achievement",
                            "code": "improving",
                            "display": "Improving"
                          }
                        ]
                    },
                    "priority": {
                        "coding": [
                          {
                            "system": "http://terminology.hl7.org/CodeSystem/goal-priority",
                            "code": "medium-priority",
                            "display": "Medium Priority"
                          }
                        ]
                    },
                    "description": {
                        "text": "Eat one veggie a day"
                    },
                    "subject": {
                        "reference": "Patient/f3d750f5d77d403c96baef6a6055c6e7",
                        "type": "Patient"
                    },
                    "startDate": "2022-12-06",
                    "expressedBy": {
                        "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                        "type": "Practitioner"
                    },
                    "note": [
                      {
                        "id": "fe2365c7-1a87-43c3-8846-fc26349a8797",
                        "authorReference": {
                            "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                            "type": "Practitioner"
                        },
                        "time": "2022-12-06T17:21:25.172196+00:00",
                        "text": "Not going well only eat skittles"
                      }
                    ]
                }
              },
              {
                "resource": {
                    "resourceType": "Goal",
                    "id": "730e38b4-afaf-476c-914c-5eb0b2de405d",
                    "lifecycleStatus": "active",
                    "achievementStatus": {
                      "coding": [
                        {
                          "system": "http://terminology.hl7.org/CodeSystem/goal-achievement",
                          "code": "improving",
                          "display": "Improving"
                        }
                      ]
                    },
                    "description": {
                        "text": "Walk 3 steps each day"
                    },
                    "subject": {
                        "reference": "Patient/f3d750f5d77d403c96baef6a6055c6e7",
                        "type": "Patient"
                    },
                    "startDate": "2023-03-03",
                    "expressedBy": {
                        "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                        "type": "Practitioner"
                    }
                  }
              }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Group

Source: https://docs.canvasmedical.com/api/group/

### 
Represents a defined collection of entities that may be discussed or acted upon collectively but which are not expected to act collectively, and are not formally or legally recognized; i.e. a collection of entities that isn't an Organization.  
<https://hl7.org/fhir/R4/group.html>  
In Canvas Teams and Patient Groups are mapped to the FHIR Group resource.   
See this [Pylon article](https://canvas-medical.help.usepylon.com/articles/5123845479-teams) for information about creating teams in Canvas.  
See this [Pylon article](https://help.canvasmedical.com/articles/8319995182-patient-groups) for information about patient groups in Canvas.
### Endpoints
post/Group get/Group/{id} put/Group/{id} get/Group
post
/Group
#### Group create
Create a Group resource.  
**Note:** The Canvas implementation of Group create/update assigns responsibilities to practitioner Groups using the `characteristic` attribute, rather than using the `characteristic` attribute to establish membership.
### Attributes
resourceType
string
The FHIR Resource name.
type
string required
Identifies the broad classification of the kind of resources the group includes.   
A group with type `person` refers to a Patient Group in canvas, while a group of type `practitioner` refers to a Team in Canvas.
**Value Options Supported:**
  - person
  - practitioner
actual
boolean required
If true, indicates that the resource refers to a specific group of real individuals. If false, the group defines a set of intended individuals.   
While this is a required field in FHIR, Canvas assumes all groups are made up of real individuals, so this will be assumed True for all interactions.
name
string required
Label for Group.
characteristic
array[json]
Identifies traits whose presence or absence is shared by members of the group  
The `text` attribute on the `valueCodeableConcept` for each `characteristic` represents responsibilities held by the Group (in Canvas a Team). Responsibilities may not be shared by more than one team.
If a group of practitioners is created/updated with a responsibility that another group is assigned, the endpoint will return an error dictating the responsibilities have already been assigned.
Click to view child attributes
code
json required
Kind of characteristic
Click to view child attributes
text
string required
Plain text representation of the concept.
**Value Options Supported:**
  - responsibility
valueCodeableConcept
json required
Value held by characteristic.
Click to view child attributes
text
string
Plain text representation of the concept.   
These responsibilities represent the responsibilities of a Canvas Team. They are not applicable for a Patient Group.
**Value Options Supported:**
  - COLLECT_SPECIMENS_FROM_PATIENT
  - COMMUNICATE_DIAGNOSTIC_RESULTS_TO_PATIENT
  - COORDINATE_REFERRALS_FOR_PATIENT
  - PROCESS_REFILL_REQUESTS
  - PROCESS_CHANGE_REQUESTS
  - SCHEDULE_LAB_VISITS_FOR_PATIENT
  - POPULATION_HEALTH_CAMPAIGN_OUTREACH
  - COLLECT_PATIENT_PAYMENTS
  - COMPLETE_OPEN_LAB_ORDERS
  - REVIEW_ERA_POSTING_EXCEPTIONS
  - REVIEW_COVERAGES
member
array[json]
Who or what is in group.
Click to view child attributes
entity
json required
Reference to the group member.
Click to view child attributes
reference
string required
The reference string of the member in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/a09946c97cb04f44bc36f1c08f6d1b76"`.
type
string
Type the reference refers to (e.g. "Patient", "Practitioner").
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Group/{id}
#### Group read
Read a Group resource.
### Path Parameters
id required
string
The unique identifier for the Group   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Group.
type
string
Identifies the broad classification of the kind of resources the group includes.   
A group with type `person` refers to a Patient Group in canvas, while a group of type `practitioner` refers to a Team in Canvas.
**Value Options Supported:**
  - person
  - practitioner
actual
boolean
If true, indicates that the resource refers to a specific group of real individuals. If false, the group defines a set of intended individuals.   
While this is a required field in FHIR, Canvas assumes all groups are made up of real individuals, so this will be assumed True for all interactions.
name
string
Label for Group.
quantity
integer
Number of members.
characteristic
array[json]
Identifies traits whose presence or absence is shared by members of the group  
The `text` attribute on the `valueCodeableConcept` for each `characteristic` represents responsibilities held by the Group (in Canvas a Team). Responsibilities may not be shared by more than one team.
Click to view child attributes
code
json
Kind of characteristic
Click to view child attributes
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - responsibility
exclude
boolean
Group includes or excludes
**Value Options Supported:**
  - false
valueCodeableConcept
json
Value held by characteristic.
Click to view child attributes
text
string
Plain text representation of the concept.   
These responsibilities represent the responsibilities of a Canvas Team. They are not applicable for a Patient Group.
**Value Options Supported:**
  - COLLECT_SPECIMENS_FROM_PATIENT
  - COMMUNICATE_DIAGNOSTIC_RESULTS_TO_PATIENT
  - COORDINATE_REFERRALS_FOR_PATIENT
  - PROCESS_REFILL_REQUESTS
  - PROCESS_CHANGE_REQUESTS
  - SCHEDULE_LAB_VISITS_FOR_PATIENT
  - POPULATION_HEALTH_CAMPAIGN_OUTREACH
  - COLLECT_PATIENT_PAYMENTS
  - COMPLETE_OPEN_LAB_ORDERS
  - REVIEW_ERA_POSTING_EXCEPTIONS
  - REVIEW_COVERAGES
member
array[json]
Who or what is in group.
Click to view child attributes
entity
json
Reference to the group member.
Click to view child attributes
reference
string
The reference string of the member in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/a09946c97cb04f44bc36f1c08f6d1b76"`.
type
string
Type the reference refers to (e.g. "Patient", "Practitioner").
display
string
Text alternative for the resource.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Group/{id}
#### Group update
Update a Group resource.  
**Note:** The Canvas implementation of Group create/update assigns responsibilities to practitioner Groups using the `characteristic` attribute, rather than using the `characteristic` attribute to establish membership.
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The identifier of the Group.
type
string required
Identifies the broad classification of the kind of resources the group includes.   
A group with type `person` refers to a Patient Group in canvas, while a group of type `practitioner` refers to a Team in Canvas.
**Value Options Supported:**
  - person
  - practitioner
actual
boolean required
If true, indicates that the resource refers to a specific group of real individuals. If false, the group defines a set of intended individuals.   
While this is a required field in FHIR, Canvas assumes all groups are made up of real individuals, so this will be assumed True for all interactions.
name
string required
Label for Group.
characteristic
array[json]
Identifies traits whose presence or absence is shared by members of the group  
The `text` attribute on the `valueCodeableConcept` for each `characteristic` represents responsibilities held by the Group (in Canvas a Team). Responsibilities may not be shared by more than one team.
If a group of practitioners is created/updated with a responsibility that another group is assigned, the endpoint will return an error dictating the responsibilities have already been assigned.
Click to view child attributes
code
json required
Kind of characteristic
Click to view child attributes
text
string required
Plain text representation of the concept.
**Value Options Supported:**
  - responsibility
valueCodeableConcept
json required
Value held by characteristic.
Click to view child attributes
text
string
Plain text representation of the concept.   
These responsibilities represent the responsibilities of a Canvas Team. They are not applicable for a Patient Group.
**Value Options Supported:**
  - COLLECT_SPECIMENS_FROM_PATIENT
  - COMMUNICATE_DIAGNOSTIC_RESULTS_TO_PATIENT
  - COORDINATE_REFERRALS_FOR_PATIENT
  - PROCESS_REFILL_REQUESTS
  - PROCESS_CHANGE_REQUESTS
  - SCHEDULE_LAB_VISITS_FOR_PATIENT
  - POPULATION_HEALTH_CAMPAIGN_OUTREACH
  - COLLECT_PATIENT_PAYMENTS
  - COMPLETE_OPEN_LAB_ORDERS
  - REVIEW_ERA_POSTING_EXCEPTIONS
  - REVIEW_COVERAGES
member
array[json]
Who or what is in group.
Click to view child attributes
entity
json required
Reference to the group member.
Click to view child attributes
reference
string required
The reference string of the member in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/a09946c97cb04f44bc36f1c08f6d1b76"`.
type
string
Type the reference refers to (e.g. "Patient", "Practitioner").
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Group
#### Group search
Search for Group resources.
### Query Parameters
****
_id
string
The identifier of the Group.
type
string
The type of resources the group contains.
**Search Values Supported:**
  - person
  - practitioner
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Group.
type
string
Identifies the broad classification of the kind of resources the group includes.   
A group with type `person` refers to a Patient Group in canvas, while a group of type `practitioner` refers to a Team in Canvas.
**Value Options Supported:**
  - person
  - practitioner
actual
boolean
If true, indicates that the resource refers to a specific group of real individuals. If false, the group defines a set of intended individuals.   
While this is a required field in FHIR, Canvas assumes all groups are made up of real individuals, so this will be assumed True for all interactions.
name
string
Label for Group.
quantity
integer
Number of members.
characteristic
array[json]
Identifies traits whose presence or absence is shared by members of the group  
The `text` attribute on the `valueCodeableConcept` for each `characteristic` represents responsibilities held by the Group (in Canvas a Team). Responsibilities may not be shared by more than one team.
Click to view child attributes
code
json
Kind of characteristic
Click to view child attributes
text
string
Plain text representation of the concept.
**Value Options Supported:**
  - responsibility
exclude
boolean
Group includes or excludes
**Value Options Supported:**
  - false
valueCodeableConcept
json
Value held by characteristic.
Click to view child attributes
text
string
Plain text representation of the concept.   
These responsibilities represent the responsibilities of a Canvas Team. They are not applicable for a Patient Group.
**Value Options Supported:**
  - COLLECT_SPECIMENS_FROM_PATIENT
  - COMMUNICATE_DIAGNOSTIC_RESULTS_TO_PATIENT
  - COORDINATE_REFERRALS_FOR_PATIENT
  - PROCESS_REFILL_REQUESTS
  - PROCESS_CHANGE_REQUESTS
  - SCHEDULE_LAB_VISITS_FOR_PATIENT
  - POPULATION_HEALTH_CAMPAIGN_OUTREACH
  - COLLECT_PATIENT_PAYMENTS
  - COMPLETE_OPEN_LAB_ORDERS
  - REVIEW_ERA_POSTING_EXCEPTIONS
  - REVIEW_COVERAGES
member
array[json]
Who or what is in group.
Click to view child attributes
entity
json
Reference to the group member.
Click to view child attributes
reference
string
The reference string of the member in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"` or `"Practitioner/a09946c97cb04f44bc36f1c08f6d1b76"`.
type
string
Type the reference refers to (e.g. "Patient", "Practitioner").
display
string
Text alternative for the resource.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Group' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Group",
            "type": "practitioner",
            "actual": true,
            "name": "A Test Team",
            "characteristic": [
                {
                    "code": {
                        "text": "responsibility"
                    },
                    "valueCodeableConcept": {
                        "text": "COLLECT_SPECIMENS_FROM_PATIENT"
                    },
                    "exclude": false
                }
            ],
            "member": [
                {
                    "entity": {
                        "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39",
                        "type": "Practitioner"
                    }
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Group"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Group",
            "type": "practitioner",
            "actual": True,
            "name": "A Test Team",
            "characteristic": [
                {
                    "code": {
                        "text": "responsibility"
                    },
                    "valueCodeableConcept": {
                        "text": "COLLECT_SPECIMENS_FROM_PATIENT"
                    },
                    "exclude": False
                }
            ],
            "member": [
                {
                    "entity": {
                        "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39",
                        "type": "Practitioner"
                    }
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Group/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Group/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Group",
            "id": "3340c331-d446-4700-9c23-7959bd393f26",
            "type": "practitioner",
            "actual": true,
            "name": "A Test Team",
            "quantity": 1,
            "characteristic": [
                {
                    "code": {
                        "text": "responsibility"
                    },
                    "valueCodeableConcept": {
                        "text": "COLLECT_SPECIMENS_FROM_PATIENT"
                    },
                    "exclude": false
                }
            ],
            "member": [
                {
                    "entity": {
                        "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39",
                        "type": "Practitioner"
                    }
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Group resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/Group/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Group",
            "id": "3340c331-d446-4700-9c23-7959bd393f26",
            "type": "practitioner",
            "actual": true,
            "name": "A Test Team",
            "characteristic": [
                {
                    "code": {
                        "text": "responsibility"
                    },
                    "valueCodeableConcept": {
                        "text": "COLLECT_SPECIMENS_FROM_PATIENT"
                    },
                    "exclude": false
                }
            ],
            "member": [
                {
                    "entity": {
                        "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39",
                        "type": "Practitioner"
                    }
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Group/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Group",
            "id": "3340c331-d446-4700-9c23-7959bd393f26",
            "type": "practitioner",
            "actual": True,
            "name": "A Test Team",
            "characteristic": [
                {
                    "code": {
                        "text": "responsibility"
                    },
                    "valueCodeableConcept": {
                        "text": "COLLECT_SPECIMENS_FROM_PATIENT"
                    },
                    "exclude": False
                }
            ],
            "member": [
                {
                    "entity": {
                        "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39",
                        "type": "Practitioner"
                    }
                }
            ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Group resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Group?type=practitioner' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Group?type=practitioner"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Group?type=practitioner&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Group?type=practitioner&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Group?type=practitioner&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Group",
                        "id": "3340c331-d446-4700-9c23-7959bd393f26",
                        "type": "practitioner",
                        "actual": true,
                        "name": "A Test Team",
                        "quantity": 1,
                        "characteristic": [
                            {
                                "code": {
                                    "text": "responsibility"
                                },
                                "valueCodeableConcept": {
                                    "text": "COLLECT_SPECIMENS_FROM_PATIENT"
                                },
                                "exclude": false
                            }
                        ],
                        "member": [
                            {
                                "entity": {
                                    "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39",
                                    "type": "Practitioner"
                                }
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Immunization

Source: https://docs.canvasmedical.com/api/immunization/

### 
Describes the event of a patient being administered a vaccine or a record of an immunization as reported by a patient, a clinician or another party.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-immunization.html>  
In Canvas, Immunization records are recorded using either the [Immunization Statement Commmand](https://canvas-medical.help.usepylon.com/articles/1379672479-command-immunization-statement) or the [Immunize Command](https://canvas-medical.help.usepylon.com/articles/4155771468-command-immunize).
### Endpoints
post/Immunization get/Immunization/{id} put/Immunization/{id} get/Immunization
post
/Immunization
#### Immunization create
Immunization records created through this endpoint will be stored in an Immunization Statement command on the patient's chart. There currently is no support to create an Immunize command with this endpoint.
### Attributes
resourceType
string
The FHIR Resource name.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Canvas recommends sending the note identifier extension or the Encounter reference, but not both. If both are supplied, they must both refer to the same note. If neither is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.
Click to view child attributes
url
string required
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string required
The valueId field is used for the Note extension and will be the note's unique identifier.
status
enum [ completed | entered-in-error | not-done ] required
The status of the immunization.
**Value Options Supported:**
  - completed
vaccineCode
json required
Coding for the administered vaccine.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/cvx
  - http://www.ama-assn.org/go/cpt
code
string required
The code.
display
string
The display name of the coding.
patient
json required
The patient who received the immunization.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Supply an encounter reference to be able to insert the command into a specific note on the patient's timeline. If no encounter is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.   
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string required
The reference string of the encounter in the format of `"Encounter/76028e14e77a47f4b95149bf5b7400bb"`.
type
string
Type the reference refers to (e.g. "Encounter").
occurrenceDateTime
datetime required
The date or datetime the immunization was administered or reported to have been administered.
primarySource
boolean required
Whether the immunization was administered by a primary source.
On create accepts only **false**.
note
array[json]
Additional text not captured in other fields.   
Canvas will display this in the `comment` field of the immunization statement command. If there are multiple objects given, they will be separeted by a new line on the UI.
Click to view child attributes
text
string
The annotation - text content.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Immunization/{id}
#### Immunization read
### Path Parameters
id required
string
The unique identifier for the Immunization   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The Canvas identifier of the immunization.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
status
enum [ completed | entered-in-error | not-done ]
The status of the immunization.
**Value Options Supported:**
  - completed
  - entered-in-error
  - not-done
statusReason
json
A coding for reason not given, if recorded - omitted otherwise.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-ActReason
code
string
The code.
display
string
The display name of the coding.
vaccineCode
json
Coding for the administered vaccine.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/cvx
  - http://www.ama-assn.org/go/cpt
code
string
The code.
display
string
The display name of the coding.
patient
json
The patient who received the immunization.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
The encounter related to the provided Note in the extension of this resource.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/76028e14e77a47f4b95149bf5b7400bb"`.
type
string
Type the reference refers to (e.g. "Encounter").
occurrenceDateTime
datetime
The date or datetime the immunization was administered or reported to have been administered.
primarySource
boolean
Whether the immunization was administered by a primary source.
  - **true** indicates that the immunization was administered within the clinic. To document immunizations like these, use an [Immunize Command](https://canvas-medical.help.usepylon.com/articles/4155771468-command-immunize).  
\- **false** indicates that the immunization was administered outside the clinic. To document this immunizations like these, use an [Immunization Statement Command](https://canvas-medical.help.usepylon.com/articles/1379672479-command-immunization-statement).
note
array[json]
Additional text not captured in other fields.   
Canvas will display this in the `comment` field of the immunization statement command. If there are multiple objects given, they will be separeted by a new line on the UI.
Click to view child attributes
text
string
The annotation - text content.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Immunization/{id}
#### Immunization update
Update an Immunization resource.  
The only type of Immunization update interaction that is supported by Canvas is to mark an existing Immunization Statement as **entered-in-error** using the `status` attribute. No changes to other fields will be processed; however, required fields still need to be supplied.
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The Canvas identifier of the immunization.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string required
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string required
The valueId field is used for the Note extension and will be the note's unique identifier.
status
enum [ completed | entered-in-error | not-done ] required
The status of the immunization.
**Value Options Supported:**
  - entered-in-error
vaccineCode
json required
Coding for the administered vaccine.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/cvx
  - http://www.ama-assn.org/go/cpt
code
string required
The code.
display
string
The display name of the coding.
patient
json required
The patient who received the immunization.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
The encounter related to the provided Note in the extension of this resource.
Click to view child attributes
reference
string required
The reference string of the encounter in the format of `"Encounter/76028e14e77a47f4b95149bf5b7400bb"`.
type
string
Type the reference refers to (e.g. "Encounter").
occurrenceDateTime
datetime required
The date or datetime the immunization was administered or reported to have been administered.
primarySource
boolean required
Whether the immunization was administered by a primary source.
note
array[json]
Additional text not captured in other fields.   
Canvas will display this in the `comment` field of the immunization statement command. If there are multiple objects given, they will be separeted by a new line on the UI.
Click to view child attributes
text
string
The annotation - text content.
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Immunization
#### Immunization search
### Query Parameters
****
_id
string
A Canvas-issued unique identifier for a specific immunization.
patient
string
The patient for the vaccination record in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The Canvas identifier of the immunization.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
status
enum [ completed | entered-in-error | not-done ]
The status of the immunization.
**Value Options Supported:**
  - completed
  - entered-in-error
  - not-done
statusReason
json
A coding for reason not given, if recorded - omitted otherwise.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-ActReason
code
string
The code.
display
string
The display name of the coding.
vaccineCode
json
Coding for the administered vaccine.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/cvx
  - http://www.ama-assn.org/go/cpt
code
string
The code.
display
string
The display name of the coding.
patient
json
The patient who received the immunization.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
The encounter related to the provided Note in the extension of this resource.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/76028e14e77a47f4b95149bf5b7400bb"`.
type
string
Type the reference refers to (e.g. "Encounter").
occurrenceDateTime
datetime
The date or datetime the immunization was administered or reported to have been administered.
primarySource
boolean
Whether the immunization was administered by a primary source.
  - **true** indicates that the immunization was administered within the clinic. To document immunizations like these, use an [Immunize Command](https://canvas-medical.help.usepylon.com/articles/4155771468-command-immunize).  
\- **false** indicates that the immunization was administered outside the clinic. To document this immunizations like these, use an [Immunization Statement Command](https://canvas-medical.help.usepylon.com/articles/1379672479-command-immunization-statement).
note
array[json]
Additional text not captured in other fields.   
Canvas will display this in the `comment` field of the immunization statement command. If there are multiple objects given, they will be separeted by a new line on the UI.
Click to view child attributes
text
string
The annotation - text content.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Immunization' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
          {
            "resourceType": "Immunization",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "eb754467-c8fc-4eac-9f36-2f46a510b48f"
                }
            ],
            "status": "completed",
            "vaccineCode": {
                "coding": [
                    {
                        "system": "http://hl7.org/fhir/sid/cvx",
                        "code": "110"
                    },
                    {
                        "system": "http://www.ama-assn.org/go/cpt",
                        "code": "90723"
                    }
                ]
            },
            "patient": {
                "reference": "Patient/4d789a3d5e794c0eb159a126b48c8b9f",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/76028e14-e77a-47f4-b951-49bf5b7400bb"
            },
            "occurrenceDateTime": "2024-10-04",
            "primarySource": false,
            "note": [
              {
                "text": "First Dose"
              }
            ]
          }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Immunization"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json",
        }
        payload = {
            "resourceType": "Immunization",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "eb754467-c8fc-4eac-9f36-2f46a510b48f"
                }
            ],
            "status": "completed",
            "vaccineCode": {
                "coding": [
                    {
                        "system": "http://hl7.org/fhir/sid/cvx",
                        "code": "110"
                    },
                    {
                        "system": "http://www.ama-assn.org/go/cpt",
                        "code": "90723"
                    }
                ]
            },
            "patient": {
                "reference": "Patient/4d789a3d5e794c0eb159a126b48c8b9f",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/76028e14-e77a-47f4-b951-49bf5b7400bb"
            },
            "occurrenceDateTime": "2024-10-04",
            "primarySource": False,
            "note": [
              {
                "text": "First Dose"
              }
            ]
        }
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Immunization/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Immunization/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Immunization",
          "id": "d9aefede-da05-4bef-bbf9-63bcf83c806a",
          "extension": [
            {
                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                "valueId": "eb754467-c8fc-4eac-9f36-2f46a510b48f"
            }
          ],
          "status": "completed",
          "vaccineCode": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/sid/cpt",
                  "code": "91306",
                  "display": "Severe acute respiratory syndrome coronavirus 2 (SARS-CoV-2) (coronavirus disease [COVID-19]) vaccine, mRNA-LNP, spike protein, preservative free, 50 mcg/0.25 mL dosage, for intramuscular use"
                },
                {
                  "system": "http://hl7.org/fhir/sid/cvx",
                  "code": "207",
                  "display": "COVID-19, mRNA, LNP-S, PF, 100 mcg/0.5mL dose or 50 mcg/0.25mL dose"
                }
              ]
          },
          "patient": {
              "reference": "Patient/a1197fa9e65b4a5195af15e0234f61c2",
              "type": "Patient"
          },
          "encounter": {
            "reference": "Encounter/76028e14-e77a-47f4-b951-49bf5b7400bb"
          },
          "occurrenceDateTime": "2022-05-26T18:55:34.629659+00:00",
          "primarySource": false,
          "note": [
            {
              "text": "First Dose"
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Immunization resource 'd9aefede-da05-4bef-bbf9-63bcf83c806b'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/Immunization/d9aefede-da05-4bef-bbf9-63bcf83c806a' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
          {
            "resourceType": "Immunization",
            "id": "d9aefede-da05-4bef-bbf9-63bcf83c806a",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "eb754467-c8fc-4eac-9f36-2f46a510b48f"
                }
            ],
            "status": "entered-in-error",
            "vaccineCode": {
                "coding": [
                    {
                      "system": "http://hl7.org/fhir/sid/cpt",
                      "code": "91306",
                      "display": "Severe acute respiratory syndrome coronavirus 2 (SARS-CoV-2) (coronavirus disease [COVID-19]) vaccine, mRNA-LNP, spike protein, preservative free, 50 mcg/0.25 mL dosage, for intramuscular use"
                    },
                    {
                      "system": "http://hl7.org/fhir/sid/cvx",
                      "code": "207",
                      "display": "COVID-19, mRNA, LNP-S, PF, 100 mcg/0.5mL dose or 50 mcg/0.25mL dose"
                    }
                ]
            },
            "patient": {
                "reference": "Patient/4d789a3d5e794c0eb159a126b48c8b9f",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/76028e14-e77a-47f4-b951-49bf5b7400bb"
            },
            "occurrenceDateTime": "2024-10-04",
            "primarySource": False,
            "note": [
              {
                "text": "First Dose"
              }
            ]
          }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Immunization/d9aefede-da05-4bef-bbf9-63bcf83c806a"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json",
        }
        payload = {
            "resourceType": "Immunization",
            "id": "d9aefede-da05-4bef-bbf9-63bcf83c806a",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "eb754467-c8fc-4eac-9f36-2f46a510b48f"
                }
            ],
            "status": "entered-in-error",
            "vaccineCode": {
                "coding": [
                    {
                      "system": "http://hl7.org/fhir/sid/cpt",
                      "code": "91306",
                      "display": "Severe acute respiratory syndrome coronavirus 2 (SARS-CoV-2) (coronavirus disease [COVID-19]) vaccine, mRNA-LNP, spike protein, preservative free, 50 mcg/0.25 mL dosage, for intramuscular use"
                    },
                    {
                      "system": "http://hl7.org/fhir/sid/cvx",
                      "code": "207",
                      "display": "COVID-19, mRNA, LNP-S, PF, 100 mcg/0.5mL dose or 50 mcg/0.25mL dose"
                    }
                ]
            },
            "patient": {
                "reference": "Patient/4d789a3d5e794c0eb159a126b48c8b9f",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/76028e14-e77a-47f4-b951-49bf5b7400bb"
            },
            "occurrenceDateTime": "2024-10-04",
            "primarySource": False,
            "note": [
              {
                "text": "First Dose"
              }
            ]
        }
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Immunization resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Immunization?patient=Patient/4d9c4a797b8c4a58872017e7a19a474e' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Immunization?patient=Patient/4d9c4a797b8c4a58872017e7a19a474e"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
              {
                "relation": "self",
                "url": "/Immunization?patient=Patient%2F4d9c4a797b8c4a58872017e7a19a474e&_count=10&_offset=0"
              },
              {
                "relation": "first",
                "url": "/Immunization?patient=Patient%2F4d9c4a797b8c4a58872017e7a19a474e&_count=10&_offset=0"
              },
              {
                "relation": "last",
                "url": "/Immunization?patient=Patient%2F4d9c4a797b8c4a58872017e7a19a474e&_count=10&_offset=0"
              }
            ],
            "entry": [
              {
                "resource": {
                  "resourceType": "Immunization",
                  "id": "d9aefede-da05-4bef-bbf9-63bcf83c806a",
                  "extension": [
                    {
                      "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                      "valueId": "eb754467-c8fc-4eac-9f36-2f46a510b48f"
                    }
                  ],
                  "status": "completed",
                  "vaccineCode": {
                    "coding": [
                      {
                        "system": "http://hl7.org/fhir/sid/cpt",
                        "code": "91306",
                        "display": "Severe acute respiratory syndrome coronavirus 2 (SARS-CoV-2) (coronavirus disease [COVID-19]) vaccine, mRNA-LNP, spike protein, preservative free, 50 mcg/0.25 mL dosage, for intramuscular use"
                      },
                      {
                        "system": "http://hl7.org/fhir/sid/cvx",
                        "code": "207",
                        "display": "COVID-19, mRNA, LNP-S, PF, 100 mcg/0.5mL dose or 50 mcg/0.25mL dose"
                      }
                    ]
                  },
                  "patient": {
                      "reference": "Patient/4d9c4a797b8c4a58872017e7a19a474e",
                      "type": "Patient"
                  },
                  "encounter": {
                    "reference": "Encounter/76028e14-e77a-47f4-b951-49bf5b7400bb"
                  },
                  "occurrenceDateTime": "2021-12-01",
                  "primarySource": false
                }
              },
              {
                "resource": {
                  "resourceType": "Immunization",
                  "id": "d9aefede-da05-4bef-bbf9-63bcf83c806a",
                  "extension": [
                    {
                      "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                      "valueId": "eb754467-c8fc-4eac-9f36-2f46a510b48f"
                    }
                  ],
                  "status": "completed",
                  "vaccineCode": {
                    "coding": [
                      {
                          "system": "http://www.ama-assn.org/go/cpt",
                          "code": "90715",
                          "display": "TDAP VACCINE 7 YRS/> IM"
                      },
                      {
                          "system": "http://hl7.org/fhir/sid/cvx",
                          "code": "115",
                          "display": "Tdap"
                      }
                    ]
                  },
                  "patient": {
                      "reference": "Patient/4d9c4a797b8c4a58872017e7a19a474e",
                      "type": "Patient"
                  },
                  "encounter": {
                    "reference": "Encounter/76028e14-e77a-47f4-b951-49bf5b7400bb"
                  },
                  "occurrenceDateTime": "2021-12-01",
                  "primarySource": false,
                  "note": [
                    {
                      "text": "First Dose"
                    }
                  ]
                }
              }
            ]
        }
        ```

---

# Letter

Source: https://docs.canvasmedical.com/api/letter/

This API allows customers to create letters. The effect of creating a letter is the same as creating a letter in the user interface. Content can be added using HTML & CSS. Placeholders created in Canvas will not be respected.
##  Authentication 
The Letter API uses the existing Canvas OAuth authentication flow, so you can simply post to the existing auth token endpoint /auth/token/
This endpoint was built as an addition to the Note API, and creating a letter needs the `user/Note.write` scope. This scope will not be in OAuth applications that were created prior to the release of the Note API. To get access:
  - Create a new [OAuth application](/api/customer-authentication)
  - Ask Canvas to add the new scopes to an existing OAuth application
Like the Note API, the Letter API is a staff API. It refuses tokens with a patient context and tokens that act as a user who isn't a staff member, with `401 Unauthorized`. See [Tokens with a patient context](/api/customer-authentication/#tokens-with-a-patient-context).
![description](/assets/images/allowed-scopes.png)
    ```python
    import requests
    url = "https://<your-instance>.canvasmedical.com/auth/token/"
    payload = 'grant_type=client_credentials&client_id=canvas&client_secret=canvas'
    headers = {
      'Content-Type': 'application/x-www-form-urlencoded'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    print(response.text)
    ```
Then use your token in the request headers as you do with the FHIR API:
![description](/assets/images/note-api-token.png)
##  Create 
To create a Note resource, POST to `https://<your-instance>.canvasmedical.com/core/api/letter/v1/Letter` using the supported attributes below. Letters will be staged on the patient's chart to then be faxed or printed. Further edits can be made in the UI as needed.
###  Attributes 
**`patientKey` (req)** text  
The unique key of the Patient for which this letter is written.
* * *
**`providerKey` (req)** text  
The unique key of the Provider staff who is responsible for the letter.
* * *
**`practiceLocationKey` (req)** text  
The unique key of the PracticeLocation for which this letter is written.
* * *
**`content`**  
The contents of the letter. Supports HTML & CSS. **Placeholders created in Canvas will NOT be respected.**
###  Example 
    ```python
    import requests
    import json
    url = "https://<your-instance>.canvasmedical.com/core/api/letter/v1/Letter"
    payload = json.dumps({
      "patientKey": "8d84776879de49518a4bc3bb81d96dd4",
      "providerKey": "5eede137ecfe4124b8b773040e33be14",
      "practiceLocationKey": "c67e0c59-d4d2-428c-bc13-b6e85d181ad0",
      "content": "<p>To Whom It May Concern,</p><p>Letty Letters is a patient of mine at PRACTICE NAME. Due to a current medical condition, the patient is unable to fulfill the requirements for jury duty.</p><p>Thanks,</p></div><div class=\"signature\"><img src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/b/be/Zhu_Zhengting_signature.jpg/1280px-Zhu_Zhengting_signature.jpg\" alt=\"Signature\" width=\"200\"></div></div></html>"
    })
    headers = {
      'Authorization': 'Bearer HqFtbSnBNX4S65VhRrg8sRxO6XcSFp',
      'Content-Type': 'application/json'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    print(response.text)
    ```
##  Populating a letter with chart data 
Letter Template placeholders cannot reach command values or ICD codes from a note; only the fixed set of patient, provider, and practice placeholders is supported. To produce a letter populated with chart data, command values, or ICD codes, build the letter's content in a plugin from values you read through the SDK [data module](/sdk/data/), then create the letter with this API.

---

# Location

Source: https://docs.canvasmedical.com/api/location/

### 
Details and position information for a physical place where services are provided and resources and participants may be stored, found, contained, or accommodated.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-location.html>  
The FHIR Location resource corresponds to Canvas Practice Locations.
### Endpoints
get/Location/{id} get/Location
get
/Location/{id}
#### Location read
Read a Location resource.
### Path Parameters
id required
string
The unique identifier for the Location   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Location
identifier
array[json]
Unique code or number identifying the location to its users. Currently this supports displaying the Group NPI.
Click to view child attributes
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/us-npi
value
string
The value that is unique.
status
enum [ active | inactive ]
The status property covers the general availability of the resource, not the current value which may be covered by the operationStatus, or by a schedule/slots if they are configured for the location.
name
string
Name of the location as used by humans. This is the practice location's full name in Canvas.
alias
array[string]
A list of alternate names that the location is known as, or was known as, in the past. This is the practice location's short name in Canvas.
description
string
Additional details about the location that could be displayed as further information to identify the location beyond its name. Canvas will produce this in the format `Organization full name: Location full name`
address
json
Physical location.
Click to view child attributes
use
enum [ home | work | temp | old | billing ]
Purpose of this address
type
enum [ both | physical | postal ]
Distinguishes between physical and postal addresses.
line
array[string]
Street name, number, direction & P.O. Box etc. This repeating element order: The order in which lines should appear in an address label.
city
string
Name of city, town etc.
state
string
Sub-unit of country (Canvas uses abbreviations).
postalCode
string
Postal code for area.
country
string
Country
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Location
#### Location search
Search for Location resources.
### Query Parameters
****
_id
string
The identifier of the Location.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Location
identifier
array[json]
Unique code or number identifying the location to its users. Currently this supports displaying the Group NPI.
Click to view child attributes
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/us-npi
value
string
The value that is unique.
status
enum [ active | inactive ]
The status property covers the general availability of the resource, not the current value which may be covered by the operationStatus, or by a schedule/slots if they are configured for the location.
name
string
Name of the location as used by humans. This is the practice location's full name in Canvas.
alias
array[string]
A list of alternate names that the location is known as, or was known as, in the past. This is the practice location's short name in Canvas.
description
string
Additional details about the location that could be displayed as further information to identify the location beyond its name. Canvas will produce this in the format `Organization full name: Location full name`
address
json
Physical location.
Click to view child attributes
use
enum [ home | work | temp | old | billing ]
Purpose of this address
type
enum [ both | physical | postal ]
Distinguishes between physical and postal addresses.
line
array[string]
Street name, number, direction & P.O. Box etc. This repeating element order: The order in which lines should appear in an address label.
city
string
Name of city, town etc.
state
string
Sub-unit of country (Canvas uses abbreviations).
postalCode
string
Postal code for area.
country
string
Country
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Location/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Location/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Location",
            "id": "a04b44ec-c7df-4808-9043-e9c4b1d352a9",
            "identifier": [
                {
                    "system": "http://hl7.org/fhir/sid/us-npi",
                    "value": "12321"
                }
            ],
            "status": "active",
            "name": "Canvas Medical",
            "alias": [
                "Canvas Medical HQ"
            ],
            "description": "Canvas Medical, San Francisco, CA",
            "address": {
                "use": "work",
                "line": [
                    "405 49th St"
                ],
                "city": "Oakland",
                "state": "CA",
                "postalCode": "94609",
                "country": "USA"
            }
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Location resource 'a04b44ec-c7df-4808-9043-e9c4b1d352a9'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Location' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Location"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Location?_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Location?_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Location?_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Location",
                        "id": "a04b44ec-c7df-4808-9043-e9c4b1d352a9",
                        "identifier": [
                            {
                                "system": "http://hl7.org/fhir/sid/us-npi",
                                "value": "12321"
                            }
                        ],
                        "status": "active",
                        "name": "Canvas Medical",
                        "alias": [
                            "Canvas Medical HQ"
                        ],
                        "description": "Canvas Medical, San Francisco, CA",
                        "address": {
                            "use": "work",
                            "line": [
                                "405 49th St"
                            ],
                            "city": "Oakland",
                            "state": "CA",
                            "postalCode": "94609",
                            "country": "USA"
                        }
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Media

Source: https://docs.canvasmedical.com/api/media/

### 
A photo, video, or audio recording acquired or used in healthcare.  
<https://hl7.org/fhir/R4/media.html>  
FHIR Media maps to a [Visual Exam Finding Command](https://canvas-medical.help.usepylon.com/articles/4119751144-command-visual-exam-finding) in Canvas.
### Endpoints
post/Media get/Media/{id} get/Media
post
/Media
#### Media create
Create a Media resource.
### Attributes
resourceType
string
The FHIR Resource name.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Canvas recommends sending the note identifier extension or the Encounter reference, but not both. If both are supplied, they must both refer to the same note. If neither is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.
Click to view child attributes
url
string
Source that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
status
string required
The current state of the media.
**Value Options Supported:**
  - completed
  - entered-in-error
subject
json required
Who/What this Media is a record of.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter associated with media.
Supply an encounter reference to be able to insert the Visual Exam Finding command into a specific note on the patient's timeline. If no encounter is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.   
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/086cd6fe-2c94-455d-a53e-6ff1c2652cae"`.
type
string
Type the reference refers to (e.g. "Encounter").
operator
json
The person who generated the image.  
The operator attribute contains a reference to the practitioner or patient that generated the media. This will show up in the Canvas UI as the value for Originator when you click the command in the tooltip that pops up. If omitted, it will default to Canvas Bot.
Click to view child attributes
reference
string
The reference string of the operator in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Practitioner").
content
json required
Actual Media.
Click to view child attributes
contentType
string required
Mime type of the content, with charset etc.
**Value Options Supported:**
  - image/heic
  - image/jpeg
  - image/png
data
string required
Inline data in Base64 format.
title
string
Label to display in place of the data. This will appear on the Visual Exam Finding Command in the patient's chart.
note
array[json]
Comments made about the media  
The note attribute is an array of JSON objects, each of which contains a text attribute that contains the text of a comment that will be attached to the inserted media on the UI.
Click to view child attributes
text
string required
The annotation - text content.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Media/{id}
#### Media read
Read a Media resource.
### Path Parameters
id required
string
The unique identifier for the Media   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Media.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Source that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
status
string
The current state of the media.
**Value Options Supported:**
  - completed
  - entered-in-error
subject
json
Who/What this Media is a record of.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter associated with media.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/086cd6fe-2c94-455d-a53e-6ff1c2652cae"`.
type
string
Type the reference refers to (e.g. "Encounter").
operator
json
The person who generated the image.  
The operator attribute contains a reference to the practitioner or patient that generated the media. This will show up in the Canvas UI as the value for Originator when you click the command in the tooltip that pops up. If omitted, it will default to Canvas Bot.
Click to view child attributes
reference
string
The reference string of the operator in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Practitioner").
content
json
Actual Media.
Click to view child attributes
contentType
string
Mime type of the content, with charset etc.
**Value Options Supported:**
  - image/heic
  - image/jpeg
  - image/png
title
string
Label to display in place of the data. This will appear on the Visual Exam Finding Command in the patient's chart.
url
string
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
note
array[json]
Comments made about the media  
The note attribute is an array of JSON objects, each of which contains a text attribute that contains the text of a comment that will be attached to the inserted media on the UI.
Click to view child attributes
text
string
The annotation - text content.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Media
#### Media search
Search for Media resources.
### Query Parameters
****
_id
string
The identifier of the Media.
patient
The patient the media is associated with in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Media.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Source that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
status
string
The current state of the media.
**Value Options Supported:**
  - completed
  - entered-in-error
subject
json
Who/What this Media is a record of.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter associated with media.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/086cd6fe-2c94-455d-a53e-6ff1c2652cae"`.
type
string
Type the reference refers to (e.g. "Encounter").
operator
json
The person who generated the image.  
The operator attribute contains a reference to the practitioner or patient that generated the media. This will show up in the Canvas UI as the value for Originator when you click the command in the tooltip that pops up. If omitted, it will default to Canvas Bot.
Click to view child attributes
reference
string
The reference string of the operator in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Practitioner").
content
json
Actual Media.
Click to view child attributes
contentType
string
Mime type of the content, with charset etc.
**Value Options Supported:**
  - image/heic
  - image/jpeg
  - image/png
title
string
Label to display in place of the data. This will appear on the Visual Exam Finding Command in the patient's chart.
url
string
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
note
array[json]
Comments made about the media  
The note attribute is an array of JSON objects, each of which contains a text attribute that contains the text of a comment that will be attached to the inserted media on the UI.
Click to view child attributes
text
string
The annotation - text content.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Media' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Media",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "status": "completed",
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "operator": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "content": {
                "contentType": "image/jpeg",
                "data": "/9j/4AAQSkZJRgABAQAASABIAAD/4QCMRXhpZgAATU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAASgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAABIAAAAAQAAAEgAAAABAAOgAQADAAAAAQABAACgAgAEAAAAAQAAAOSgAwAEAAAAAQAAAUAAAAAA/+0AOFBob3Rvc2hvcCAzLjAAOEJJTQQEAAAAAAAAOEJJTQQlAAAAAAAQ1B2M2Y8AsgTpgAmY7PhCfv/AABEIAUAA5AMBIgACEQEDEQH/xAAfAAABBQEBAQEBAQAAAAAAAAAAAQIDBAUGBwgJCgv/xAC1EAACAQMDAgQDBQUEBAAAAX0BAgMABBEFEiExQQYTUWEHInEUMoGRoQgjQrHBFVLR8CQzYnKCCQoWFxgZGiUmJygpKjQ1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4eLj5OXm5+jp6vHy8/T19vf4+fr/xAAfAQADAQEBAQEBAQEBAAAAAAAAAQIDBAUGBwgJCgv/xAC1EQACAQIEBAMEBwUEBAABAncAAQIDEQQFITEGEkFRB2FxEyIygQgUQpGhscEJIzNS8BVictEKFiQ04SXxFxgZGiYnKCkqNTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqCg4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2dri4+Tl5ufo6ery8/T19vf4+fr/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/3QAEAA//2gAMAwEAAhEDEQA/APPNzscLnHsKFRs9/wATWisaY5yackKA8ITXiOqex7NFVYcjPFQzW5JGAx+nFbSxHGAn6U2W03kFhyPepdQ0hFJlC1tpWUAL0PUmtG08yzdWbb16ipba0G3AVifTFX4tOdx9zg+vFJVbM0kk1YqahqN7FbNLp5UOeWRlzn3Fc23iTV5/kWaQknpGnP6V3FrpWzLTsGA6AVdT7LEMbo0I6YAr0KeYcqs1c8urgVKV0ebGPXLw8RXsmfXIH61PH4Y1efG9I4x6ySc/pXoL3cC8Lvc+wqlPOzuTGHAPYkYqZZjN7IuGXw6nKJ4Ol2j7RfRrjsiZx+dWI/CemRjM89xN/wAC2j9K2J3mYAAIR7VGltNL/wAtNoFYSxlV9TpjgqS6FSLR9IgGY7NH7bnJb+dWR9ktuI0gjH+yBSvZIoJkm/WoWSzQDncawlVlLds3jQhHZDZb9c4jOR7LUD3Dt0Rz9TintcQp9xM0gu8rnaq1FzRRK7ySsMEKF9CM1X+zknOW/AVYlu2I+/j6Cqz3APVmP44pXZaih4tyB93n/aNIYDkZdR6Ypolb+Afj1pv71sEcUXHZFiO23MoLMad9lxIdoNVP3qydTVxZbg9FJ/2jSbYiX7MwwM4pTaAjDSnGOmTTMTEjcyj8aeIst802PwqOZgOFnCACSv8AOmy28Y5ErfQCp0SBRksSfrSSTwp91Rn3p8zGVHQ9FaT1zxU0UjL2pxuTjCpgfTFRE7j2H0rObuVEV5W3df0pPNf+9+lMKUbKgo//0MX7Ds+8yCnrHbRnEk4/Cs6QlpMZJ78mkUEc4FfOM95Rua6PZA8b5CPale7jUfuoAP8AeNUITnrtz25xVjygV+bbUtjUUieG+mJ+VY1z7VL58rDDzkH0FU4UijkBLgmr6xllyoIGMdMU4o0dkVlOSdwdvc0rSBRwUWoTCqyku4PsOTTmijxnyZHx+AqrhZEUkhYn9630WljdiRtDMRTlkAGEiSMfTNL5rMvDOf8AdGKeo7oXM6jKgLxVWRrhjh5kH0Of5VKUlb7sOf8Ae/8Ar0eVdEdEUf72KEguRBBjpI/vgAVRl2iTb8oY9s9K0RbMpy03XsBnFDWanH3mJ6Gmog5WMO6uI7dczSBFOQT6UWl1a3dtmCUv/ujimeL4YorGNTHvMjAbcdB6k1wd5cyWeoMlm7QMuSAuSpP06H6V6FLBqcL9TzquNcJ2Wx6CYyQdsR/4EaTymyMFF/CuGs/Eup3jMsbIHVCzBhjOOuP8O1WbfxXG0qJcwuAwGW39PY/jxWE8FUjsdEMbSlvodoDGv3paaJ4gflVmx0xWbaXtvcRq0XAJxyOass+xckcZxzXLOnKOjR1RnCXwssvcnIIAHtmk8+Q9z+VVopfMOEIz9amELtyZMfQVlYq6FaRj952x9adFKmfvZphjiXmRh9Gap7cQqQQV/AUJBcn8xQPmwPrQpDDKkY9aWS5hA+Zl/OqkmowL90Z7cVoqcpbIzlVit2WwqEkGQMfQc1Iir/dJPuaxX1QDd5car9ag/tGZ/wCPA9qv6nOW5k8ZTj5nQHrwFFHP+x+Vc+biQ8+a350nnyf89G/OtPqL7mf1+PY//9HlJnJUbWI/3RURt1kOTvJ/3uKvQ2pEY3MCe9FtEhTdgsD3r5xytsfQWILWzVeQOa04rfcBjOPc0qlEHRfxqwlxwMEY9hWcpMdhkdpsPAx/u1owxYHIH4mqJnIJIDEe/akF0emD+FKMmVYusiJycfgKQug9aqGRmJ/SjcqQvNM4SJRngda1p03N2QpSUFdhIYIQzmNQByT1ri9Z8RNJeMlvI8cK8AIME+/HatNGufEmoLbWTyRW5OAEGWb1JPYV1T+GLHT7GNWG+U9AfmYn+lexRw6oq8tWeVVrus7R0R5/D4jvbZMzCR0Bxh1z+tdz4Md9alQqiyFtpCr1Kk85HpiuVvdNk1W4FvaqRGzFRKoyAR0r2j4X6CmjWUUsiBWJLFV6IT1I7gZ7V0LD05Lma1MHiakHa5h3vhs2l4d6sIpMqCR93Jxir2saJHbWcTIgbY21jjn6/Su51t0kbAUFZB17Zqstl9stZYyMsE7j9fyNOOHgtkKWKm9zwfx3p7SWmWBhWOQAkj+E8V5drtnJHIPKQqNoKn0OcbjX1Vq3hZboSs0YeQZHz96xZfhbDfRSz31wY4gqxxRqo5Pp7iuiEUlY55Tu7ny9dW8trL5sIYGeMhscYVu3t0qSxsZUulnaLCYyDL8q57/UV9Px/CTTIg0rrJPMBkbuQretcN4s8NGCxmN3HEjQuRlPvBT6+9E1bYujabszyz+x7t4hIlwVycDylKj/AOvWrpdzJa3sdlqEoeVovMQsPmA9T/StjQIpHuYbY8I6l4/6Vj+IdJnj1gXRDFwe469v/wBVcdWKmmmdqbotSRpTXEEZGw5b/eqL7cx48w/QCsyWPY3UZ68dqZvC98AetcKw0VubyxU3sXbi5AO4qC3qeaYLuQ/ecnNZ012i8buaqNfkMFTDNnHFbxpJbI551ZS3ZveaT35PrR5gIw3Ws2KYsoLsxx1xWjBcwfL5iD3J6VooGLkAkQDkin716dM9Peo5Lq35XyV9ivcVOJ7Ty8pbtj34quUTY3ap6sRRsX+/R5lo3LBs/U0b7P0f8zRysLn/0sKMsynH8qaqso2gYA9amt42B+9j6VM0A98+ua+VbPpSsIWYfM549BVlUCqDjjvzT4o1JCkkn3NWUQBcbanmFYpvIoPysMntUJmVS3OT6YqZrMByzOFX0pPLhi5DCqGkNhMkoxtIOME+1Yfii4M95FYRvjbgsM9fyrovtAjhZxgBQTXn+mPJqV1d3G4jzN370DkduPyFe1l8LJzkjzMfO9oRNfw3qGqQassWlpEtgi7Wdl+99K39avpZpILM3WLlwS+xM7V/Cuf0vU7jRLIwSwRSopysoOMfX3q9osz6vqnmW5C3DEYypbA/CvRT5nc4U1CNup3/AMPdCe3XfLOs0AJbITBJPbmvQIJWkcpGdq44DcflVLRbBbLTI4C5kbGWZu5q20UYH7tMtn7v+FXcwk7l6wCtO1vcjcHHDD17VppbPZeSyLlBlH/pWRb/AL7A5WQnjP8AjXQ2D+Y4hZy3mIeo9KpEspXn7woFAUsxJPtVqF1uBwmYkYRrn+I1CkAkZI2ztVOfUZOK2IbRAqbWCpH8qj09T9aptIncYbcDhVLnuRiuS8X+G49YsJomgJZhyGI5ruLWBEYiJwFPPPc1b+zow5A9+KlyHG6dz5T8QeH4tBFm5DGZpMAddqjpn2pNUi06WGZ7hYw4Qk8V6p8U9FntZDPDA0trICSAuSp+uK8K1C6kMro8ZWIDO1uGb3x1rCpHqdiq8yszjLlx5rMpO0ms66uAoIyK37y1inBMQCHPJUcY9cVy2owPHJ91jGej9jXPYq5CXDBjuA+nNLb481RgnPQ1HswBnnPUUAbeR909qpC3NtBtK7l254JzQSCxxhVIyBVSC4dxnO7PUEc1O8sYUkj5h1B4IpkkgUnozY9M96VX2swb8M9v/rVCkzBiAA3cNUnmbuRjdnkUCJ2PJ2ybfYUm4/8APU/lVSR9xBI3nHXFMyP+ef6U7isf/9PK81Iyd0g/Ckkvrfb1yfzrDKqRjqT0zTtu1duMHrXhrA92exLGR6I1W1LbxFExB6E8U1tQlHDDbmszcQMAs3qMUvm/Ke56etbxwdNGUsXN7E5vncsFIGDjPWoPMaRiGJY549qYWLAngDuMU6JVDA43Aen6VvGlCOyMpVpy3Za1OHytGlg80iSYbSR2z2rIt0SGIRxngdeOtX7mWadl81AFXgBT7daoOMMO3PBFbOXRGVurHqdwZZF3IeMEV23wlt4IpbmCdw7k713LwBXDrIBwc8cV6D8K4EudSlZ22hV4NXTk9iJxVrnpV1PDDACM/U8D8K5ifW7mM77lUs7Z2+WadwqsPxOa3/EELiyne1VJJIkLokh4bA6V8q65dS6xefb9Tlnu55GLYZgCn/TNc5CL06Dp6mumCOZn0lB4kt5ruBBKqyA4Zd+5TjowNd34avxc6n8pDqqszEdu1fI1vfw2en2V7ZxXFvas5hkWWUOPMVdzsrf3McduR0619HeC7tNP8O3N3dNsMjAAtx8g55+tXy2Ym9D0B5FTU1yv7tgQx9OeKyZNYlgtpnY5UMRyf881Wk1RZb+KVmPkyEZI7GuT+Jl0umWt7MGdYAPPOznngnHvx096JRuKDsdSdcjYOsF0GnXB4PGfQetdb4b1Ke5iCXagSjr718i65G411UvX1CR3UStFalBtLD92oLHBBGcnjBFev/AHVb+W5vNOnnlmi8tZ44ZH3+RyQVVjyQcEjJ47cUpRshrVntmtRwPplwbtgkKoWZycBQO9fIHi+a0utXup7BRFbyOcdSWA6MT7/pX1X46VpPB+pqkwiPkt85OK+P8AVG/fOVbcuMsBwR/Q1zzeljaC1uZzLuc4wrMSeOlUrmAyRY4OOqd/xFWXYrCrHYeMg+uPaqbTksCoLHbjbnkEdxXO2a2MLUdPZWBtgXBySueRWZgqMHdkdcjBrqd6vkr8r5wxxwfr70y9t1uvvgK4GC2OeKdwRzkMjRkFSVPQ1ceSKRAwKt7d80y8sJ7bDMNydcj0qtbNHFKMgYJ7800waLSMM5UN6+mKkYFyWHDE9KZLcKvbrxkVXeZlJIG7+dUTYlJyxyxB9M4o4/vn/vqoo7lWGQ3/AI6DTvPH97/xwUwP/9TjdxEnC4wepqYSA8sxByMDGc+tR+WzksB09T3pgUqcuxB7c1zG5MJdnXkk4ORUMj4bKjOetPcgEeU3JGTmojIxcgjkjOcUDQ1yMl1Yqw4IByKUPgcAk9M0z5cjHGe/oalChQckkfWkUkR+YwJ9DTZj0AOD6GnYGSQeDzzTRG80qrGmSxAUL1zQtRjEBOG28cc16H8MpoRf+WJQsmCSrLwfoaydI8LCRS1xMNy8BAOD+NdfpVvb2Bh+zxqEY8kDOR/OtYqxnN3Ru+K5Xt7N9v3ACcpwenvXht7pmmam7efHJHdE/MyNtDnqSBXu2sQ/aLBgSWymBXA6b4WWHMly4DAnaAOnPAFbxkkjFK5xGm6Q13e28V3aGKziyVLSliF6kFTxg121zfTDTbe0jkAjUD92WBAXt/Wpbu1WGGRp2CS7sfuxndWPawHyZfJTEof5zIcEk8gj61akJxOv0jVZJ7dYWYBVTHoRyAcGtDXtIbVNPaHe0iqu9VY8M2OCe/0rk/DojS8EYbap5bb1HPTFeh6CVkcRiQPuHVh0puRPLqeX/wBg3OtXIg1UCAxxkR5TOUz0BNejeAdKt9FvrVNPfzZW/wBdKrZz2x/TtitbW9HnjQpbRZByw4HX29D+hqH4eWlxa6xP9qU54Ctsxj60nK6G1ZnovieOCXw/cC7iWWIJkoVJz+Ar441yJ49UuAFaMiU4GMYGf8K+t/iFqB0zwjeXETL5gAClzgAnivkXViZbmRnbexzuJ6+//wCquaexrBGNMrqoDI2GJClewHof6VSdQoySAT0IFaLvtiwTlf8APSqcw3yHbux78fiPesGaFbZgZkyOM5HXP+FTkB1UHI9Dnr71Lt3YCqSBglum3j9RUZ+TIPBxlfQeuaAEyQ7Zwyk4Oe/0rN1LSVZmaHapPIwML+PvWnDIrRyqvEqjGD+n+elRTyloyGwpPcd//r0xHMOZYn8iVcH1b/PIqKQYfA4Y8+1bV9Esw+YZboCO3vWPdQeXnHKNx16VadwZXC7hnbz3yKXy/wDZH5UZCgAEkeoNG/8A3vzqiT//1cC90m6szlkLr/eH9apc7CCACeg9a9JcIyKjAH5SqH/a7fpXLa3pgQrNajKnl48dD3NZyhbYuM76HMuCWGcfl3pHQjBI5PU1dbByflyD0qpNkglefasjVETICp4G4HoelG5SAJOPp3pHBLcAqcZxTwu5fm4xyf8AGpLG/Kq4X1wM812mgaQltA4n8vz5QGWQHgjGcKaxvDFuk2sRGX5ljRnwRy3sPfv+FdtdBJsp8pBbPmdMA4IYAeh/nW0FoTJkUWIZyFZihcHOc4buP896ntnL3YKKwQngH0zjIqJ8JCySAAgbpI26NjjcPb+tWbMqt0rEBW3bcZx9T/KqIex1MS77fDEYBrJ1GNgS2MIvT1zV5JxFGQUzznNUsm4SVejZxnrRbUlOyOS1IlU+23eIrCLKiQ9T2PWuA1j4j6bb6hKUi81wNuNpK8V3nxQgI0BLKEsqS5496+XrxTDcypOj+Ypx6c55raNkjOfQ9OsviGDeeatvHH/uk5P1r2H4f+I49eijhifyp4zuAU4LD+tfKcEiou8RFuQOO1eu/ByC7udbtLmDfGEZSc8VcloTG9z69t2M9pEqqTIqhSSOD3Bq9ZWqqwkQL8w+8OopdMhUwJIWB3IBwe9WrSRQHOCACee1YGmhx3xigluvCEttEMyO6gEdvevlq4ALy5yxBKtj1Ga+rfG2oINDkuJzGBzsEnAJ6DNfIviW5eHWpn+6Wb5k/wDrVNTYumyOdU4KbQh53DuOx/xqERAsqsgUP078/wBKmR1kCSREFMZYenrio2AwxLfIRgbOOPpXObWFEZVd6hgx4JHp6j0qnIoMfGUAOT3K+/0q2rnORlgBn/Z59qaSGLP8vK7TnnB98fzoBooSQbJGL8KuRj+7xnIx2qKRihCMQRtyuffkH3rQyUUIindnGCM4HtVeaONvkXoM4Yjgn/GmZ2MqR8HzVUq/c9iKryuHByMep4/Wrc+8FiVIKj5ueo9fcVn3AIchcL6kUAQPCMggnBGab5PufzNSyM2RuMZOO5INN3H/AKY/99GnqB//1tkbmuIBtbnpuH0/l/I0TBZPOZVDNxtYds8Yx36VMkpYBt23JzwM59/5UyVoySScI7Fdx49M4+hwfzqiUcjr2m/ZX8yHmFvx2/8A1qwMEb0I285zXo06o+EICyeSUye5z09xXGa7Yvbzu6DbFu2kAdDjsPTrWE4W1R0QlfcxxjCg8sOp74oYYGDyfWpXj+6OAe5Heq28qxDgbc9qyNTrPAcZbUGeMfOo2ru9x0x7118dtufaJCH5Gc5AJ4OB/nvXL+B0AtLxnzskbaxU/MvHB98E5xW6twd7F/ldn+bafuuOuD3B6/nW0djOW5JdmMxxHywpX5ZB3Bxgj8/8807zUV0kfHzYLHH3WwOlV3VZWeO4fKuehGAGIwD9Ox/Cs1HGzZcZ2lmTPckdQaYWudxaXUF3CURsuBk+9V4mMc7LnaX/AIs9CK5fTprpJTKhbduwT6jFa39rA6qbN40RkCKSx6uf4fwqlfcjlvohni+2jewEkw34bIJbOMdfpXgfjvQ4p9Qe4tWETuoLJ2Y+tfQ17YjU0nWFVynG09BgdK4rXfDqm/td0RiXfsMu375C5OPxIFaRZDXRnhmlaFdvNl/3QBHPrXu/wxt7axaFBhpFIyM/eNZkPh1Rbh7iYyJmNpEC5Zd3Ug9wCR+teheE/Cn2aczLCsflYxk53A45H4U5ajjaJ7Bo04+ydwcZwR1q5bPH5RDYC96wtOkeCyjLsxAIQ5P5ceuKmnuGniVbU7N7YBIyOO1ZsVmc18SL2ya1ZZp0JjyFSNwGBxXzprcMM3mE4khwSFJ5xngg9Rj0r1T4maNLpV79o+f7JcqSW6lXB6Z/UfjXml4wMk54+cgrs5VSOufr+hrOZvBWRzT2j6dM3lr5lszA5zynuaJvlmbDleC27Hv+np+HvWwp2SbSv7rJ+XPPPQe+D3rMvYkC7ShRowd/X5sd/rWLRoU5SSflIDjDNtpiXOPmPUHOM/54qGUNu3q2SUyfb0z7VWSRQScEDdgoTk5NIRd8wIuTzt4BHVc9B7j3pVzsAl+dTyQvUjt9KpGVdoXqRwN3df8AGnzOwIkThwc/NzkDjOPbv7Gglle/bMjW8p2FVLI/19KzyxReAcgYKkYzjvjtVu8lSUkMVUhRtOOG9Oe1UpCkm/eGDL2zz+NMlh55JO0EDsA2MUec3+1/33VZo9+CS2cU3yf96nYR/9fZSTYiQxHOw5Qt2Unj9KS73R3brIm0rh1/iGcf4E81JLbKkJZW3KNwUsc4XPAPp1prvvlUqsYKIduDnevJwf1qyRpiSJsk5Yx5jU8k46f4VXvVLQpKNjiUqJFkPAweCPz/ACNWCipGsy7dsQ39z8vcfnx+NQSKv2Oe3Ukr0SP0TOVwfyH4VLRaZwl/F9mup49uzaxwp/pWdIWO3KnHWuw1WCCdUjuARMrAO6nJwRxn0PQGuWvLdraXEjA5yAezYPWueUbHRGVzqPBZUWM7kZVXJIbovGM+9bc6wxGKNSUiUfMRzx2b3OeD9a57wjuW2uJVGczKuT0xjnNbF0zi3hUM3lLnAbHQ8H+v6VpHYmW46WUMi7mEZOY2RuozVS9Lb4pkyZFKknGD0wCR7460MWZBKoLsQEYnOMj7pNWVgdp0bBJYYHHUdOfypivY6HQNOWa2ABILAk/7OT61lal4Hvt0ElrfxbbZ/NVmT945GSAWzjk98V6L4U08PZgMvygenU1sXmmR+QwfkegqoysZczuea6NqV5NoKHULI2mrSSkSRL8y5LYGGHBGOc0/U/E0dhp0lzqFuEtIGI3TDGSG46/Qn6Cuxs9P3z/MoSMdB3rQv7C2j06YzxI6AZ2soI/Kq0uTdnKeFNR07VZ2TT4YC44dRgkEgN/WuzWyl+0wiYYQkKAB7VyXhTSTB4jN8USMNESIkUADPc4716nZBLhE3LgjB5pysNO5GdKia22FS27rmktbCK3KpHHhB29K1gMCmSkKd46jqPas2O5geLdCttZ0ea1uYwyMOvcH1FfMHi7wte6DqJimVzAf9VPj5ZR6Z7H2r66mCvFhT97msDV9GgvreS3u4Vlt5B8ynt7j0+tTYuMrHx/NgRheNud6Y7/571XMmyRLlgCXXGw859QO+f6Gu4+JXgyfwrqwaLdJY3GWik74HY/7Qzz6jmuE2jYY2YeYuWTuM+g/pUNWNk7mJdo1tM4YEnJ2uvX14qnIVkHyqNm0uGUdD34/p2rZnhWXKFhuYEdeh7fn61g3IeCZsnaRz/kVFgIfOLc7ufZunpmrCSFP9cqk5PIOQKpEjaxQfdHKf3cntUaSGIYYgIT2OcZPUUrEs07hldslA7epGPrxVGR4235CJKc44x78/wBKV7oYDDIABODn9P8ACopwroGXGT19QPX2pksq+aVJ3+YrZ6L0FHnL6zfnRKJFfBUN7hAf50zMn/PMf98LVCP/0NqORIJmjdgUcEK5J2src7T+tRWjopZWKpgBS5O7nOM46kZGM08xoZpE6SBSoZuQCex+lQXjM1yJgESNkBOxM456H2yCfXmrEkOWRzdNbkZyvybj8vPGM/yqsWYNK5gdjFFxg/KRnBHPfr/SrMbh41ZlAeJ9n1HXGPwzVVgsu5UIjyxZWJyvXnkfh9DSGiiyRQyGR4t20LkE/eT+LA78HP4ZrJ1aFCht/wCHeQhAyB3HueMmtuWVTp9tLHtJRwjEN2zkDPpnI/E1nSxpJauIkDMGLIu7p3A+mahq5onYi8LToLG5sLgERbzvbrsz0PuMgVqyb2gjlkKZDbHTPU9D9OoP0rLsp44A5Khre4QKzltu0Hv754/KrG8qyGeVvKZtkjhBkMOenr0GaldjRrqXLKWSedbVgDFPzsPbB+7j2rr7HS/KiHGT3PrXO+FoC2pZ3vIsZLIWUAjtg4r0KBBsUADpQZyep0+jbIrKPoOM1rwwpKhL9/WuWtZSNozworQh1CQXiRFSYyMk1VjNo0XtY4ixj6nktVeZEmgKMAwY459KNTuwkBVTgnvWP/aGyMAcluB/jRewJD7u/gtdRigQAMzYz746V0dtcMl/bRnjd+vFcdPbie7tbgpl0kD/AEFdpavFJEjSD5gcj1FU2g5TakcIuWNZN/eMAvlDLGlneSVyGysfb3qpPn7ydR096QEttfjzTC5wyfLWqirJHkHJrFtGEjbpIhnPWtyJgUAAApAec/G7Txc+B7uQorG1ZZ8nqoB5IP0r5bvgDJvQhWUNuA/Tj0Nfa+u20d7Y3FtKqvHKjRsrDIIIxXxl4ks203Vru1GVmhlKMD09MVLRtB6GDLKPK+dQpxnk4A4+7n096r3KiZPLmAXqQSuWx2x61cvB5kKhsbkOGXjLcdfrVS4ixGisVIJOx+cN7E9qgs5zUEaHaHGM8q6nis5rgglW+YeoGOa6O5TzI3WWIqQTkAdCB+hx+dc1e25Vxn7rcrTViJEsbkmMt3zjHPNSyu5XHBbGCPx//XVGElQN5wwIG48gZ7/hU8UgkJGN7YK7lPJA9KGibk8UihNrZO3jOCad5ieh/wC+TVZpXQ45b3H9fem/aH9H/WlYLn//0dNJ088xoiIkknILEq3H+A7VVEDyozQqdtvkMGPLKJPX6d6tXUYfE8K7W4BGeiMMZ/A8fjSCfNos+SGhYwuwBG1SMrn19D9a0ZKZL9oBaRoliZZcuhT+8vI//XVGWRY3ETj5IySobjCE5B+vanXSyQyxKCrbc+UQeSmMgH8SfzqO+DSeWHYNIWCqeuVHP9f0qCkULiTy4p87NgO51HAHcnB/PP1qrzFdKjyOFZcqzkYJ/p61bt2WSZllG9JA6SoQe3Q49CKzLk+RFLGFwYMQbmOcjJAb9QKk0RDe4yofG5AVKg9Mnj+fWoobktZhA5LLMyE9flIIwfoehqG83LcFo9oVEyDzng8jB9jVQ3LW7vJ8wRuSpPJHFc97TNkrxPTfCS4gMx+V5CN34V3NseAOBXBeFmC6XCYyNrEsMe5rsLGbOAa2Rzy3Olt4gUB7fzqfYyndjGP1pmltvUVoTjbHnbmqJTMi+Uy5JbnGKoRptYAgE9BVu8kIPpUESsxHSpNDa06FZCrHnFbYtshSxxisW1fFuscZKN1yBmughkWSPJAzQTcZJ0ANVS4yVHSrUxXsOcVlyXHkvgincbWhdi+9zitCFgB61hpdofxq5BcPJgRKTmmQ2Wbs/IfWvkv4xWjWnjW+dfmjnbzOD16dPfj8q+qtRkaKzlaTAwpPJr498c3c15rl5K7h2MhHB4Azx/kUmXA5yfMiYRxlcuOc7fXNMkAZSEDlM7XiI+4fUf56dajDsjjblG6FsdSPWllHmOGjX51+Yr1VgeOR3H+eKg1K1wzRyLHIS3m8cc5UdMHsc/4Vj3yh2KSgbcHacc5Fb9x5LLujO5MgkDkx+x9v/wBVZ93a+ZCFYjcQGBPp2xjpQJnJSORmNuvf/wDXUMUjRtlTzV++szGFDMDLkDB4P41mkEHB4NWrGUrmnDcFoxtIXHBz60/zn/vLWRRRyoVz/9LYZIftkieZtUuX8tjjK5Bzn0HIqqSx+220YbcreaF2g5VXzjdU0t39qFvM6IZGGzKfwA5GR3qGeTbPCyo+GUps2An5RySPbj+taEEjlGsUljZ12L5ahlGeOo/A1SnkBtYpolQQIzKyklSuQCp/nUMNztiuY1cZGJ14yp2nkEDsc9aYknnJNBEC0JJZR0JH19Bkj61LKRWuZERwYZDlZcglsA5HTPbg9apamxR52iQyJNtUrnhX65H8/wA6kkHl2/l4BIwisfbkZHbiqcgC2aiJ1di2/buwQR0HH0P51DNEZ090rxMXbAU4xtI4wf8AOaz7oEx7eMklgxbr7fiKvSndIjSAhHG0jHXJwf1ArIbcqnyySc9x0IJ6Vz1VZ3OinqrHqXga5jutLhERyAuAD1rtLNJFYcEV4/8ADrUTDqDxlsA/Mo7cnk17FpMY8xiX3yMck+g7CtYao56iszdtLnyUDMce2adeaySMLwv1qNoo5bZiRgjPFYFwqJJwTkjOM1ozOJee8dkdlwT1AJq7YTs8alxtbHIzmsq2wy7TzWhbRkNwcD0qDW5vWVxmRcmtlZ0hXLvtz3rlkYLJHnP3h+db0UiSnblSyHkHmqsQae7emetY8oMt3JHIRxggCtlE+QcYqrdGO13TOAMDqewosNspN5UUgj6t3zV+PUbe3lWB2VXwMVxul6suoahI6Hcu44/OtDxFLasiF0b7Ttyjqvb/AD2q0tbGbJtc1XzrS+BZAqKwWQHjp3FfJ2vSGWWZ2U7t33uhYZ5x/n0NfSOrXTPo1zHJ5eTEcqMnBxXzZqcaMXKHPPBXqRnkY7EenpUSNaexztwcygLjGT8xOfb86sIWXYQSGjzg54bjpj9cU+4QLI/l5Vn5Kqc7Tjj/ABqDAk4JZHXC59fcVmzUiMgDJJHM3mfeaMc564yafK8UypyoGBhWzwPXH+fWkR1LF0fbOpJfJ6544z06CiU/Z5mnWNxHg5jPPIPIP59PzoEzMv7YmAO4bzNpX689Pr71zlxGwZhw2D174rsjKHDIpDx424bsf6D09657VrRo0V1yF6hj/EPWmiJIxKKD1orQzP/Tvacpez8wZVCflEi4K84z+B4/GgCdoZI4laN495JduTjGRn6kgj3ohu4oZrR8AC4XB25JII6Y7c0pkka6ebkNIxMwLDG4YGQPw/SrIKrxfZ7uxk8lWaWQ2vTHBTdx/jVWAMs6R4fyimAc4+bPp74zUlyFubW6SCTErxll9mTG05HGfaqkrysr3DlkZ1DljzhgMbvxGD7UMor6kZEj3SfM4XMjqucP0PHU4BBrIAjeJnkXCjEoG37qk85x3yDWnNKwslmcMJkjMZKjhjnOf581kXieUSweQRSDHuMgYHHUc1DLiU7xTtM0QMhERPJPGPU9jg8fSsm/cbz2bg/KOBx79+a0Z7wSecHULLGNpXGNwzjbj6Y5rAkmLlnZiMMQwc5+lY1djam9S5plwbXV4mjYqhfGDwff9K9jttcmj+xxRSBGZxk4ySK+fzcPBcM6tnDBlA717F4dnN3pNtcbjEyLuJOCcEetOi+hNZdT1nTp499yvnmR5GztP8OAOK5bxFe/Y9YtTuwjZU/lVjQy15KJoGVIwNvPVvWsPx1BLLp8k6AiaElse1bPexklpc6qyPm3CyI3yleR610FqoYCuC8GXpvNCtZ1PJXafqK7bTZm8tWfHPBIpWEyxMrLKp9DnIra06WNJC+Vy3UjmsmRwwCk4ycVfg2AcgbQelFgudNCylQe1cT8UNTlt/D0i2ILTz/u48d2Jx+nJ/Cuhsb1Z4i44XoPpXG+PZxPe6VapxEGMr4/ugYA/M00IyPDlqdIsbdZnZjwGI65rqbe+B1KGKVkkhlGAG6qfWsLJkn2pkqFJHHB6VFp9vNJPiRSThjGc55x60oattlTVkkW/iBLb2WjXPlOsR53yYx1Hb3r5tuVlWdo48CNmJXI+YHHUfyPNev/ABYuG+yrbO4ZY1GecjcPX1+teOXDIzPKq7gv8LNy+cDHsOOtTIuCKFxH5riVNw2rymSVGDyQe/X8Kq3ELMGkRggI+Ug9uwz71duW3b5ImOH/AI8EbT746DPBFVBG0jCNuCCSQpGf96oKI4pyz52qZU4bPByOCMe9LKSYiy4c4KeW3OfbA6/1FMc4hUpJvTaNpPD5znceOuO1PUsJnmhil8tSSycEuh7g9iP60AUGjaKXaCD2bb0HufaoriYyWpjnUODwB3Oex/Srlwjsd+wLESxJxjPrj3qC6jRMQ7fmjPyuDjIxwc+lUScncQGKUryR2PrUe0+ldY0KTBXeKZ8j70YABpv2SL/n3uv0q7mdj//UdfwSKlwIieWcrswShB4+gxmpW/eXLPEoWPCyg9yvADfn+dSpEFmeGNpIlkRSgIyc8g/UDvWatzLFp8ckMXmyWw2uAw+7k5Hv2x71ZAWTPbavc2srKhlHDL0bPBX2/wAahWXyofKEPyECM7jwQpOBj3GDRrTRRyRzfIjOirIEJJUHvn1qssgW7UOSFlGe/wArkccn7vANDKWpHESkD7xsJJwvvzj8Kw1+awXy5csIwquOd7Dg5HbGKuyORfKm9mDDJZgQFJIx/L9aqXDyDfBGoMal2GR1QnOAOv3hWbLRkySKFuUaMhyMEE9SRj+f86xdXZYVkjB4BDZ9Afatq/iBJfcCowgYjAbpyf8APSsTVG3IwCfKBtwPmbr6/XpWc9jSG5jTSF2QZGCuQfT0ruPBV4Lqxa3muGWIEqVzzj/CvPVfAAA4X5hzn8Pwrb8J3zW+qwKCoVm5/PrUU3Zmk1dHtnht2hsjIPOWON/LTJ557n616Ra6bb3ekoH+YyqW+bvn1rz/AE65aK1eIRM4Y8EDOK77wrJIyoZEbByTnt2ArpbT1OXVaGFpGj/2Jc3VggxA5MkI/u56j862dNlZEEUnDHP5ir2tWzyQJcgfvo8kgdcVl2cnnYkBHzfr7imJs1HlQn5jgg5H1xVqxn8yM7j1yKw7rCyeacdDjnvSrcsiAo2GOByaLCudbauixMFIx0AFcn4hcPr8aLghIOn41bt7nyIWLnavauRN9Lf6vNfIPkDeSoz0Ve/50dATOr0bzEkhbb+724wf8/5xXQGaK2tSqQ7H5wAOhrD0dSSF7YJwTxVm7vQIGiUF3PGQOlQ9Cr3PN/iyp+yRTRqpI4IK54PpXj4ZZVIDb2JGOxIGcrz06V6/8WgzaHbyqSMS9uvTt/OvGC7wyFCFEe5nkBHDHv7jrSZpHYluHTykmDNtIKscZxxnk+2PxrOlVS5Iy2DuBHJ46irZkYXEyhQyhQd3UkeuPbn8qiZAchVAQcBVJyV9R9M8VAytIqSkgkjKsZIxzuXuV9O3SmDiNCmTj5VKtn/JFTSo8PmKwYtHjbtGS30PrUabgciNQECqwLbXYDONuO1MAmjUsjuFMRJDAHJB7MPqexqsmHKqw3OpI3KeGGPX+VTxuZYGCqSrcOd2N3ufQ1DGPObzeOMOseMYx2x7e/4VSJZXlHmENGrbMDaAcbfY575zTPKb/nm//fQqw0EkmCvlHAwQSQQfTjr9aT7JL/dh/wC+moEf/9V+rXIW3iuI4PkidY5SDuYK/XGPQkVmxQJbC8tottsu4x+UF4CkZDAdSAcD8afI32nTZFeRTNGjAR4zjnAA9e3SpBseG1aZd9zsxKytk9hgnt9a1IKlvJI9neJH5anYpBCk7iP/AKxGKz2lcQF9mfLbs/OcYOfwz1rXVo3nWMSL5K/w4x1yOnsOOfWsYDE08TxvuXdIMsCT/DjH4ZGaljTEupH3QyoiTQyhFdS2Pmx29iMfjVTVLp3KvIyfvFMEhC/d9vr09qRIIjMjkxl1K4XcRjJO7B9sAg/hUM0ocNDOyScecVAIPzE8fljk1DKRlXbPKqq+1nHUk434Hyk/WsO+uNzPHHtDuN4RhwPr+BrTnPJjVWZ1/duR/EMf0zXOXgZ5k/ehsqFOOAQO38/yFRJXNIszjjePLb7xAUHtxU2kH/iZ2qnCkzIpbP8AtDNQTBhu8vG9GyCOhFRwyGKdZUK71kyMjuOQf5VlFamzZ9M6XcfZpUP8LcGu60C/Vup56jivLtJvFv8ARLW8jG7dGrkH1xXYaJcB5U+zFlO0ZDDitkcskdyxDOxyTuGK5G+T+xdWKfN9ll+cAfwHvj/Cumtnfy+gVs9a57xwhntUnif94p456itETuXcW9zDlSrg9s1nQRNHdnjMQOQSa4zRfEZkla3kypQ4IP8AjXVrfRLbxSTNmRsgDPJwaZNmTeILsQWzyM2FVSQormvCtx+5Unnc3I9yeatatK92hVsBT2Fc0rTWk6SxMFhJzw3J9PwpNlqJ6/prQwnkEZ7U3Ur1lSQxAEYOMH9awLTWlkixkE8YI9Krx3Et68kok2RjO5ug47VMgXdnPfFi9DaNYW8LR+aZRIQ2TgAdfzryW52TzyRFNr5BVtx6ZHygfnXQeNtV+2eIWyWMUQ2pjJAx15Hf61zsrI7hol4Xp33HqOf6++KlmkdiNchpFCOYwNqknlT6HuBzj8ajeVonuA0hKSMDjbgcdh3xx19aV3uWlVhlZy+LkL09VwegHNMHly2zCNlAJ39MnJ4yCf4f/wBdSUEhcuUCvv3HapXBcYyVHv1qskK4435T7jEYPPY+g4/SnDO1jJJtIbJZm3FD2I9AP602SSURfOEEvTZjhhzg++aYmQkCOO2cqxjILMGbAUnkM3cHrxTZiH8qRRKJCBv28FgPukD19vzq0uLlWjHVCX3Nxt45IPrg85qusw3JDDv8wYCyKMDn0xz+J9KCRC9szN57SRSA4Kgnj8uPejNl/wA95fzahZoYNyGd4GBOQqAhz3bPvTvtkH/P/J/36FMLH//Wq2trKl0Y3khjZBuWJVA3sPpnOQAfzrK0m5jW8uopbcqszsTvf5Rxz9Rnt610M4+2X1vFbOqA27hT/HuBOCAPu8ZFcrcymPUhcTTtLHMRsRh/cyu7/Z5x9a0M0XobxXkg35jmbduDNyGz+vTIqO7mQ3iwQ+ZvkB3SOMnIIOPxBFLMI4wTOsjeXtdpEGNjHjv1J7+grM1cOYdieZl0wsg53c54/DGTSKIYZvKuwAokzk+WRwhPG0/kf8Kr3jfZkaVFQpFIEc+gY9x3x+lTS5iSW9ib91CBIzMAccZJJ9qzrm5W4XymDAyoRnJzux1J+mOfwqWUjLv32XNzbgNuYZQkdl4OffHasC7/AHUiuMKjJkA/hxkdK2b6VFjUFmU8Bxxkf7RH61jSlOYhnzFIIBHT3Hp/9apZSZRkysjfL93GOOSMVVbkbUJ4xg/pV8KGEcgKtsGCSMhyen/66hn2ZUgg7gdpxjPNYvRmid0erfCu887w8YGf51kkAz6ZzivRfDOohcwyna6cc968g+FzxoTEG+67cnjORmvWIdKF3AJIH8uUDIYevvWy1MpaHY6dflmKyuCpUgY9R/8ArrmvEuotNctb2xLSDgKD0xWBNqtxa2/7+PyZ4Djk4D8f/Wrl5PGcT3l5Ku1SMiOTHfHP6iqt3J22LC3P2V3e8jW3kychjinDXvPeNFJKoDj6ZritQndybi6aQsBufdnBOOAKlkvhazQzncsRjGSB1Pp+VJsu56ja3cl1EP3Z6cEng1qaVpX2hGE6g7hjAGBiuV8MazHfxnyxt4G3ntXoekyKEBJ59aZLkzKs/Dcttch5LrFquTtGQT9apeLvEUNhbC1tehG3K1q+OL+W00yR7Y5kKEqCcA4rxe8kkun82eZXcH52blRxwPc03oTHUoXTTXX2hd6PMhBQ5+aTnv8AWlSRVwGMocbVUA8/U/n0FBlLQxpF5jSIAIvl6nq2RSTjKrcW7uWJBlKrwgxnJHQHIwayZsKA0d8u7aGYheM4PHDdMEj370kpiieObarzhvLJGAwXqMAdf6c0x5FEcazIhbBYMxOSCehA+7+NJgRs+yMo2Spyeq4wDj9KQBcRbArhN7D94Ac8n/PP51SvMyIpJBkUhUG09MZIxj8quiL5IljITYdzB1+YHngZ6AjoajVxgyeaxJ+6VbOxvp370yWRI8KqWkKkDEm4qByOoI6gjoaCrSH918oJJUEHII5G4D/JzVeQxrHmI7UYlpFzu2kn72T7Zz9asyAQW/nLuXBxIwY4wOAfQ+lAFYy2ZSPzYWdto9Bj296b5mn/APPq/wD30Ku+TCVUuttnHRx0+nPTv+NHkW/92y/L/wCvTsB//9elqE81lLLJGCJoY2MXUjPB+p757c1l6jC5njTY0jkLLCufl2k/Mo9OOn1rQvHS6CTyQuW+0mFyDnhl/h9+gPas1pDIlncRxhfKdrKUjncCdoP4Y6VqZosZM8T2qSpMhzHuf5QCRknd3OCo/Csnc0PlJ5zO6yeWoIIOAcdOxOTUsJRlICLkDOI8hQOAPzK/zrIubn7RO6gXGCWUE8c55PHX+lIZZuGa1imidV3RHchkA3DIPPPXkVj32ZbeSKJ8MsIdGA7/AN32HFJP9qhaDCrLt/dK7ZyCCc5JPWq0lwVeKdVZR0fcepY8/h7VLGZd3KHh+9mNkDL2yD3JqjCplZZMAZyCSvJIxjPp9KkvEMeEeTcqT7Sq/wB1uhH0zVW+OI3KOFBy6r1x259wR+tQy0TmJAZmQsoJPAAwOec/0qjdzZRh0IyOR+XNWgpfzHw3zJ849Scc/hWddTGRwwBXcg4Pt3/WoaLTO0+Fx/064JJKnC5PPPf9MV7ZpU5hhKBtw9a8i+GunyxweYw5c5x7dv6V6ZaRvbps3lifmJNaRMp7nO/FW+ddMhWIHM0vlsfQY615SQdzRYO0ccH73oM16V8TrV7rSIpM4WOUbuccEYry0sfMPmEb9vAx3B4+tTUvcumtDet7hLq3dZPvoioYwc9eB14yKVdqhoHYqSNwU8bWHb3HesvTSr3EayAv1y2BkMeg9Pyq/eDCPMrYVto3vy2d3X8OBUp3RbRf8KXzwas0C8IRkH0weRXselX6lBz2HFeEaPc7L9mZ8vz6duwr0/Rp5Vgh2HG5vmJq0yGrnT+MSLzQHwP3i8ocj0rx1SSsSxuPNQlRg8cdDk+1ewSIl5YtDKDscbeO1eXa3bPY30lvKv75W3Jhck++enSnJ3FDQyJXMPzwPhvvB1JGWzwT9OakBCF5YSYoy21huO1m6n255/nUV06G2KMWdlPHPzEkc7f51ExlW3hiIVjt4Ycqx+vU8Cs2aE07J9pkW1KJbSBfLxn5SOfmJ9T2p0b75t43LJgglucDPIx29PXmoVDi2ghmiKlWZkZ27H+friqzlhL+/jkJdvukAfMOjccdPehCLkjMxDIS0TgDnB+bsCPpio42YySkEjIPQDPXgjsB2oidnKy28e5wGVxwpcduT9Cc1HNJjaPMUshyGA+Zhj7o9896olk0UcaTSlGKu2C0bHPJwMAdMe9RQrsllheML5RBAYfe5+6M+nX3pAY7kxybJN+CfmwF+gHtUlwkUbmTAOzHDccEdvx6fjQAkX2iNMQmEL1w74IP5U/fe+tt/wB/D/hT45l2A4ijHYbhjFO85P78X/fQpAf/0OP/ALQuJGS6nSNDPG0Mg3EiNhg5UDjI9abMjfY3UyKRmOVhuILbT8zYPA65/GmLGzC3iiyNzNHcBgVIGM/UnoO3eltpo5ZPLllYEQsHBB2vjqPyHGK0MyCe8CWtxcW7BZIAcqTnocjHoQD16c1Q3iaTLNEJUYg8FcZG4/j0q1MDbwyLE8LZ25VPmcqe7H2P9az7xpppGlBVHjkSQucDKhcALigaK9xIRaLvw6m5VuGO8YxxnvVGebzYpztIDt8xLDAGScipdTtw8zeYzgySbhuOCflyDx0zzx7VhQyLLGgcZlYfPsPJKnnjsCBipZSH3Vwk94+yKRIwo5PY4wf5Cs6MqsARgG3A9OOOhJPfjn61ZuXLK7JtypCAk+/p9O9VVUiQRAfN5ZUDOc5PH51BRbWUQiInJJx94cEdCD+HNUVi82+WBSeHwwxxtzn+VWJnEkSq5GyMYySO9VxK51GBwcM6jdg+9FgvY9e8P3C20UESKAWxyK62F/3pDPyR09K880q6jFxaR7uBlmPsB1/OurjmiENxdbiNuAc+gFWkSzI8d3yTaDcRocFZRyR1A5OPfGa8uZ3SZXVSSuMMRyT6flXY+O9QV2gtrYkL/EF+nWuSkJWRpF8tE2nDMehGeg9+KxqvWxpTWg5WZXU8fIMAggHk9B+OK0NOuGks5FYRmQExsqnJAPJbP1rB3lEQFcHbsGR0GfT3qa2uJre4EisVXo68cg9amJbLjSi2uD5Z3Fm4yPzr0vw7eiS2g6EgA8eteaa+qukbWysYUUFnPcn7pHqDmuj8IXCpauJT90YIz09q0RDPW9LuN9oJenPftWB8SoY5bRLxUBkhwG5xxnPPtVfQrq4eK4UufLUkf4Gk8QXJ/sImVsyMuDgZ4BqiepxEbGB0QM4aQFMk5OT0I9AKqxrI8axmVXIDCNgcPnpyenPpU0uZhvdmIjDHzGXnJ44A/Dk1CLlDNJKIj5WfKPmc4HTI7cVmyyF4laAbSY2UhzyWYY+U59MUjhhE26XdufDIOxA6g/lU9zGkDOh3MxOFyeWY/wAXp0qCdRHcKIgpU/eGcDHr64/CgTHzTzRujvxxtCsQd3QkAd+lTrGsNwJoNzCXjYmAyDGTk+vNQTKVvokk2+Zjewzk4OcfTp2p1hMsbSq6ICMMSeEJP09RwfpTRLGXTuy3JMYldTlTuIAJA5Bxzx60oKwApNuLScFnU/KcdMenSrtwrSndLtiiyw8sZXkY+bj0HaqaSPIZFaXZMzjl+uOn6imBYltoC5DTS5X5cIh2j2FN+yW//Pa4/wC+DVfzhF8rxrJ6ZY/KPSk+1p/z7J+dAz//0eIs7sPE1yxkZfPLRqMlgCSp5/8AZj2qNWlhvFElujrG7wIuc/Mw35H60ac6R200AEgdGYjzBkHAyFx7AD8ahvWEkMV0hybiFZsrASwbg9c4B7fStSBodFddqlMkRsH55x/I8Z+lQ6hMkSoFDvb3afcIH3gMcY6DAqzeS+Zps86yKEJWUYGFPcjP1zWLfxqmnSFuEiYTKH+XdxnPHUc0gG3W8Rx4PmPEQZQrg5AO0En1ya5i8jeOSTzEJQMGC7sYyfu/yrVubiNvkHmLBJ+7YFQvvj3zmsaQ7IFEo2oG37Qc7sr0PvUspEU8QQzxh1McijaoJPP/AOuoyY+GjG5w2w+rbe49hTppSDCxyE3CNsN97FL5QS4nTaEymVOMYz0+ueagoLeXchKLzMCWbbnYCew74NE6swdmj/iBLnqO3PpUaJICqSlcn94oHU5PT8OKuTSATKy7t8p6Y4IA+YCgRqeHL82xljvPvqAFz6f/AF81t6hrrf2XdQcHzFbODx0ycGuTUNtESpgEAJz94Y9TUDFliClo/M7Acge2aTm1oUop6k15dTXUhLMxYYwAeDx/niq6E+cnlklj1YdARxgU0bgRLCXQEABcZz789KXAAM3IyclupPHH+NZt3NELJtciY4EmRuHrg/zoz8zjP8W0DOMD3+vSmXCl4CWRdjMzADjB9fekZS53s+GztyePcHikM07KR5bV4Pm3kgqM/eHQjnsMGp7cPZtiNzLCw529gRwff0rMsZ3jmU5XeOCzDOcnBx+Ga3YiyvGJH2h28vjrtBJBFaRZDRu6LqrSxsFY7jIhbtxgVL4kZzYSRiRmU7juXIOM9B3rmoN9soeMDLyY2pySBnr6DpVpr2WQrIHKggqrnoCSRnn/ADitHIztqM+0qdNMRcfNjzNmV3MD1+mOKJGeG4iRW3KQyqvGAcjn0xUeRGUdspBIhjVn+cj1P4mpsqsO12UFMqTt2gZ7jH5/jWZZG9r9oQxxDdKp3KxfhYx0P1zUfm7pwZN7MPkdcbA3oRnk+uaeMmZJVffPC2xUZtu5O5PtRIFiuknCqSVbqS2Rnjn0FMGRIeGk+0J5QBVmZtzH0x6dcU6yieW6i2HayN5bKgyoXGefbNMtVR7aTaqJchvNQspIY4yc1JHtaOCba6x/e2s2N+SeDjvn1oETWbM7hnkJtSXVzt6jPT86a7Ml08YOWwCCB8ysAfyB7UvlLIA0cu5wSyxrwgcDO0n6elOsGNxAJCpVfm2ncCRnkr/vDFAFT7WqvIzMWkdt0hPdun9BR9uX/Iq2b2GABCrqcZIBXqfwpP7Th/2/zX/CgNT/0uHhtoYbvU1jmcqr70hXO7kc+uRVCQMNHMSnKrcKu4HB2sRnIHfGRTkuxFqMdxYo6t5Yi6bQecFR69Cc1XiuHubW9tVXZHboSsifKHYc5Leozn8K1JRM8MUv2qJWZl8xljJOB93GAv0rNtD5lvG7ts89Dx95iF4xnt1zVuJ44bedh5bSCNHDucA/7f8AnrWWu55opIMxCFsb24D7up21NwMmS5ZIpc3A8xWAchOdwyOp4Pasq5OxmgTCwyLlmAw2fr6mtPUsyFgypyo+deCG6Bj+GKyHQqqvMAzONwO3OSTjd+IqWMnhRpoZklX5/vIi8dOlQ3DOskc+CTj94u7oPrTIfMbBlYjByH3YGO+adMyOk0KgiMKCvHQdyx9qkZJdFBNHI0jNIGxt3AbVI9v50+MsYp1i+bywGDvxgjrx71BMWubdJLeGNRgqcnkYGPxqdZSl3CoPyHjp8pBHP1JNMZJ5nmQQFWVir546AEYz6+tQ3LMl1Lncythsk9u54oUeUJ4nCFgCoOOP7w6fXmkD5iQAAqUOVA5x6moktCojXyJTHvbbyFwOmeeKkmXcknl+YQPuqoHHT/69Q8ZG0g7V3ZA6j059qW2kEIBkOVAyuT+fSs2WOZwUTaNrLgNnnjGajeQefEyjh1AK5xSxAEFM8qeOOnPGTTHOLgfdKEc552joDmgCYKRcqpJ/u4GCT15rVtZJZ4I13/MIyjMFGMA84PsKx7cCJjGjLuGW+XnPt+lXLa4dUjhOAQBt28AZ6j8qpOwM2YJIyrGBFeNztXH8IH3Rn65NWXMiFYj+8VlCu3BXeBkgCqVozqrxh3KFt6yDuMdAPzpxk811aWNsn5imdu0dNxPqeP1qmQLkSiVpMRRFshzyQRwc479h9KjnchEWGONoUYlw5wufx68H86k/dm3KZDLK+0443ADg59BSxfOHG/OTyDwjAfwr684oAlL7sTMqusZ2gOODkfxDoSMYFQqY2eKNhtjYkDLYCSf3cdgaUEs0ilSXRmOclhkYyAOnekkch7dV558zJTqe7e2OPypgRRiMXKyGR1i3ndk5O4cZX2B/nVkKY1IAMQlQ4Rm6vnn8zzVeRhd24nlJd428mYspBbuCQOmev402CIeTsuQzRsQFYnqP4ST2xQBbhP2Vx5h3A8uysCFBPJHvTpo5YLxYYxtSdvmLY5bsQfQgVA8aMYvtIZWEZQ7DgbR1YL79T3qaG4gkRVSFRMqsAX4ynbJ/lSAbPBhx80kZxynHyn06VF5X/TaT9P8ACrMN9BbpskBkkySzYHJp/wDalt/zyP5CncD/2Q==",
                "title": "Image title"
            },
            "note": [
                {
                    "text": "Note #1"
                },
                {
                    "text": "Note #2"
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Media"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Media",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "status": "completed",
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "operator": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "content": {
                "contentType": "image/jpeg",
                "data": "/9j/4AAQSkZJRgABAQAASABIAAD/4QCMRXhpZgAATU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAASgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAABIAAAAAQAAAEgAAAABAAOgAQADAAAAAQABAACgAgAEAAAAAQAAAOSgAwAEAAAAAQAAAUAAAAAA/+0AOFBob3Rvc2hvcCAzLjAAOEJJTQQEAAAAAAAAOEJJTQQlAAAAAAAQ1B2M2Y8AsgTpgAmY7PhCfv/AABEIAUAA5AMBIgACEQEDEQH/xAAfAAABBQEBAQEBAQAAAAAAAAAAAQIDBAUGBwgJCgv/xAC1EAACAQMDAgQDBQUEBAAAAX0BAgMABBEFEiExQQYTUWEHInEUMoGRoQgjQrHBFVLR8CQzYnKCCQoWFxgZGiUmJygpKjQ1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4eLj5OXm5+jp6vHy8/T19vf4+fr/xAAfAQADAQEBAQEBAQEBAAAAAAAAAQIDBAUGBwgJCgv/xAC1EQACAQIEBAMEBwUEBAABAncAAQIDEQQFITEGEkFRB2FxEyIygQgUQpGhscEJIzNS8BVictEKFiQ04SXxFxgZGiYnKCkqNTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqCg4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2dri4+Tl5ufo6ery8/T19vf4+fr/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/3QAEAA//2gAMAwEAAhEDEQA/APPNzscLnHsKFRs9/wATWisaY5yackKA8ITXiOqex7NFVYcjPFQzW5JGAx+nFbSxHGAn6U2W03kFhyPepdQ0hFJlC1tpWUAL0PUmtG08yzdWbb16ipba0G3AVifTFX4tOdx9zg+vFJVbM0kk1YqahqN7FbNLp5UOeWRlzn3Fc23iTV5/kWaQknpGnP6V3FrpWzLTsGA6AVdT7LEMbo0I6YAr0KeYcqs1c8urgVKV0ebGPXLw8RXsmfXIH61PH4Y1efG9I4x6ySc/pXoL3cC8Lvc+wqlPOzuTGHAPYkYqZZjN7IuGXw6nKJ4Ol2j7RfRrjsiZx+dWI/CemRjM89xN/wAC2j9K2J3mYAAIR7VGltNL/wAtNoFYSxlV9TpjgqS6FSLR9IgGY7NH7bnJb+dWR9ktuI0gjH+yBSvZIoJkm/WoWSzQDncawlVlLds3jQhHZDZb9c4jOR7LUD3Dt0Rz9TintcQp9xM0gu8rnaq1FzRRK7ySsMEKF9CM1X+zknOW/AVYlu2I+/j6Cqz3APVmP44pXZaih4tyB93n/aNIYDkZdR6Ypolb+Afj1pv71sEcUXHZFiO23MoLMad9lxIdoNVP3qydTVxZbg9FJ/2jSbYiX7MwwM4pTaAjDSnGOmTTMTEjcyj8aeIst802PwqOZgOFnCACSv8AOmy28Y5ErfQCp0SBRksSfrSSTwp91Rn3p8zGVHQ9FaT1zxU0UjL2pxuTjCpgfTFRE7j2H0rObuVEV5W3df0pPNf+9+lMKUbKgo//0MX7Ds+8yCnrHbRnEk4/Cs6QlpMZJ78mkUEc4FfOM95Rua6PZA8b5CPale7jUfuoAP8AeNUITnrtz25xVjygV+bbUtjUUieG+mJ+VY1z7VL58rDDzkH0FU4UijkBLgmr6xllyoIGMdMU4o0dkVlOSdwdvc0rSBRwUWoTCqyku4PsOTTmijxnyZHx+AqrhZEUkhYn9630WljdiRtDMRTlkAGEiSMfTNL5rMvDOf8AdGKeo7oXM6jKgLxVWRrhjh5kH0Of5VKUlb7sOf8Ae/8Ar0eVdEdEUf72KEguRBBjpI/vgAVRl2iTb8oY9s9K0RbMpy03XsBnFDWanH3mJ6Gmog5WMO6uI7dczSBFOQT6UWl1a3dtmCUv/ujimeL4YorGNTHvMjAbcdB6k1wd5cyWeoMlm7QMuSAuSpP06H6V6FLBqcL9TzquNcJ2Wx6CYyQdsR/4EaTymyMFF/CuGs/Eup3jMsbIHVCzBhjOOuP8O1WbfxXG0qJcwuAwGW39PY/jxWE8FUjsdEMbSlvodoDGv3paaJ4gflVmx0xWbaXtvcRq0XAJxyOass+xckcZxzXLOnKOjR1RnCXwssvcnIIAHtmk8+Q9z+VVopfMOEIz9amELtyZMfQVlYq6FaRj952x9adFKmfvZphjiXmRh9Gap7cQqQQV/AUJBcn8xQPmwPrQpDDKkY9aWS5hA+Zl/OqkmowL90Z7cVoqcpbIzlVit2WwqEkGQMfQc1Iir/dJPuaxX1QDd5car9ag/tGZ/wCPA9qv6nOW5k8ZTj5nQHrwFFHP+x+Vc+biQ8+a350nnyf89G/OtPqL7mf1+PY//9HlJnJUbWI/3RURt1kOTvJ/3uKvQ2pEY3MCe9FtEhTdgsD3r5xytsfQWILWzVeQOa04rfcBjOPc0qlEHRfxqwlxwMEY9hWcpMdhkdpsPAx/u1owxYHIH4mqJnIJIDEe/akF0emD+FKMmVYusiJycfgKQug9aqGRmJ/SjcqQvNM4SJRngda1p03N2QpSUFdhIYIQzmNQByT1ri9Z8RNJeMlvI8cK8AIME+/HatNGufEmoLbWTyRW5OAEGWb1JPYV1T+GLHT7GNWG+U9AfmYn+lexRw6oq8tWeVVrus7R0R5/D4jvbZMzCR0Bxh1z+tdz4Md9alQqiyFtpCr1Kk85HpiuVvdNk1W4FvaqRGzFRKoyAR0r2j4X6CmjWUUsiBWJLFV6IT1I7gZ7V0LD05Lma1MHiakHa5h3vhs2l4d6sIpMqCR93Jxir2saJHbWcTIgbY21jjn6/Su51t0kbAUFZB17Zqstl9stZYyMsE7j9fyNOOHgtkKWKm9zwfx3p7SWmWBhWOQAkj+E8V5drtnJHIPKQqNoKn0OcbjX1Vq3hZboSs0YeQZHz96xZfhbDfRSz31wY4gqxxRqo5Pp7iuiEUlY55Tu7ny9dW8trL5sIYGeMhscYVu3t0qSxsZUulnaLCYyDL8q57/UV9Px/CTTIg0rrJPMBkbuQretcN4s8NGCxmN3HEjQuRlPvBT6+9E1bYujabszyz+x7t4hIlwVycDylKj/AOvWrpdzJa3sdlqEoeVovMQsPmA9T/StjQIpHuYbY8I6l4/6Vj+IdJnj1gXRDFwe469v/wBVcdWKmmmdqbotSRpTXEEZGw5b/eqL7cx48w/QCsyWPY3UZ68dqZvC98AetcKw0VubyxU3sXbi5AO4qC3qeaYLuQ/ecnNZ012i8buaqNfkMFTDNnHFbxpJbI551ZS3ZveaT35PrR5gIw3Ws2KYsoLsxx1xWjBcwfL5iD3J6VooGLkAkQDkin716dM9Peo5Lq35XyV9ivcVOJ7Ty8pbtj34quUTY3ap6sRRsX+/R5lo3LBs/U0b7P0f8zRysLn/0sKMsynH8qaqso2gYA9amt42B+9j6VM0A98+ua+VbPpSsIWYfM549BVlUCqDjjvzT4o1JCkkn3NWUQBcbanmFYpvIoPysMntUJmVS3OT6YqZrMByzOFX0pPLhi5DCqGkNhMkoxtIOME+1Yfii4M95FYRvjbgsM9fyrovtAjhZxgBQTXn+mPJqV1d3G4jzN370DkduPyFe1l8LJzkjzMfO9oRNfw3qGqQassWlpEtgi7Wdl+99K39avpZpILM3WLlwS+xM7V/Cuf0vU7jRLIwSwRSopysoOMfX3q9osz6vqnmW5C3DEYypbA/CvRT5nc4U1CNup3/AMPdCe3XfLOs0AJbITBJPbmvQIJWkcpGdq44DcflVLRbBbLTI4C5kbGWZu5q20UYH7tMtn7v+FXcwk7l6wCtO1vcjcHHDD17VppbPZeSyLlBlH/pWRb/AL7A5WQnjP8AjXQ2D+Y4hZy3mIeo9KpEspXn7woFAUsxJPtVqF1uBwmYkYRrn+I1CkAkZI2ztVOfUZOK2IbRAqbWCpH8qj09T9aptIncYbcDhVLnuRiuS8X+G49YsJomgJZhyGI5ruLWBEYiJwFPPPc1b+zow5A9+KlyHG6dz5T8QeH4tBFm5DGZpMAddqjpn2pNUi06WGZ7hYw4Qk8V6p8U9FntZDPDA0trICSAuSp+uK8K1C6kMro8ZWIDO1uGb3x1rCpHqdiq8yszjLlx5rMpO0ms66uAoIyK37y1inBMQCHPJUcY9cVy2owPHJ91jGej9jXPYq5CXDBjuA+nNLb481RgnPQ1HswBnnPUUAbeR909qpC3NtBtK7l254JzQSCxxhVIyBVSC4dxnO7PUEc1O8sYUkj5h1B4IpkkgUnozY9M96VX2swb8M9v/rVCkzBiAA3cNUnmbuRjdnkUCJ2PJ2ybfYUm4/8APU/lVSR9xBI3nHXFMyP+ef6U7isf/9PK81Iyd0g/Ckkvrfb1yfzrDKqRjqT0zTtu1duMHrXhrA92exLGR6I1W1LbxFExB6E8U1tQlHDDbmszcQMAs3qMUvm/Ke56etbxwdNGUsXN7E5vncsFIGDjPWoPMaRiGJY549qYWLAngDuMU6JVDA43Aen6VvGlCOyMpVpy3Za1OHytGlg80iSYbSR2z2rIt0SGIRxngdeOtX7mWadl81AFXgBT7daoOMMO3PBFbOXRGVurHqdwZZF3IeMEV23wlt4IpbmCdw7k713LwBXDrIBwc8cV6D8K4EudSlZ22hV4NXTk9iJxVrnpV1PDDACM/U8D8K5ifW7mM77lUs7Z2+WadwqsPxOa3/EELiyne1VJJIkLokh4bA6V8q65dS6xefb9Tlnu55GLYZgCn/TNc5CL06Dp6mumCOZn0lB4kt5ruBBKqyA4Zd+5TjowNd34avxc6n8pDqqszEdu1fI1vfw2en2V7ZxXFvas5hkWWUOPMVdzsrf3McduR0619HeC7tNP8O3N3dNsMjAAtx8g55+tXy2Ym9D0B5FTU1yv7tgQx9OeKyZNYlgtpnY5UMRyf881Wk1RZb+KVmPkyEZI7GuT+Jl0umWt7MGdYAPPOznngnHvx096JRuKDsdSdcjYOsF0GnXB4PGfQetdb4b1Ke5iCXagSjr718i65G411UvX1CR3UStFalBtLD92oLHBBGcnjBFev/AHVb+W5vNOnnlmi8tZ44ZH3+RyQVVjyQcEjJ47cUpRshrVntmtRwPplwbtgkKoWZycBQO9fIHi+a0utXup7BRFbyOcdSWA6MT7/pX1X46VpPB+pqkwiPkt85OK+P8AVG/fOVbcuMsBwR/Q1zzeljaC1uZzLuc4wrMSeOlUrmAyRY4OOqd/xFWXYrCrHYeMg+uPaqbTksCoLHbjbnkEdxXO2a2MLUdPZWBtgXBySueRWZgqMHdkdcjBrqd6vkr8r5wxxwfr70y9t1uvvgK4GC2OeKdwRzkMjRkFSVPQ1ceSKRAwKt7d80y8sJ7bDMNydcj0qtbNHFKMgYJ7800waLSMM5UN6+mKkYFyWHDE9KZLcKvbrxkVXeZlJIG7+dUTYlJyxyxB9M4o4/vn/vqoo7lWGQ3/AI6DTvPH97/xwUwP/9TjdxEnC4wepqYSA8sxByMDGc+tR+WzksB09T3pgUqcuxB7c1zG5MJdnXkk4ORUMj4bKjOetPcgEeU3JGTmojIxcgjkjOcUDQ1yMl1Yqw4IByKUPgcAk9M0z5cjHGe/oalChQckkfWkUkR+YwJ9DTZj0AOD6GnYGSQeDzzTRG80qrGmSxAUL1zQtRjEBOG28cc16H8MpoRf+WJQsmCSrLwfoaydI8LCRS1xMNy8BAOD+NdfpVvb2Bh+zxqEY8kDOR/OtYqxnN3Ru+K5Xt7N9v3ACcpwenvXht7pmmam7efHJHdE/MyNtDnqSBXu2sQ/aLBgSWymBXA6b4WWHMly4DAnaAOnPAFbxkkjFK5xGm6Q13e28V3aGKziyVLSliF6kFTxg121zfTDTbe0jkAjUD92WBAXt/Wpbu1WGGRp2CS7sfuxndWPawHyZfJTEof5zIcEk8gj61akJxOv0jVZJ7dYWYBVTHoRyAcGtDXtIbVNPaHe0iqu9VY8M2OCe/0rk/DojS8EYbap5bb1HPTFeh6CVkcRiQPuHVh0puRPLqeX/wBg3OtXIg1UCAxxkR5TOUz0BNejeAdKt9FvrVNPfzZW/wBdKrZz2x/TtitbW9HnjQpbRZByw4HX29D+hqH4eWlxa6xP9qU54Ctsxj60nK6G1ZnovieOCXw/cC7iWWIJkoVJz+Ar441yJ49UuAFaMiU4GMYGf8K+t/iFqB0zwjeXETL5gAClzgAnivkXViZbmRnbexzuJ6+//wCquaexrBGNMrqoDI2GJClewHof6VSdQoySAT0IFaLvtiwTlf8APSqcw3yHbux78fiPesGaFbZgZkyOM5HXP+FTkB1UHI9Dnr71Lt3YCqSBglum3j9RUZ+TIPBxlfQeuaAEyQ7Zwyk4Oe/0rN1LSVZmaHapPIwML+PvWnDIrRyqvEqjGD+n+elRTyloyGwpPcd//r0xHMOZYn8iVcH1b/PIqKQYfA4Y8+1bV9Esw+YZboCO3vWPdQeXnHKNx16VadwZXC7hnbz3yKXy/wDZH5UZCgAEkeoNG/8A3vzqiT//1cC90m6szlkLr/eH9apc7CCACeg9a9JcIyKjAH5SqH/a7fpXLa3pgQrNajKnl48dD3NZyhbYuM76HMuCWGcfl3pHQjBI5PU1dbByflyD0qpNkglefasjVETICp4G4HoelG5SAJOPp3pHBLcAqcZxTwu5fm4xyf8AGpLG/Kq4X1wM812mgaQltA4n8vz5QGWQHgjGcKaxvDFuk2sRGX5ljRnwRy3sPfv+FdtdBJsp8pBbPmdMA4IYAeh/nW0FoTJkUWIZyFZihcHOc4buP896ntnL3YKKwQngH0zjIqJ8JCySAAgbpI26NjjcPb+tWbMqt0rEBW3bcZx9T/KqIex1MS77fDEYBrJ1GNgS2MIvT1zV5JxFGQUzznNUsm4SVejZxnrRbUlOyOS1IlU+23eIrCLKiQ9T2PWuA1j4j6bb6hKUi81wNuNpK8V3nxQgI0BLKEsqS5496+XrxTDcypOj+Ypx6c55raNkjOfQ9OsviGDeeatvHH/uk5P1r2H4f+I49eijhifyp4zuAU4LD+tfKcEiou8RFuQOO1eu/ByC7udbtLmDfGEZSc8VcloTG9z69t2M9pEqqTIqhSSOD3Bq9ZWqqwkQL8w+8OopdMhUwJIWB3IBwe9WrSRQHOCACee1YGmhx3xigluvCEttEMyO6gEdvevlq4ALy5yxBKtj1Ga+rfG2oINDkuJzGBzsEnAJ6DNfIviW5eHWpn+6Wb5k/wDrVNTYumyOdU4KbQh53DuOx/xqERAsqsgUP078/wBKmR1kCSREFMZYenrio2AwxLfIRgbOOPpXObWFEZVd6hgx4JHp6j0qnIoMfGUAOT3K+/0q2rnORlgBn/Z59qaSGLP8vK7TnnB98fzoBooSQbJGL8KuRj+7xnIx2qKRihCMQRtyuffkH3rQyUUIindnGCM4HtVeaONvkXoM4Yjgn/GmZ2MqR8HzVUq/c9iKryuHByMep4/Wrc+8FiVIKj5ueo9fcVn3AIchcL6kUAQPCMggnBGab5PufzNSyM2RuMZOO5INN3H/AKY/99GnqB//1tkbmuIBtbnpuH0/l/I0TBZPOZVDNxtYds8Yx36VMkpYBt23JzwM59/5UyVoySScI7Fdx49M4+hwfzqiUcjr2m/ZX8yHmFvx2/8A1qwMEb0I285zXo06o+EICyeSUye5z09xXGa7Yvbzu6DbFu2kAdDjsPTrWE4W1R0QlfcxxjCg8sOp74oYYGDyfWpXj+6OAe5Heq28qxDgbc9qyNTrPAcZbUGeMfOo2ru9x0x7118dtufaJCH5Gc5AJ4OB/nvXL+B0AtLxnzskbaxU/MvHB98E5xW6twd7F/ldn+bafuuOuD3B6/nW0djOW5JdmMxxHywpX5ZB3Bxgj8/8807zUV0kfHzYLHH3WwOlV3VZWeO4fKuehGAGIwD9Ox/Cs1HGzZcZ2lmTPckdQaYWudxaXUF3CURsuBk+9V4mMc7LnaX/AIs9CK5fTprpJTKhbduwT6jFa39rA6qbN40RkCKSx6uf4fwqlfcjlvohni+2jewEkw34bIJbOMdfpXgfjvQ4p9Qe4tWETuoLJ2Y+tfQ17YjU0nWFVynG09BgdK4rXfDqm/td0RiXfsMu375C5OPxIFaRZDXRnhmlaFdvNl/3QBHPrXu/wxt7axaFBhpFIyM/eNZkPh1Rbh7iYyJmNpEC5Zd3Ug9wCR+teheE/Cn2aczLCsflYxk53A45H4U5ajjaJ7Bo04+ydwcZwR1q5bPH5RDYC96wtOkeCyjLsxAIQ5P5ceuKmnuGniVbU7N7YBIyOO1ZsVmc18SL2ya1ZZp0JjyFSNwGBxXzprcMM3mE4khwSFJ5xngg9Rj0r1T4maNLpV79o+f7JcqSW6lXB6Z/UfjXml4wMk54+cgrs5VSOufr+hrOZvBWRzT2j6dM3lr5lszA5zynuaJvlmbDleC27Hv+np+HvWwp2SbSv7rJ+XPPPQe+D3rMvYkC7ShRowd/X5sd/rWLRoU5SSflIDjDNtpiXOPmPUHOM/54qGUNu3q2SUyfb0z7VWSRQScEDdgoTk5NIRd8wIuTzt4BHVc9B7j3pVzsAl+dTyQvUjt9KpGVdoXqRwN3df8AGnzOwIkThwc/NzkDjOPbv7Gglle/bMjW8p2FVLI/19KzyxReAcgYKkYzjvjtVu8lSUkMVUhRtOOG9Oe1UpCkm/eGDL2zz+NMlh55JO0EDsA2MUec3+1/33VZo9+CS2cU3yf96nYR/9fZSTYiQxHOw5Qt2Unj9KS73R3brIm0rh1/iGcf4E81JLbKkJZW3KNwUsc4XPAPp1prvvlUqsYKIduDnevJwf1qyRpiSJsk5Yx5jU8k46f4VXvVLQpKNjiUqJFkPAweCPz/ACNWCipGsy7dsQ39z8vcfnx+NQSKv2Oe3Ukr0SP0TOVwfyH4VLRaZwl/F9mup49uzaxwp/pWdIWO3KnHWuw1WCCdUjuARMrAO6nJwRxn0PQGuWvLdraXEjA5yAezYPWueUbHRGVzqPBZUWM7kZVXJIbovGM+9bc6wxGKNSUiUfMRzx2b3OeD9a57wjuW2uJVGczKuT0xjnNbF0zi3hUM3lLnAbHQ8H+v6VpHYmW46WUMi7mEZOY2RuozVS9Lb4pkyZFKknGD0wCR7460MWZBKoLsQEYnOMj7pNWVgdp0bBJYYHHUdOfypivY6HQNOWa2ABILAk/7OT61lal4Hvt0ElrfxbbZ/NVmT945GSAWzjk98V6L4U08PZgMvygenU1sXmmR+QwfkegqoysZczuea6NqV5NoKHULI2mrSSkSRL8y5LYGGHBGOc0/U/E0dhp0lzqFuEtIGI3TDGSG46/Qn6Cuxs9P3z/MoSMdB3rQv7C2j06YzxI6AZ2soI/Kq0uTdnKeFNR07VZ2TT4YC44dRgkEgN/WuzWyl+0wiYYQkKAB7VyXhTSTB4jN8USMNESIkUADPc4716nZBLhE3LgjB5pysNO5GdKia22FS27rmktbCK3KpHHhB29K1gMCmSkKd46jqPas2O5geLdCttZ0ea1uYwyMOvcH1FfMHi7wte6DqJimVzAf9VPj5ZR6Z7H2r66mCvFhT97msDV9GgvreS3u4Vlt5B8ynt7j0+tTYuMrHx/NgRheNud6Y7/571XMmyRLlgCXXGw859QO+f6Gu4+JXgyfwrqwaLdJY3GWik74HY/7Qzz6jmuE2jYY2YeYuWTuM+g/pUNWNk7mJdo1tM4YEnJ2uvX14qnIVkHyqNm0uGUdD34/p2rZnhWXKFhuYEdeh7fn61g3IeCZsnaRz/kVFgIfOLc7ufZunpmrCSFP9cqk5PIOQKpEjaxQfdHKf3cntUaSGIYYgIT2OcZPUUrEs07hldslA7epGPrxVGR4235CJKc44x78/wBKV7oYDDIABODn9P8ACopwroGXGT19QPX2pksq+aVJ3+YrZ6L0FHnL6zfnRKJFfBUN7hAf50zMn/PMf98LVCP/0NqORIJmjdgUcEK5J2src7T+tRWjopZWKpgBS5O7nOM46kZGM08xoZpE6SBSoZuQCex+lQXjM1yJgESNkBOxM456H2yCfXmrEkOWRzdNbkZyvybj8vPGM/yqsWYNK5gdjFFxg/KRnBHPfr/SrMbh41ZlAeJ9n1HXGPwzVVgsu5UIjyxZWJyvXnkfh9DSGiiyRQyGR4t20LkE/eT+LA78HP4ZrJ1aFCht/wCHeQhAyB3HueMmtuWVTp9tLHtJRwjEN2zkDPpnI/E1nSxpJauIkDMGLIu7p3A+mahq5onYi8LToLG5sLgERbzvbrsz0PuMgVqyb2gjlkKZDbHTPU9D9OoP0rLsp44A5Khre4QKzltu0Hv754/KrG8qyGeVvKZtkjhBkMOenr0GaldjRrqXLKWSedbVgDFPzsPbB+7j2rr7HS/KiHGT3PrXO+FoC2pZ3vIsZLIWUAjtg4r0KBBsUADpQZyep0+jbIrKPoOM1rwwpKhL9/WuWtZSNozworQh1CQXiRFSYyMk1VjNo0XtY4ixj6nktVeZEmgKMAwY459KNTuwkBVTgnvWP/aGyMAcluB/jRewJD7u/gtdRigQAMzYz746V0dtcMl/bRnjd+vFcdPbie7tbgpl0kD/AEFdpavFJEjSD5gcj1FU2g5TakcIuWNZN/eMAvlDLGlneSVyGysfb3qpPn7ydR096QEttfjzTC5wyfLWqirJHkHJrFtGEjbpIhnPWtyJgUAAApAec/G7Txc+B7uQorG1ZZ8nqoB5IP0r5bvgDJvQhWUNuA/Tj0Nfa+u20d7Y3FtKqvHKjRsrDIIIxXxl4ks203Vru1GVmhlKMD09MVLRtB6GDLKPK+dQpxnk4A4+7n096r3KiZPLmAXqQSuWx2x61cvB5kKhsbkOGXjLcdfrVS4ixGisVIJOx+cN7E9qgs5zUEaHaHGM8q6nis5rgglW+YeoGOa6O5TzI3WWIqQTkAdCB+hx+dc1e25Vxn7rcrTViJEsbkmMt3zjHPNSyu5XHBbGCPx//XVGElQN5wwIG48gZ7/hU8UgkJGN7YK7lPJA9KGibk8UihNrZO3jOCad5ieh/wC+TVZpXQ45b3H9fem/aH9H/WlYLn//0dNJ088xoiIkknILEq3H+A7VVEDyozQqdtvkMGPLKJPX6d6tXUYfE8K7W4BGeiMMZ/A8fjSCfNos+SGhYwuwBG1SMrn19D9a0ZKZL9oBaRoliZZcuhT+8vI//XVGWRY3ETj5IySobjCE5B+vanXSyQyxKCrbc+UQeSmMgH8SfzqO+DSeWHYNIWCqeuVHP9f0qCkULiTy4p87NgO51HAHcnB/PP1qrzFdKjyOFZcqzkYJ/p61bt2WSZllG9JA6SoQe3Q49CKzLk+RFLGFwYMQbmOcjJAb9QKk0RDe4yofG5AVKg9Mnj+fWoobktZhA5LLMyE9flIIwfoehqG83LcFo9oVEyDzng8jB9jVQ3LW7vJ8wRuSpPJHFc97TNkrxPTfCS4gMx+V5CN34V3NseAOBXBeFmC6XCYyNrEsMe5rsLGbOAa2Rzy3Olt4gUB7fzqfYyndjGP1pmltvUVoTjbHnbmqJTMi+Uy5JbnGKoRptYAgE9BVu8kIPpUESsxHSpNDa06FZCrHnFbYtshSxxisW1fFuscZKN1yBmughkWSPJAzQTcZJ0ANVS4yVHSrUxXsOcVlyXHkvgincbWhdi+9zitCFgB61hpdofxq5BcPJgRKTmmQ2Wbs/IfWvkv4xWjWnjW+dfmjnbzOD16dPfj8q+qtRkaKzlaTAwpPJr498c3c15rl5K7h2MhHB4Azx/kUmXA5yfMiYRxlcuOc7fXNMkAZSEDlM7XiI+4fUf56dajDsjjblG6FsdSPWllHmOGjX51+Yr1VgeOR3H+eKg1K1wzRyLHIS3m8cc5UdMHsc/4Vj3yh2KSgbcHacc5Fb9x5LLujO5MgkDkx+x9v/wBVZ93a+ZCFYjcQGBPp2xjpQJnJSORmNuvf/wDXUMUjRtlTzV++szGFDMDLkDB4P41mkEHB4NWrGUrmnDcFoxtIXHBz60/zn/vLWRRRyoVz/9LYZIftkieZtUuX8tjjK5Bzn0HIqqSx+220YbcreaF2g5VXzjdU0t39qFvM6IZGGzKfwA5GR3qGeTbPCyo+GUps2An5RySPbj+taEEjlGsUljZ12L5ahlGeOo/A1SnkBtYpolQQIzKyklSuQCp/nUMNztiuY1cZGJ14yp2nkEDsc9aYknnJNBEC0JJZR0JH19Bkj61LKRWuZERwYZDlZcglsA5HTPbg9apamxR52iQyJNtUrnhX65H8/wA6kkHl2/l4BIwisfbkZHbiqcgC2aiJ1di2/buwQR0HH0P51DNEZ090rxMXbAU4xtI4wf8AOaz7oEx7eMklgxbr7fiKvSndIjSAhHG0jHXJwf1ArIbcqnyySc9x0IJ6Vz1VZ3OinqrHqXga5jutLhERyAuAD1rtLNJFYcEV4/8ADrUTDqDxlsA/Mo7cnk17FpMY8xiX3yMck+g7CtYao56iszdtLnyUDMce2adeaySMLwv1qNoo5bZiRgjPFYFwqJJwTkjOM1ozOJee8dkdlwT1AJq7YTs8alxtbHIzmsq2wy7TzWhbRkNwcD0qDW5vWVxmRcmtlZ0hXLvtz3rlkYLJHnP3h+db0UiSnblSyHkHmqsQae7emetY8oMt3JHIRxggCtlE+QcYqrdGO13TOAMDqewosNspN5UUgj6t3zV+PUbe3lWB2VXwMVxul6suoahI6Hcu44/OtDxFLasiF0b7Ttyjqvb/AD2q0tbGbJtc1XzrS+BZAqKwWQHjp3FfJ2vSGWWZ2U7t33uhYZ5x/n0NfSOrXTPo1zHJ5eTEcqMnBxXzZqcaMXKHPPBXqRnkY7EenpUSNaexztwcygLjGT8xOfb86sIWXYQSGjzg54bjpj9cU+4QLI/l5Vn5Kqc7Tjj/ABqDAk4JZHXC59fcVmzUiMgDJJHM3mfeaMc564yafK8UypyoGBhWzwPXH+fWkR1LF0fbOpJfJ6544z06CiU/Z5mnWNxHg5jPPIPIP59PzoEzMv7YmAO4bzNpX689Pr71zlxGwZhw2D174rsjKHDIpDx424bsf6D09657VrRo0V1yF6hj/EPWmiJIxKKD1orQzP/Tvacpez8wZVCflEi4K84z+B4/GgCdoZI4laN495JduTjGRn6kgj3ohu4oZrR8AC4XB25JII6Y7c0pkka6ebkNIxMwLDG4YGQPw/SrIKrxfZ7uxk8lWaWQ2vTHBTdx/jVWAMs6R4fyimAc4+bPp74zUlyFubW6SCTErxll9mTG05HGfaqkrysr3DlkZ1DljzhgMbvxGD7UMor6kZEj3SfM4XMjqucP0PHU4BBrIAjeJnkXCjEoG37qk85x3yDWnNKwslmcMJkjMZKjhjnOf581kXieUSweQRSDHuMgYHHUc1DLiU7xTtM0QMhERPJPGPU9jg8fSsm/cbz2bg/KOBx79+a0Z7wSecHULLGNpXGNwzjbj6Y5rAkmLlnZiMMQwc5+lY1djam9S5plwbXV4mjYqhfGDwff9K9jttcmj+xxRSBGZxk4ySK+fzcPBcM6tnDBlA717F4dnN3pNtcbjEyLuJOCcEetOi+hNZdT1nTp499yvnmR5GztP8OAOK5bxFe/Y9YtTuwjZU/lVjQy15KJoGVIwNvPVvWsPx1BLLp8k6AiaElse1bPexklpc6qyPm3CyI3yleR610FqoYCuC8GXpvNCtZ1PJXafqK7bTZm8tWfHPBIpWEyxMrLKp9DnIra06WNJC+Vy3UjmsmRwwCk4ycVfg2AcgbQelFgudNCylQe1cT8UNTlt/D0i2ILTz/u48d2Jx+nJ/Cuhsb1Z4i44XoPpXG+PZxPe6VapxEGMr4/ugYA/M00IyPDlqdIsbdZnZjwGI65rqbe+B1KGKVkkhlGAG6qfWsLJkn2pkqFJHHB6VFp9vNJPiRSThjGc55x60oattlTVkkW/iBLb2WjXPlOsR53yYx1Hb3r5tuVlWdo48CNmJXI+YHHUfyPNev/ABYuG+yrbO4ZY1GecjcPX1+teOXDIzPKq7gv8LNy+cDHsOOtTIuCKFxH5riVNw2rymSVGDyQe/X8Kq3ELMGkRggI+Ug9uwz71duW3b5ImOH/AI8EbT746DPBFVBG0jCNuCCSQpGf96oKI4pyz52qZU4bPByOCMe9LKSYiy4c4KeW3OfbA6/1FMc4hUpJvTaNpPD5znceOuO1PUsJnmhil8tSSycEuh7g9iP60AUGjaKXaCD2bb0HufaoriYyWpjnUODwB3Oex/Srlwjsd+wLESxJxjPrj3qC6jRMQ7fmjPyuDjIxwc+lUScncQGKUryR2PrUe0+ldY0KTBXeKZ8j70YABpv2SL/n3uv0q7mdj//UdfwSKlwIieWcrswShB4+gxmpW/eXLPEoWPCyg9yvADfn+dSpEFmeGNpIlkRSgIyc8g/UDvWatzLFp8ckMXmyWw2uAw+7k5Hv2x71ZAWTPbavc2srKhlHDL0bPBX2/wAahWXyofKEPyECM7jwQpOBj3GDRrTRRyRzfIjOirIEJJUHvn1qssgW7UOSFlGe/wArkccn7vANDKWpHESkD7xsJJwvvzj8Kw1+awXy5csIwquOd7Dg5HbGKuyORfKm9mDDJZgQFJIx/L9aqXDyDfBGoMal2GR1QnOAOv3hWbLRkySKFuUaMhyMEE9SRj+f86xdXZYVkjB4BDZ9Afatq/iBJfcCowgYjAbpyf8APSsTVG3IwCfKBtwPmbr6/XpWc9jSG5jTSF2QZGCuQfT0ruPBV4Lqxa3muGWIEqVzzj/CvPVfAAA4X5hzn8Pwrb8J3zW+qwKCoVm5/PrUU3Zmk1dHtnht2hsjIPOWON/LTJ557n616Ra6bb3ekoH+YyqW+bvn1rz/AE65aK1eIRM4Y8EDOK77wrJIyoZEbByTnt2ArpbT1OXVaGFpGj/2Jc3VggxA5MkI/u56j862dNlZEEUnDHP5ir2tWzyQJcgfvo8kgdcVl2cnnYkBHzfr7imJs1HlQn5jgg5H1xVqxn8yM7j1yKw7rCyeacdDjnvSrcsiAo2GOByaLCudbauixMFIx0AFcn4hcPr8aLghIOn41bt7nyIWLnavauRN9Lf6vNfIPkDeSoz0Ve/50dATOr0bzEkhbb+724wf8/5xXQGaK2tSqQ7H5wAOhrD0dSSF7YJwTxVm7vQIGiUF3PGQOlQ9Cr3PN/iyp+yRTRqpI4IK54PpXj4ZZVIDb2JGOxIGcrz06V6/8WgzaHbyqSMS9uvTt/OvGC7wyFCFEe5nkBHDHv7jrSZpHYluHTykmDNtIKscZxxnk+2PxrOlVS5Iy2DuBHJ46irZkYXEyhQyhQd3UkeuPbn8qiZAchVAQcBVJyV9R9M8VAytIqSkgkjKsZIxzuXuV9O3SmDiNCmTj5VKtn/JFTSo8PmKwYtHjbtGS30PrUabgciNQECqwLbXYDONuO1MAmjUsjuFMRJDAHJB7MPqexqsmHKqw3OpI3KeGGPX+VTxuZYGCqSrcOd2N3ufQ1DGPObzeOMOseMYx2x7e/4VSJZXlHmENGrbMDaAcbfY575zTPKb/nm//fQqw0EkmCvlHAwQSQQfTjr9aT7JL/dh/wC+moEf/9V+rXIW3iuI4PkidY5SDuYK/XGPQkVmxQJbC8tottsu4x+UF4CkZDAdSAcD8afI32nTZFeRTNGjAR4zjnAA9e3SpBseG1aZd9zsxKytk9hgnt9a1IKlvJI9neJH5anYpBCk7iP/AKxGKz2lcQF9mfLbs/OcYOfwz1rXVo3nWMSL5K/w4x1yOnsOOfWsYDE08TxvuXdIMsCT/DjH4ZGaljTEupH3QyoiTQyhFdS2Pmx29iMfjVTVLp3KvIyfvFMEhC/d9vr09qRIIjMjkxl1K4XcRjJO7B9sAg/hUM0ocNDOyScecVAIPzE8fljk1DKRlXbPKqq+1nHUk434Hyk/WsO+uNzPHHtDuN4RhwPr+BrTnPJjVWZ1/duR/EMf0zXOXgZ5k/ehsqFOOAQO38/yFRJXNIszjjePLb7xAUHtxU2kH/iZ2qnCkzIpbP8AtDNQTBhu8vG9GyCOhFRwyGKdZUK71kyMjuOQf5VlFamzZ9M6XcfZpUP8LcGu60C/Vup56jivLtJvFv8ARLW8jG7dGrkH1xXYaJcB5U+zFlO0ZDDitkcskdyxDOxyTuGK5G+T+xdWKfN9ll+cAfwHvj/Cumtnfy+gVs9a57xwhntUnif94p456itETuXcW9zDlSrg9s1nQRNHdnjMQOQSa4zRfEZkla3kypQ4IP8AjXVrfRLbxSTNmRsgDPJwaZNmTeILsQWzyM2FVSQormvCtx+5Unnc3I9yeatatK92hVsBT2Fc0rTWk6SxMFhJzw3J9PwpNlqJ6/prQwnkEZ7U3Ur1lSQxAEYOMH9awLTWlkixkE8YI9Krx3Et68kok2RjO5ug47VMgXdnPfFi9DaNYW8LR+aZRIQ2TgAdfzryW52TzyRFNr5BVtx6ZHygfnXQeNtV+2eIWyWMUQ2pjJAx15Hf61zsrI7hol4Xp33HqOf6++KlmkdiNchpFCOYwNqknlT6HuBzj8ajeVonuA0hKSMDjbgcdh3xx19aV3uWlVhlZy+LkL09VwegHNMHly2zCNlAJ39MnJ4yCf4f/wBdSUEhcuUCvv3HapXBcYyVHv1qskK4435T7jEYPPY+g4/SnDO1jJJtIbJZm3FD2I9AP602SSURfOEEvTZjhhzg++aYmQkCOO2cqxjILMGbAUnkM3cHrxTZiH8qRRKJCBv28FgPukD19vzq0uLlWjHVCX3Nxt45IPrg85qusw3JDDv8wYCyKMDn0xz+J9KCRC9szN57SRSA4Kgnj8uPejNl/wA95fzahZoYNyGd4GBOQqAhz3bPvTvtkH/P/J/36FMLH//Wq2trKl0Y3khjZBuWJVA3sPpnOQAfzrK0m5jW8uopbcqszsTvf5Rxz9Rnt610M4+2X1vFbOqA27hT/HuBOCAPu8ZFcrcymPUhcTTtLHMRsRh/cyu7/Z5x9a0M0XobxXkg35jmbduDNyGz+vTIqO7mQ3iwQ+ZvkB3SOMnIIOPxBFLMI4wTOsjeXtdpEGNjHjv1J7+grM1cOYdieZl0wsg53c54/DGTSKIYZvKuwAokzk+WRwhPG0/kf8Kr3jfZkaVFQpFIEc+gY9x3x+lTS5iSW9ib91CBIzMAccZJJ9qzrm5W4XymDAyoRnJzux1J+mOfwqWUjLv32XNzbgNuYZQkdl4OffHasC7/AHUiuMKjJkA/hxkdK2b6VFjUFmU8Bxxkf7RH61jSlOYhnzFIIBHT3Hp/9apZSZRkysjfL93GOOSMVVbkbUJ4xg/pV8KGEcgKtsGCSMhyen/66hn2ZUgg7gdpxjPNYvRmid0erfCu887w8YGf51kkAz6ZzivRfDOohcwyna6cc968g+FzxoTEG+67cnjORmvWIdKF3AJIH8uUDIYevvWy1MpaHY6dflmKyuCpUgY9R/8ArrmvEuotNctb2xLSDgKD0xWBNqtxa2/7+PyZ4Djk4D8f/Wrl5PGcT3l5Ku1SMiOTHfHP6iqt3J22LC3P2V3e8jW3kychjinDXvPeNFJKoDj6ZritQndybi6aQsBufdnBOOAKlkvhazQzncsRjGSB1Pp+VJsu56ja3cl1EP3Z6cEng1qaVpX2hGE6g7hjAGBiuV8MazHfxnyxt4G3ntXoekyKEBJ59aZLkzKs/Dcttch5LrFquTtGQT9apeLvEUNhbC1tehG3K1q+OL+W00yR7Y5kKEqCcA4rxe8kkun82eZXcH52blRxwPc03oTHUoXTTXX2hd6PMhBQ5+aTnv8AWlSRVwGMocbVUA8/U/n0FBlLQxpF5jSIAIvl6nq2RSTjKrcW7uWJBlKrwgxnJHQHIwayZsKA0d8u7aGYheM4PHDdMEj370kpiieObarzhvLJGAwXqMAdf6c0x5FEcazIhbBYMxOSCehA+7+NJgRs+yMo2Spyeq4wDj9KQBcRbArhN7D94Ac8n/PP51SvMyIpJBkUhUG09MZIxj8quiL5IljITYdzB1+YHngZ6AjoajVxgyeaxJ+6VbOxvp370yWRI8KqWkKkDEm4qByOoI6gjoaCrSH918oJJUEHII5G4D/JzVeQxrHmI7UYlpFzu2kn72T7Zz9asyAQW/nLuXBxIwY4wOAfQ+lAFYy2ZSPzYWdto9Bj296b5mn/APPq/wD30Ku+TCVUuttnHRx0+nPTv+NHkW/92y/L/wCvTsB//9elqE81lLLJGCJoY2MXUjPB+p757c1l6jC5njTY0jkLLCufl2k/Mo9OOn1rQvHS6CTyQuW+0mFyDnhl/h9+gPas1pDIlncRxhfKdrKUjncCdoP4Y6VqZosZM8T2qSpMhzHuf5QCRknd3OCo/Csnc0PlJ5zO6yeWoIIOAcdOxOTUsJRlICLkDOI8hQOAPzK/zrIubn7RO6gXGCWUE8c55PHX+lIZZuGa1imidV3RHchkA3DIPPPXkVj32ZbeSKJ8MsIdGA7/AN32HFJP9qhaDCrLt/dK7ZyCCc5JPWq0lwVeKdVZR0fcepY8/h7VLGZd3KHh+9mNkDL2yD3JqjCplZZMAZyCSvJIxjPp9KkvEMeEeTcqT7Sq/wB1uhH0zVW+OI3KOFBy6r1x259wR+tQy0TmJAZmQsoJPAAwOec/0qjdzZRh0IyOR+XNWgpfzHw3zJ849Scc/hWddTGRwwBXcg4Pt3/WoaLTO0+Fx/064JJKnC5PPPf9MV7ZpU5hhKBtw9a8i+GunyxweYw5c5x7dv6V6ZaRvbps3lifmJNaRMp7nO/FW+ddMhWIHM0vlsfQY615SQdzRYO0ccH73oM16V8TrV7rSIpM4WOUbuccEYry0sfMPmEb9vAx3B4+tTUvcumtDet7hLq3dZPvoioYwc9eB14yKVdqhoHYqSNwU8bWHb3HesvTSr3EayAv1y2BkMeg9Pyq/eDCPMrYVto3vy2d3X8OBUp3RbRf8KXzwas0C8IRkH0weRXselX6lBz2HFeEaPc7L9mZ8vz6duwr0/Rp5Vgh2HG5vmJq0yGrnT+MSLzQHwP3i8ocj0rx1SSsSxuPNQlRg8cdDk+1ewSIl5YtDKDscbeO1eXa3bPY30lvKv75W3Jhck++enSnJ3FDQyJXMPzwPhvvB1JGWzwT9OakBCF5YSYoy21huO1m6n255/nUV06G2KMWdlPHPzEkc7f51ExlW3hiIVjt4Ycqx+vU8Cs2aE07J9pkW1KJbSBfLxn5SOfmJ9T2p0b75t43LJgglucDPIx29PXmoVDi2ghmiKlWZkZ27H+friqzlhL+/jkJdvukAfMOjccdPehCLkjMxDIS0TgDnB+bsCPpio42YySkEjIPQDPXgjsB2oidnKy28e5wGVxwpcduT9Cc1HNJjaPMUshyGA+Zhj7o9896olk0UcaTSlGKu2C0bHPJwMAdMe9RQrsllheML5RBAYfe5+6M+nX3pAY7kxybJN+CfmwF+gHtUlwkUbmTAOzHDccEdvx6fjQAkX2iNMQmEL1w74IP5U/fe+tt/wB/D/hT45l2A4ijHYbhjFO85P78X/fQpAf/0OP/ALQuJGS6nSNDPG0Mg3EiNhg5UDjI9abMjfY3UyKRmOVhuILbT8zYPA65/GmLGzC3iiyNzNHcBgVIGM/UnoO3eltpo5ZPLllYEQsHBB2vjqPyHGK0MyCe8CWtxcW7BZIAcqTnocjHoQD16c1Q3iaTLNEJUYg8FcZG4/j0q1MDbwyLE8LZ25VPmcqe7H2P9az7xpppGlBVHjkSQucDKhcALigaK9xIRaLvw6m5VuGO8YxxnvVGebzYpztIDt8xLDAGScipdTtw8zeYzgySbhuOCflyDx0zzx7VhQyLLGgcZlYfPsPJKnnjsCBipZSH3Vwk94+yKRIwo5PY4wf5Cs6MqsARgG3A9OOOhJPfjn61ZuXLK7JtypCAk+/p9O9VVUiQRAfN5ZUDOc5PH51BRbWUQiInJJx94cEdCD+HNUVi82+WBSeHwwxxtzn+VWJnEkSq5GyMYySO9VxK51GBwcM6jdg+9FgvY9e8P3C20UESKAWxyK62F/3pDPyR09K880q6jFxaR7uBlmPsB1/OurjmiENxdbiNuAc+gFWkSzI8d3yTaDcRocFZRyR1A5OPfGa8uZ3SZXVSSuMMRyT6flXY+O9QV2gtrYkL/EF+nWuSkJWRpF8tE2nDMehGeg9+KxqvWxpTWg5WZXU8fIMAggHk9B+OK0NOuGks5FYRmQExsqnJAPJbP1rB3lEQFcHbsGR0GfT3qa2uJre4EisVXo68cg9amJbLjSi2uD5Z3Fm4yPzr0vw7eiS2g6EgA8eteaa+qukbWysYUUFnPcn7pHqDmuj8IXCpauJT90YIz09q0RDPW9LuN9oJenPftWB8SoY5bRLxUBkhwG5xxnPPtVfQrq4eK4UufLUkf4Gk8QXJ/sImVsyMuDgZ4BqiepxEbGB0QM4aQFMk5OT0I9AKqxrI8axmVXIDCNgcPnpyenPpU0uZhvdmIjDHzGXnJ44A/Dk1CLlDNJKIj5WfKPmc4HTI7cVmyyF4laAbSY2UhzyWYY+U59MUjhhE26XdufDIOxA6g/lU9zGkDOh3MxOFyeWY/wAXp0qCdRHcKIgpU/eGcDHr64/CgTHzTzRujvxxtCsQd3QkAd+lTrGsNwJoNzCXjYmAyDGTk+vNQTKVvokk2+Zjewzk4OcfTp2p1hMsbSq6ICMMSeEJP09RwfpTRLGXTuy3JMYldTlTuIAJA5Bxzx60oKwApNuLScFnU/KcdMenSrtwrSndLtiiyw8sZXkY+bj0HaqaSPIZFaXZMzjl+uOn6imBYltoC5DTS5X5cIh2j2FN+yW//Pa4/wC+DVfzhF8rxrJ6ZY/KPSk+1p/z7J+dAz//0eIs7sPE1yxkZfPLRqMlgCSp5/8AZj2qNWlhvFElujrG7wIuc/Mw35H60ac6R200AEgdGYjzBkHAyFx7AD8ahvWEkMV0hybiFZsrASwbg9c4B7fStSBodFddqlMkRsH55x/I8Z+lQ6hMkSoFDvb3afcIH3gMcY6DAqzeS+Zps86yKEJWUYGFPcjP1zWLfxqmnSFuEiYTKH+XdxnPHUc0gG3W8Rx4PmPEQZQrg5AO0En1ya5i8jeOSTzEJQMGC7sYyfu/yrVubiNvkHmLBJ+7YFQvvj3zmsaQ7IFEo2oG37Qc7sr0PvUspEU8QQzxh1McijaoJPP/AOuoyY+GjG5w2w+rbe49hTppSDCxyE3CNsN97FL5QS4nTaEymVOMYz0+ueagoLeXchKLzMCWbbnYCew74NE6swdmj/iBLnqO3PpUaJICqSlcn94oHU5PT8OKuTSATKy7t8p6Y4IA+YCgRqeHL82xljvPvqAFz6f/AF81t6hrrf2XdQcHzFbODx0ycGuTUNtESpgEAJz94Y9TUDFliClo/M7Acge2aTm1oUop6k15dTXUhLMxYYwAeDx/niq6E+cnlklj1YdARxgU0bgRLCXQEABcZz789KXAAM3IyclupPHH+NZt3NELJtciY4EmRuHrg/zoz8zjP8W0DOMD3+vSmXCl4CWRdjMzADjB9fekZS53s+GztyePcHikM07KR5bV4Pm3kgqM/eHQjnsMGp7cPZtiNzLCw529gRwff0rMsZ3jmU5XeOCzDOcnBx+Ga3YiyvGJH2h28vjrtBJBFaRZDRu6LqrSxsFY7jIhbtxgVL4kZzYSRiRmU7juXIOM9B3rmoN9soeMDLyY2pySBnr6DpVpr2WQrIHKggqrnoCSRnn/ADitHIztqM+0qdNMRcfNjzNmV3MD1+mOKJGeG4iRW3KQyqvGAcjn0xUeRGUdspBIhjVn+cj1P4mpsqsO12UFMqTt2gZ7jH5/jWZZG9r9oQxxDdKp3KxfhYx0P1zUfm7pwZN7MPkdcbA3oRnk+uaeMmZJVffPC2xUZtu5O5PtRIFiuknCqSVbqS2Rnjn0FMGRIeGk+0J5QBVmZtzH0x6dcU6yieW6i2HayN5bKgyoXGefbNMtVR7aTaqJchvNQspIY4yc1JHtaOCba6x/e2s2N+SeDjvn1oETWbM7hnkJtSXVzt6jPT86a7Ml08YOWwCCB8ysAfyB7UvlLIA0cu5wSyxrwgcDO0n6elOsGNxAJCpVfm2ncCRnkr/vDFAFT7WqvIzMWkdt0hPdun9BR9uX/Iq2b2GABCrqcZIBXqfwpP7Th/2/zX/CgNT/0uHhtoYbvU1jmcqr70hXO7kc+uRVCQMNHMSnKrcKu4HB2sRnIHfGRTkuxFqMdxYo6t5Yi6bQecFR69Cc1XiuHubW9tVXZHboSsifKHYc5Leozn8K1JRM8MUv2qJWZl8xljJOB93GAv0rNtD5lvG7ts89Dx95iF4xnt1zVuJ44bedh5bSCNHDucA/7f8AnrWWu55opIMxCFsb24D7up21NwMmS5ZIpc3A8xWAchOdwyOp4Pasq5OxmgTCwyLlmAw2fr6mtPUsyFgypyo+deCG6Bj+GKyHQqqvMAzONwO3OSTjd+IqWMnhRpoZklX5/vIi8dOlQ3DOskc+CTj94u7oPrTIfMbBlYjByH3YGO+adMyOk0KgiMKCvHQdyx9qkZJdFBNHI0jNIGxt3AbVI9v50+MsYp1i+bywGDvxgjrx71BMWubdJLeGNRgqcnkYGPxqdZSl3CoPyHjp8pBHP1JNMZJ5nmQQFWVir546AEYz6+tQ3LMl1Lncythsk9u54oUeUJ4nCFgCoOOP7w6fXmkD5iQAAqUOVA5x6moktCojXyJTHvbbyFwOmeeKkmXcknl+YQPuqoHHT/69Q8ZG0g7V3ZA6j059qW2kEIBkOVAyuT+fSs2WOZwUTaNrLgNnnjGajeQefEyjh1AK5xSxAEFM8qeOOnPGTTHOLgfdKEc552joDmgCYKRcqpJ/u4GCT15rVtZJZ4I13/MIyjMFGMA84PsKx7cCJjGjLuGW+XnPt+lXLa4dUjhOAQBt28AZ6j8qpOwM2YJIyrGBFeNztXH8IH3Rn65NWXMiFYj+8VlCu3BXeBkgCqVozqrxh3KFt6yDuMdAPzpxk811aWNsn5imdu0dNxPqeP1qmQLkSiVpMRRFshzyQRwc479h9KjnchEWGONoUYlw5wufx68H86k/dm3KZDLK+0443ADg59BSxfOHG/OTyDwjAfwr684oAlL7sTMqusZ2gOODkfxDoSMYFQqY2eKNhtjYkDLYCSf3cdgaUEs0ilSXRmOclhkYyAOnekkch7dV558zJTqe7e2OPypgRRiMXKyGR1i3ndk5O4cZX2B/nVkKY1IAMQlQ4Rm6vnn8zzVeRhd24nlJd428mYspBbuCQOmev402CIeTsuQzRsQFYnqP4ST2xQBbhP2Vx5h3A8uysCFBPJHvTpo5YLxYYxtSdvmLY5bsQfQgVA8aMYvtIZWEZQ7DgbR1YL79T3qaG4gkRVSFRMqsAX4ynbJ/lSAbPBhx80kZxynHyn06VF5X/TaT9P8ACrMN9BbpskBkkySzYHJp/wDalt/zyP5CncD/2Q==",
                "title": "Image title"
            },
            "note": [
                {
                    "text": "Note #1"
                },
                {
                    "text": "Note #2"
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Media/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Media/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Media",
            "id": "729e5242-bad6-4bd7-905d-9716ae262971",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "status": "completed",
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "operator": {
                "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
            },
            "content": {
                "contentType": "image/jpeg",
                "url": "https://fumage-example.canvasmedical.com/Media/729e5242-bad6-4bd7-905d-9716ae262971/files/content",
                "title": "Image title"
            },
            "note": [
                {
                    "text": "Note #1"
                },
                {
                    "text": "Note #2"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Media resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Media?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Media?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Media?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Media?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Media?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Media",
                        "id": "729e5242-bad6-4bd7-905d-9716ae262971",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                                "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                            }
                        ],
                        "status": "completed",
                        "subject": {
                            "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                            "type": "Patient"
                        },
                        "encounter": {
                            "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
                        },
                        "operator": {
                            "reference": "Practitioner/76428138e7644ce6b7eb426fdbbf2f39"
                        },
                        "content": {
                            "contentType": "image/jpeg",
                            "url": "https://fumage-example.canvasmedical.com/Media/729e5242-bad6-4bd7-905d-9716ae262971/files/content",
                            "title": "Image title"
                        },
                        "note": [
                            {
                                "text": "Note #1"
                            },
                            {
                                "text": "Note #2"
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Medication

Source: https://docs.canvasmedical.com/api/medication/

### 
This resource is primarily used for the identification and definition of a medication for the purposes of prescribing, dispensing, and administering a medication as well as for making statements about medication use.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medication.html>  
Best practice is to utilize this endpoint to find codings to feed the [Medication Statement Create/Update](/api/medicationstatement/#create). These medications come directly from our integration with FDB.
### Endpoints
get/Medication/{id} get/Medication
get
/Medication/{id}
#### Medication read
Read a Medication resource.
### Path Parameters
id required
string
The unique identifier for the Medication   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Medication.
text
json
Text summary of the Medication, for human interpretation.
Click to view child attributes
status
All medications returned from this endpoint will show a status of `generated` since this resource is generated from FDB.
div
Limited xhtml content that contains the human readable text of the Medication.
code
json
Codes that identify this medication.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string
The code of the medication.
display
string
The display name of the coding.
text
string
Plain text representation of the medication.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Medication
#### Medication search
Search for Medication resources.
### Query Parameters
**A Medication Search requires either a code or _text search parameter to perform.**
_text
string
Performs a case insensitive partial search on the narrative of the Medication.
code
System url and code that identifies the medication formatted like   
`system_url|code`.  
Currently a search for an RxNorm code will return both branded and generic medications associated with the RxNorm code regardless of whether the RxNorm code is branded or generic.  
For example, a search for the RxNorm code that represents the branded version of metformin will return a search bundle that contains at least two Medication resources – one for the branded version and one for the generic version. The branded and generic Medication resources in the search bundle can be differentiated by the presence or absence of the RxNorm code for the branded version in the list of codings.
**Search Values Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm|code
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Medication.
text
json
Text summary of the Medication, for human interpretation.
Click to view child attributes
status
All medications returned from this endpoint will show a status of `generated` since this resource is generated from FDB.
div
Limited xhtml content that contains the human readable text of the Medication.
code
json
Codes that identify this medication.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string
The code of the medication.
display
string
The display name of the coding.
text
string
Plain text representation of the medication.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Medication/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Medication/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Medication",
            "id": "fdb-449732",
            "text": {
                "status": "generated",
                "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Tylenol PM Extra Strength 25 mg-500 mg tablet</div>"
            },
            "code": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "449732",
                        "display": "Tylenol PM Extra Strength 25 mg-500 mg tablet"
                    },
                    {
                        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                        "code": "1092189",
                        "display": "Tylenol PM Extra Strength 25 mg-500 mg tablet"
                    },
                    {
                        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                        "code": "1092378",
                        "display": "Tylenol PM Extra Strength 25 mg-500 mg tablet"
                    }
                ],
                "text": "Tylenol PM Extra Strength 25 mg-500 mg tablet"
            }
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Medication resource 'fdb-399234'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Medication?code=http://www.nlm.nih.gov/research/umls/rxnorm|1092189&_text=tylenol' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Medication?code=http://www.nlm.nih.gov/research/umls/rxnorm|1092189&_text=tylenol"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Medication?code=http://www.nlm.nih.gov/research/umls/rxnorm|1092189&_text=tylenol&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Medication?code=http://www.nlm.nih.gov/research/umls/rxnorm|1092189&_text=tylenol&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Medication?code=http://www.nlm.nih.gov/research/umls/rxnorm|1092189&_text=tylenol&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Medication",
                        "id": "fdb-449732",
                        "text": {
                            "status": "generated",
                            "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Tylenol PM Extra Strength 25 mg-500 mg tablet</div>"
                        },
                        "code": {
                            "coding": [
                                {
                                    "system": "http://www.fdbhealth.com/",
                                    "code": "449732",
                                    "display": "Tylenol PM Extra Strength 25 mg-500 mg tablet"
                                },
                                {
                                    "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                                    "code": "1092189",
                                    "display": "Tylenol PM Extra Strength 25 mg-500 mg tablet"
                                },
                                {
                                    "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                                    "code": "1092378",
                                    "display": "Tylenol PM Extra Strength 25 mg-500 mg tablet"
                                }
                            ],
                            "text": "Tylenol PM Extra Strength 25 mg-500 mg tablet"
                        }
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# MedicationDispense

Source: https://docs.canvasmedical.com/api/medicationdispense/

### 
Indicates that a medication product is to be or has been dispensed for a named person/patient. This includes a description of the medication product (supply) provided and the instructions for administering the medication.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationdispense.html>  
### Endpoints
get/MedicationDispense/{id} get/MedicationDispense
get
/MedicationDispense/{id}
#### MedicationDispense read
Read a MedicationDispense resource.
### Path Parameters
id required
string
The unique identifier for the MedicationDispense   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the MedicationDispense.
status
string
A code specifying the state of the dispense event.
**Value Options Supported:**
  - completed
  - entered-in-error
  - stopped
medicationCodeableConcept
json
Identifies the medication that was dispensed. This is simply an attribute carrying a code that identifies the medication from a known list of medications.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string
The code of the medication.
display
string
The display name of the coding.
subject
json
Who the dispense is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
performer
array[json]
Indicates who performed the dispense.
Click to view child attributes
actor
json
The individual who performed the dispense.
Click to view child attributes
reference
string
The reference string of the performer in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Practitioner").
authorizingPrescription
array[json]
Indicates the medication order that is being dispensed against.
Click to view child attributes
reference
string
The reference string of the MedicationRequest in the format of `"MedicationRequest/3423a69c-618d-4cbe-861a-54c60f48744e"`.
type
string
Type the reference refers to (e.g. "MedicationRequest").
type
json
Indicates the type of dispensing event that is being performed.
Click to view child attributes
text
string
Plain text representation of the concept
quantity
json
The amount of medication that has been dispensed.
Click to view child attributes
value
decimal
Numerical value of the quantity.
whenHandedOver
datetime
When the medication was handed over to the patient.
dosageInstruction
array[json]
Indicates how the medication is to be used by the patient.
Click to view child attributes
text
string
Free text dosage instructions. In Canvas this text comes from the `SIG` or `DIRECTIONS` field on the associated command.
timing
json
When medication should be administered.
Click to view child attributes
event
array[string]
Identifies the specific times when the medication should be administered.
doseAndRate
array[json]
Amount of medication administered.
Click to view child attributes
doseQuantity
json
Amount of medication per dose.
Click to view child attributes
value
decimal
Numerical value
unit
string
Unit representation.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/MedicationDispense
#### MedicationDispense search
Search for MedicationDispense resources.
### Query Parameters
****
_id
string
The identifier of the MedicationDispense.
patient
string
The patient reference associated with the MedicationDispense in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
_revinclude
string
Standard FHIR `_revinclude` parameter.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the MedicationDispense.
status
string
A code specifying the state of the dispense event.
**Value Options Supported:**
  - completed
  - entered-in-error
  - stopped
medicationCodeableConcept
json
Identifies the medication that was dispensed. This is simply an attribute carrying a code that identifies the medication from a known list of medications.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string
The code of the medication.
display
string
The display name of the coding.
subject
json
Who the dispense is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
performer
array[json]
Indicates who performed the dispense.
Click to view child attributes
actor
json
The individual who performed the dispense.
Click to view child attributes
reference
string
The reference string of the performer in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Practitioner").
authorizingPrescription
array[json]
Indicates the medication order that is being dispensed against.
Click to view child attributes
reference
string
The reference string of the MedicationRequest in the format of `"MedicationRequest/3423a69c-618d-4cbe-861a-54c60f48744e"`.
type
string
Type the reference refers to (e.g. "MedicationRequest").
type
json
Indicates the type of dispensing event that is being performed.
Click to view child attributes
text
string
Plain text representation of the concept
quantity
json
The amount of medication that has been dispensed.
Click to view child attributes
value
decimal
Numerical value of the quantity.
whenHandedOver
datetime
When the medication was handed over to the patient.
dosageInstruction
array[json]
Indicates how the medication is to be used by the patient.
Click to view child attributes
text
string
Free text dosage instructions. In Canvas this text comes from the `SIG` or `DIRECTIONS` field on the associated command.
timing
json
When medication should be administered.
Click to view child attributes
event
array[string]
Identifies the specific times when the medication should be administered.
doseAndRate
array[json]
Amount of medication administered.
Click to view child attributes
doseQuantity
json
Amount of medication per dose.
Click to view child attributes
value
decimal
Numerical value
unit
string
Unit representation.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/MedicationDispense/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/MedicationDispense/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "MedicationDispense",
            "id": "a47c7b0e-bbb4-42cd-bc4a-df259d148ea1",
            "status": "completed",
            "medicationCodeableConcept": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "244899",
                        "display": "lisinopril 10 mg tablet"
                    },
                    {
                        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                        "code": "314076",
                        "display": "lisinopril 10 mg tablet"
                    }
                ]
            },
            "subject": {
                "reference": "Patient/6cb2a409334943c2b48f1686dc739f11",
                "type": "Patient"
            },
            "performer": [
                {
                    "actor": {
                        "reference": "Practitioner/6c20b7152cf7421791c5ab4113060b3f",
                        "type": "Practitioner"
                    }
                }
            ],
            "authorizingPrescription": [
                {
                    "reference": "MedicationRequest/3423a69c-618d-4cbe-861a-54c60f48744e",
                    "type": "MedicationRequest"
                }
            ],
            "type": {
                "text": "Office-supplied"
            },
            "quantity": {
                "value": 30
            },
            "whenHandedOver": "2023-09-21T18:35:00.000+00:00",
            "dosageInstruction": [
                {
                    "text": "take 1 daily",
                    "timing": {
                      "event": [
                        "2023-09-21T18:35:00.000+00:00"
                      ]
                    },
                    "doseAndRate": [
                        {
                            "doseQuantity": {
                                "value": 5,
                                "unit": "Tablet"
                            }
                        }
                    ]
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown MedicationDispense resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/MedicationDispense?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/MedicationDispense?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/MedicationDispense?patient=Patient%2F6cb2a409334943c2b48f1686dc739f11&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/MedicationDispense?patient=Patient%2F6cb2a409334943c2b48f1686dc739f11&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/MedicationDispense?patient=Patient%2F6cb2a409334943c2b48f1686dc739f11&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "MedicationDispense",
                        "id": "a47c7b0e-bbb4-42cd-bc4a-df259d148ea1",
                        "status": "completed",
                        "medicationCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://www.fdbhealth.com/",
                                    "code": "244899",
                                    "display": "lisinopril 10 mg tablet"
                                },
                                {
                                    "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                                    "code": "314076",
                                    "display": "lisinopril 10 mg tablet"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/6cb2a409334943c2b48f1686dc739f11",
                            "type": "Patient"
                        },
                        "performer": [
                            {
                                "actor": {
                                    "reference": "Practitioner/6c20b7152cf7421791c5ab4113060b3f",
                                    "type": "Practitioner"
                                }
                            }
                        ],
                        "authorizingPrescription": [
                            {
                                "reference": "MedicationRequest/3423a69c-618d-4cbe-861a-54c60f48744e",
                                "type": "MedicationRequest"
                            }
                        ],
                        "type": {
                            "text": "Office-supplied"
                        },
                        "quantity": {
                            "value": 30
                        },
                        "whenHandedOver": "2023-09-21T18:35:00.000+00:00",
                        "dosageInstruction": [
                            {
                                "text": "take 1 daily",
                                "timing": {
                                    "event": [
                                        "2023-09-21T18:35:00.000+00:00"
                                    ]
                                },
                                "doseAndRate": [
                                    {
                                        "doseQuantity": {
                                            "value": 5,
                                            "unit": "Tablet"
                                        }
                                    }
                                ]
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# MedicationRequest

Source: https://docs.canvasmedical.com/api/medicationrequest/

### 
An order or request for both supply of the medication and the instructions for administration of the medication to a patient. The resource is called "MedicationRequest" rather than "MedicationPrescription" or "MedicationOrder" to generalize the use across inpatient and outpatient settings, including care plans, etc., and to harmonize with workflow patterns.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationrequest.html>  
FHIR MedicationRequest maps to the [Prescribe, Refill, Adjust Prescription, Deny Refill, Approve Refill](https://canvas-medical.help.usepylon.com/articles/5128727084-managing-medication-commands) commands in Canvas.
### Endpoints
get/MedicationRequest/{id} get/MedicationRequest
get
/MedicationRequest/{id}
#### MedicationRequest read
Read a MedicationRequest resource.
### Path Parameters
id required
string
The unique identifier for the MedicationRequest   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the MedicationRequest.
status
enum [ active | entered-in-error | cancelled | stopped | unknown ]
A code specifying the current state of the order.
intent
enum [ order | filler-order ]
Whether the request is a proposal, plan, or an original order.   
A Medication Request that corresponds to a refill in the patient's chart will have an intent of `filler-order` while all other Medication Requests will be `order`.
category
array[json]
Indicates the type of medication request. Currently, all medication requests from Canvas are categorized as "outpatient".
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/medicationrequest-category
code
string
The code of the category.
**Value Options Supported:**
  - outpatient
display
string
The display name of the coding.
**Value Options Supported:**
  - Outpatient
reportedBoolean
boolean
Indicates if this record was captured as a secondary 'reported' record rather than as an original primary source-of-truth record.  
Currently this will always be False from Canvas.
medicationCodeableConcept
json
Identifies the medication being requested. This is simply an attribute carrying a code that identifies the medication from a known list of medications.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string
The code of the medication.
display
string
The display name of the coding.
subject
json
Who the medication request is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter created as part of encounter/admission/stay.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/f7663d7b-13bd-4236-843e-086306aea125"`.
type
string
Type the reference refers to (e.g. "Encounter").
authoredOn
datetime
When request was initially authored. In Canvas this corresponds to the time the command was created.
requester
json
Who/What requested the Request.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Practitioner").
performer [deprecated]
json
Intended performer of administration  
This attribute is deprecated and will be removed in a future release. It currently (and incorrectly) contains information about the dispenser of the medication. Canvas recommends disregarding this attribute. Information about the dispenser can be obtained from the `performer` attribute under `dispenseRequest`.
reasonCode
array[json]
Reason or indication for ordering or not ordering the medication.  
In Canvas this represents the indications on a Prescribe/Refill Command.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/icd-10-cm
code
string
The code of the indication.
display
string
The display name of the coding.
note
array[json]
Information about the prescription.
Click to view child attributes
text
string
The annotation - text content.
dosageInstruction
array[json]
How the medication should be taken.
Click to view child attributes
text
string
Free text dosage instructions. In Canvas this text comes from the `SIG` or `DIRECTIONS` field on the associated command.
timing
json
When medication should be administered.
Click to view child attributes
event
array[datetime]
Identifies specific times when the event takes place.
doseAndRate
array[json]
Amount of medication administered.
Click to view child attributes
doseQuantity
json
Amount of medication per dose.
Click to view child attributes
value
decimal
Numerical value
unit
string
Unit representation.
dispenseRequest
json
Medication supply authorization.
Click to view child attributes
numberOfRepeatsAllowed
integer
Number of refills authorized.
quantity
json
Amount of medication to supply per dispense.
Click to view child attributes
value
decimal
Numerical value.
expectedSupplyDuration
json
Number of days supply per dispense.
Click to view child attributes
value
integer
Numerical value.
unit
string
Unit representation.
**Value Options Supported:**
  - days
performer
json
Intended dispenser. In Canvas this represents the pharmacy the medication request was sent to.
Click to view child attributes
display
string
Text alternative for the resource.   
This display name concatenates the following information about the pharmacy: Name, NCPDP ID, Address, Phone, and Fax
substitution
json
Any restrictions on medication substitution.
Click to view child attributes
allowedBoolean
boolean
Whether substitution is allowed or not.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/MedicationRequest
#### MedicationRequest search
Search for MedicationRequest resources.
### Query Parameters
****
_id
string
The identifier of the MedicationRequest.
intent
string
Search Medication Requests by specific intents.
**Search Values Supported:**
  - order
  - filler-order
patient
string
The patient reference associated with the MedicationRequest in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
requester
string
The Practitioner reference associated to the MedicationRequest.requester attribute in the format `Practitioner/6c20b7152cf7421791c5ab4113060b3f`.
status
string
Search Medication Requests by a specific status.
**Search Values Supported:**
  - active
  - entered-in-error
  - cancelled
  - stopped
_include
string
Include referenced resources in the search bundle. The supported value is `MedicationRequest:medication`, which adds the referenced Medication resources to the response.
**Search Values Supported:**
  - MedicationRequest:medication
_revinclude
string
Standard FHIR `_revinclude` parameter.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the MedicationRequest.
status
enum [ active | entered-in-error | cancelled | stopped | unknown ]
A code specifying the current state of the order.
intent
enum [ order | filler-order ]
Whether the request is a proposal, plan, or an original order.   
A Medication Request that corresponds to a refill in the patient's chart will have an intent of `filler-order` while all other Medication Requests will be `order`.
category
array[json]
Indicates the type of medication request. Currently, all medication requests from Canvas are categorized as "outpatient".
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/medicationrequest-category
code
string
The code of the category.
**Value Options Supported:**
  - outpatient
display
string
The display name of the coding.
**Value Options Supported:**
  - Outpatient
reportedBoolean
boolean
Indicates if this record was captured as a secondary 'reported' record rather than as an original primary source-of-truth record.  
Currently this will always be False from Canvas.
medicationCodeableConcept
json
Identifies the medication being requested. This is simply an attribute carrying a code that identifies the medication from a known list of medications.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string
The code of the medication.
display
string
The display name of the coding.
subject
json
Who the medication request is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
encounter
json
Encounter created as part of encounter/admission/stay.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/f7663d7b-13bd-4236-843e-086306aea125"`.
type
string
Type the reference refers to (e.g. "Encounter").
authoredOn
datetime
When request was initially authored. In Canvas this corresponds to the time the command was created.
requester
json
Who/What requested the Request.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Practitioner/ed1e304acdb847148338c6b0596d93fd"`.
type
string
Type the reference refers to (e.g. "Practitioner").
performer [deprecated]
json
Intended performer of administration  
This attribute is deprecated and will be removed in a future release. It currently (and incorrectly) contains information about the dispenser of the medication. Canvas recommends disregarding this attribute. Information about the dispenser can be obtained from the `performer` attribute under `dispenseRequest`.
reasonCode
array[json]
Reason or indication for ordering or not ordering the medication.  
In Canvas this represents the indications on a Prescribe/Refill Command.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/icd-10-cm
code
string
The code of the indication.
display
string
The display name of the coding.
note
array[json]
Information about the prescription.
Click to view child attributes
text
string
The annotation - text content.
dosageInstruction
array[json]
How the medication should be taken.
Click to view child attributes
text
string
Free text dosage instructions. In Canvas this text comes from the `SIG` or `DIRECTIONS` field on the associated command.
timing
json
When medication should be administered.
Click to view child attributes
event
array[datetime]
Identifies specific times when the event takes place.
doseAndRate
array[json]
Amount of medication administered.
Click to view child attributes
doseQuantity
json
Amount of medication per dose.
Click to view child attributes
value
decimal
Numerical value
unit
string
Unit representation.
dispenseRequest
json
Medication supply authorization.
Click to view child attributes
numberOfRepeatsAllowed
integer
Number of refills authorized.
quantity
json
Amount of medication to supply per dispense.
Click to view child attributes
value
decimal
Numerical value.
expectedSupplyDuration
json
Number of days supply per dispense.
Click to view child attributes
value
integer
Numerical value.
unit
string
Unit representation.
**Value Options Supported:**
  - days
performer
json
Intended dispenser. In Canvas this represents the pharmacy the medication request was sent to.
Click to view child attributes
display
string
Text alternative for the resource.   
This display name concatenates the following information about the pharmacy: Name, NCPDP ID, Address, Phone, and Fax
substitution
json
Any restrictions on medication substitution.
Click to view child attributes
allowedBoolean
boolean
Whether substitution is allowed or not.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/MedicationRequest/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/MedicationRequest/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "MedicationRequest",
            "id": "3423a69c-618d-4cbe-861a-54c60f48744e",
            "status": "active",
            "intent": "order",
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/medicationrequest-category",
                            "code": "outpatient",
                            "display": "Outpatient"
                        }
                    ]
                }
            ],
            "reportedBoolean": false,
            "medicationCodeableConcept": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "244899",
                        "display": "lisinopril 10 mg tablet"
                    },
                    {
                        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                        "code": "314076",
                        "display": "lisinopril 10 mg tablet"
                    }
                ]
            },
            "subject": {
                "reference": "Patient/6cb2a409334943c2b48f1686dc739f11",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/bdadce18-098b-40dc-8bdd-ef8481bd999a",
                "type": "Encounter"
            },
            "authoredOn": "2023-09-21T18:19:36.106449+00:00",
            "requester": {
                "reference": "Practitioner/6c20b7152cf7421791c5ab4113060b3f",
                "type": "Practitioner"
            },
            "performer": {
                "display": "Name: CVS Health #68534|NCPDP ID: 0068534|Address: 1 Cvs Dr, Woonsocket, RI, 028956146|Phone: 4017702500|Fax: 4017704486"
            },
            "reasonCode": [
                {
                    "coding": [
                        {
                            "system": "http://hl7.org/fhir/sid/icd-10-cm",
                            "code": "I10",
                            "display": "Essential (primary) hypertension"
                        }
                    ]
                }
            ],
            "dosageInstruction": [
                {
                    "text": "take 1 daily",
                    "timing": {
                        "event": ["2023-09-21T18:19:36.106449+00:00"]
                    },
                    "doseAndRate": [
                        {
                            "doseQuantity": {
                                "value": 5,
                                "unit": "Tablet"
                            }
                        }
                    ]
                }
            ],
            "dispenseRequest": {
                "numberOfRepeatsAllowed": 3,
                "quantity": {
                    "value": 30.0
                },
                "expectedSupplyDuration": {
                    "value": 30,
                    "unit": "days"
                },
                "performer": {
                    "display": "Name: CVS Health #68534|NCPDP ID: 0068534|Address: 1 Cvs Dr, Woonsocket, RI, 028956146|Phone: 4017702500|Fax: 4017704486"
                }
            },
            "substitution": {
                "allowedBoolean": true
            }
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown MedicationRequest resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/MedicationRequest?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/MedicationRequest?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/MedicationRequest?patient=Patient%2F6cb2a409334943c2b48f1686dc739f11&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/MedicationRequest?patient=Patient%2F6cb2a409334943c2b48f1686dc739f11&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/MedicationRequest?patient=Patient%2F6cb2a409334943c2b48f1686dc739f11&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "MedicationRequest",
                        "id": "3423a69c-618d-4cbe-861a-54c60f48744e",
                        "status": "active",
                        "intent": "order",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/medicationrequest-category",
                                        "code": "outpatient",
                                        "display": "Outpatient"
                                    }
                                ]
                            }
                        ],
                        "reportedBoolean": false,
                        "medicationCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://www.fdbhealth.com/",
                                    "code": "244899",
                                    "display": "lisinopril 10 mg tablet"
                                },
                                {
                                    "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                                    "code": "314076",
                                    "display": "lisinopril 10 mg tablet"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/6cb2a409334943c2b48f1686dc739f11",
                            "type": "Patient"
                        },
                        "encounter": {
                            "reference": "Encounter/bdadce18-098b-40dc-8bdd-ef8481bd999a",
                            "type": "Encounter"
                        },
                        "authoredOn": "2023-09-21T18:19:36.106449+00:00",
                        "requester": {
                            "reference": "Practitioner/6c20b7152cf7421791c5ab4113060b3f",
                            "type": "Practitioner"
                        },
                        "performer": {
                            "display": "Name: CVS Health #68534|NCPDP ID: 0068534|Address: 1 Cvs Dr, Woonsocket, RI, 028956146|Phone: 4017702500|Fax: 4017704486"
                        },
                        "reasonCode": [
                            {
                                "coding": [
                                    {
                                        "system": "http://hl7.org/fhir/sid/icd-10-cm",
                                        "code": "I10",
                                        "display": "Essential (primary) hypertension"
                                    }
                                ]
                            }
                        ],
                        "dosageInstruction": [
                            {
                                "text": "take 1 daily",
                                "timing": {
                                    "event": ["2023-09-21T18:19:36.106449+00:00"]
                                },
                                "doseAndRate": [
                                    {
                                        "doseQuantity": {
                                            "value": 5,
                                            "unit": "Tablet"
                                        }
                                    }
                                ]
                            }
                        ],
                        "dispenseRequest": {
                            "numberOfRepeatsAllowed": 3,
                            "quantity": {
                                "value": 30.0
                            },
                            "expectedSupplyDuration": {
                                "value": 30,
                                "unit": "days"
                            },
                            "performer": {
                                "display": "Name: CVS Health #68534|NCPDP ID: 0068534|Address: 1 Cvs Dr, Woonsocket, RI, 028956146|Phone: 4017702500|Fax: 4017704486"
                            }
                        },
                        "substitution": {
                            "allowedBoolean": true
                        }
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# MedicationStatement

Source: https://docs.canvasmedical.com/api/medicationstatement/

### 
A record of a medication that is being consumed by a patient. A MedicationStatement may indicate that the patient may be taking the medication now or has taken the medication in the past or will be taking the medication in the future. The source of this information can be the patient, significant other (such as a family member or spouse), or a clinician. A common scenario where this information is captured is during the history taking process during a patient visit or stay. The medication information may come from sources such as the patient's memory, from a prescription bottle, or from a list of medications the patient, clinician or other party maintains.  
<https://hl7.org/fhir/R4/medicationstatement.html>  
MedicationStatement resources can be created in two ways in the Canvas UI:
  - [Prescribe commands](https://canvas-medical.help.usepylon.com/articles/5128727084-managing-medication-commands#prescribe-command-7) create [MedicationRequest](/api/medicationrequest/) resources, but these `Prescribe` commands are also represented as MedicationStatement resources. MedicationStatement resources that were created with a `Prescribe` command will contain a reference to the related MedicationRequest resource in the `derivedFrom` attribute.
  - MedicationStatement resources can also be created with the [Medication Statement command](https://canvas-medical.help.usepylon.com/articles/5128727084-managing-medication-commands#medication-statement-command-1)
### Endpoints
post/MedicationStatement get/MedicationStatement/{id} put/MedicationStatement/{id} get/MedicationStatement
post
/MedicationStatement
#### MedicationStatement create
Create a MedicationStatement resource.  
If `context` or `extension` is provided, the MedicationStatement will be added to the existing encounter (note). If it is not provided, a new data import note will be created.  
Create requests support either `medicationReference` or `medicationCodeableConcept` in the request body; Canvas recommends using `medicationReference`. Medication identifiers for `medicationReference` can be obtained from the [Medication search endpoint](/api/medication/#search).
### Attributes
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Canvas recommends sending the note identifier extension or the Encounter reference, but not both. If both are supplied, they must both refer to the same note. If neither is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.
Click to view child attributes
url
string required
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string required
The valueId field is used for the Note extension and will be the note's unique identifier.
status
string required
A code representing the patient or other source's judgment about the state of the medication used that this statement is about.
**Value Options Supported:**
  - active
  - entered-in-error
  - stopped
medicationReference
json
What medication was taken.   
Canvas recommends using a medicationReference on create/update to ensure a proper medication lookup is done on validation similar to our commands framework on the Canvas UI. Use the [Medication search endpoint](/api/medication/#search) to help find the correct FDB ID.   
A create/update requires either a medicationReference or medicationCodeableConcept when making a request
Click to view child attributes
reference
string required
The reference string of the medication in the format of `"Medication/fdb-449732"`
display
string required
The display name of the medication
medicationCodeableConcept
json
What medication was taken.   
Canvas recommends using a medicationReference on create/update; however on a Read/Search the medicationCodeableConcept will be returned to allow visibility into all the coding associated with the medication (e.g RxNorm, FDB)   
A create/update requires either a medicationReference or medicationCodeableConcept when making a request.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The url of the medication coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string required
The code value of the medication coding
display
string required
The display name of the medication
subject
json required
Who is/was taking the medication.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`
type
string
Type the reference refers to (e.g. "Patient")
context
json
Encounter / Episode associated with MedicationStatement.  
Supply an encounter reference to be able to insert the command into a specific note on the patient's timeline. If no encounter or note via the extension is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.   
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string required
The reference string of the encounter in the format of `"Encounter/948b54e2-40b7-4648-bfce-e2373f9802af"`
type
string
Type the reference refers to (e.g. "Encounter")
effectivePeriod
json
The interval when the medication is/was/will be taken.
Click to view child attributes
start
datetime
The datetime string represented the start time of the medication in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.
If omitted this will default to the current timestamp.
end
datetime
The datetime string represented the end time of the medication in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.
If omitted, this field will be left empty.
dosage
array[json]
Details of how medication is/was taken or should be taken.  
The `text` attribute for the Dosage object contains the SIG.
Canvas will only ingest the first item in the dosage array.
Click to view child attributes
text
string
The SIG of the medication
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/MedicationStatement/{id}
#### MedicationStatement read
Read an MedicationStatement resource.  
Read responses will always contain a `medicationCodeableConcept` regardless of what was used to create the MedicationStatement.
### Path Parameters
id required
string
The unique identifier for the MedicationStatement   
### Response Payload Attributes
id
string
The identifier of the MedicationStatement.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
status
string
A code representing the patient or other source's judgment about the state of the medication used that this statement is about.
**Value Options Supported:**
  - active
  - entered-in-error
  - stopped
  - intended (Medications where the effectivePeriod.start date is in the future)
  - unknown (Returned when the source state cannot be mapped to one of the other values.)
medicationCodeableConcept
json
What medication was taken.   
Canvas recommends using a medicationReference on create/update; however on a Read/Search the medicationCodeableConcept will be returned to allow visibility into all the coding associated with the medication (e.g RxNorm, FDB)   
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The url of the medication coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string
The code value of the medication coding
display
string
The display name of the medication
subject
json
Who is/was taking the medication.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`
type
string
Type the reference refers to (e.g. "Patient")
effectivePeriod
json
The interval when the medication is/was/will be taken.
Click to view child attributes
start
datetime
The datetime string represented the start time of the medication in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.
end
datetime
The datetime string represented the end time of the medication in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.
dateAsserted
datetime
When the statement was asserted. This is autogenerated on a create request as the timestamp of ingestion.
derivedFrom
array[json]
This will display if the medication was added to the Patient's chart via a MedicationRequest (prescribe or refill command).
Click to view child attributes
reference
string
The reference string of the MedicationRequest in the format of `"MedicationRequest/948b54e2-40b7-4648-bfce-e2373f9802af"`
type
string
Type the reference refers to (e.g. "MedicationRequest")
dosage
array[json]
Details of how medication is/was taken or should be taken.  
The `text` attribute for the Dosage object contains the SIG.
Click to view child attributes
text
string
The SIG of the medication
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/MedicationStatement/{id}
#### MedicationStatement update
Update an MedicationStatement resource.  
The only type of MedicationStatement update interaction that is supported by Canvas is to mark an existing MedicationStatement as **entered-in-error**. No changes to other fields will be processed.
### Attributes
id
string required
The identifier of the MedicationStatement.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string required
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string required
The valueId field is used for the Note extension and will be the note's unique identifier.
status
string required
A code representing the patient or other source's judgment about the state of the medication used that this statement is about.
**Value Options Supported:**
  - entered-in-error
medicationReference
json
What medication was taken.   
Canvas recommends using a medicationReference on create/update to ensure a proper medication lookup is done on validation similar to our commands framework on the Canvas UI. Use the [Medication search endpoint](/api/medication/#search) to help find the correct FDB ID.   
A create/update requires either a medicationReference or medicationCodeableConcept when making a request
Click to view child attributes
reference
string required
The reference string of the medication in the format of `"Medication/fdb-449732"`
display
string required
The display name of the medication
medicationCodeableConcept
json
What medication was taken.   
Canvas recommends using a medicationReference on create/update; however on a Read/Search the medicationCodeableConcept will be returned to allow visibility into all the coding associated with the medication (e.g RxNorm, FDB)   
A create/update requires either a medicationReference or medicationCodeableConcept when making a request.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The url of the medication coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string required
The code value of the medication coding
display
string required
The display name of the medication
subject
json required
Who is/was taking the medication.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`
type
string
Type the reference refers to (e.g. "Patient")
context
json
Encounter / Episode associated with MedicationStatement.  
Supply an encounter reference to be able to insert the command into a specific note on the patient's timeline. If no encounter or note via the extension is specified, it will insert into a Data Import note where the DOS is the current time of ingestion.   
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string required
The reference string of the encounter in the format of `"Encounter/948b54e2-40b7-4648-bfce-e2373f9802af"`
type
string
Type the reference refers to (e.g. "Encounter")
effectivePeriod
json
The interval when the medication is/was/will be taken.
Click to view child attributes
start
datetime
The datetime string represented the start time of the medication in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.
end
datetime
The datetime string represented the end time of the medication in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.
dosage
array[json]
Details of how medication is/was taken or should be taken.  
The `text` attribute for the Dosage object contains the SIG.
Click to view child attributes
text
string
The SIG of the medication
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/MedicationStatement
#### MedicationStatement search
Search for MedicationStatement resources.  
Search bundle entries will always contain values for `medicationCodeableConcept` regardless of what was used to create the MedicationStatement.
### Query Parameters
****
_id
string
The identifier of the MedicationStatement.
patient
string
The patient reference associated to the Medication Statement in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
id
string
The identifier of the MedicationStatement.
extension
array[json]
Canvas supports a note identifier extension on this resource. The note identifier can be used with the [Canvas Note API](/api/note).
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier.
status
string
A code representing the patient or other source's judgment about the state of the medication used that this statement is about.
**Value Options Supported:**
  - active
  - entered-in-error
  - stopped
  - intended (Medications where the effectivePeriod.start date is in the future)
  - unknown (Returned when the source state cannot be mapped to one of the other values.)
medicationCodeableConcept
json
What medication was taken.   
Canvas recommends using a medicationReference on create/update; however on a Read/Search the medicationCodeableConcept will be returned to allow visibility into all the coding associated with the medication (e.g RxNorm, FDB)   
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The url of the medication coding.
**Value Options Supported:**
  - http://www.nlm.nih.gov/research/umls/rxnorm
  - http://www.fdbhealth.com/
code
string
The code value of the medication coding
display
string
The display name of the medication
subject
json
Who is/was taking the medication.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`
type
string
Type the reference refers to (e.g. "Patient")
effectivePeriod
json
The interval when the medication is/was/will be taken.
Click to view child attributes
start
datetime
The datetime string represented the start time of the medication in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.
end
datetime
The datetime string represented the end time of the medication in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.
dateAsserted
datetime
When the statement was asserted. This is autogenerated on a create request as the timestamp of ingestion.
derivedFrom
array[json]
This will display if the medication was added to the Patient's chart via a MedicationRequest (prescribe or refill command).
Click to view child attributes
reference
string
The reference string of the MedicationRequest in the format of `"MedicationRequest/948b54e2-40b7-4648-bfce-e2373f9802af"`
type
string
Type the reference refers to (e.g. "MedicationRequest")
dosage
array[json]
Details of how medication is/was taken or should be taken.  
The `text` attribute for the Dosage object contains the SIG.
Click to view child attributes
text
string
The SIG of the medication
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/MedicationStatement' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "MedicationStatement",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5",
                }
            ],
            "status": "active",
            "medicationReference": {
                "reference": "Medication/fdb-259181",
                "display": "Advil 200 mg tablet"
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "context": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "effectivePeriod": {
                "start": "2023-06-15T15:00:00-04:00",
                "end": "2023-06-25T15:00:00-04:00"
            },
            "dosage": [
                {
                    "text": "1-2 tablets once daily at bedtime as needed for restless legs"
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/MedicationStatement"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "MedicationStatement",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5",
                }
            ],
            "status": "active",
            "medicationReference": {
                "reference": "Medication/fdb-259181",
                "display": "Advil 200 mg tablet"
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "context": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "effectivePeriod": {
                "start": "2023-06-15T15:00:00-04:00",
                "end": "2023-06-25T15:00:00-04:00"
            },
            "dosage": [
                {
                    "text": "1-2 tablets once daily at bedtime as needed for restless legs"
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/MedicationStatement/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/MedicationStatement/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "MedicationStatement",
            "id": "e76e44b4-4e68-4f72-b1c3-1de528a3bb2a",
            "status": "active",
            "medicationCodeableConcept": {
                "coding": [
                    {
                        "system": "http://www.fdbhealth.com/",
                        "code": "259181",
                        "display": "Advil 200 mg tablet"
                    },
                    {
                        "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                        "code": "310965",
                        "display": "Advil 200 mg tablet"
                    }
                ]
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "context": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "dateAsserted": "2023-06-15T15:00:00-04:00",
            "effectivePeriod": {
                "start": "2023-06-15T15:00:00-04:00",
                "end": "2023-06-25T15:00:00-04:00"
            },
            "dosage": [
                {
                    "text": "1-2 tablets once daily at bedtime as needed for restless legs"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown MedicationStatement resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/MedicationStatement/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "MedicationStatement",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5",
                }
            ],
            "status": "entered-in-error",
            "medicationReference": {
                "reference": "Medication/fdb-259181",
                "display": "Advil 200 mg tablet"
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "context": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "effectivePeriod": {
                "start": "2023-06-15T15:00:00-04:00",
                "end": "2023-06-25T15:00:00-04:00"
            },
            "dosage": [
                {
                    "text": "1-2 tablets once daily at bedtime as needed for restless legs"
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/MedicationStatement/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "MedicationStatement",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5",
                }
            ],
            "status": "entered-in-error",
            "medicationReference": {
                "reference": "Medication/fdb-259181",
                "display": "Advil 200 mg tablet"
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
            },
            "context": {
                "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
            },
            "effectivePeriod": {
                "start": "2023-06-15T15:00:00-04:00",
                "end": "2023-06-25T15:00:00-04:00"
            },
            "dosage": [
                {
                    "text": "1-2 tablets once daily at bedtime as needed for restless legs"
                }
            ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown MedicationStatement resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/MedicationStatement?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/MedicationStatement?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/MedicationStatement?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/MedicationStatement?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/MedicationStatement?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "MedicationStatement",
                        "id": "e76e44b4-4e68-4f72-b1c3-1de528a3bb2a",
                        "status": "active",
                        "medicationCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://www.fdbhealth.com/",
                                    "code": "259181",
                                    "display": "Advil 200 mg tablet"
                                },
                                {
                                    "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                                    "code": "310965",
                                    "display": "Advil 200 mg tablet"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
                        },
                        "context": {
                            "reference": "Encounter/eae3c8a5-a129-4960-9715-fc26da30eccc"
                        },
                        "effectivePeriod": {
                            "start": "2023-06-15T15:00:00-04:00",
                            "end": "2023-06-25T15:00:00-04:00"
                        },
                        "dosage": [
                            {
                                "text": "1-2 tablets once daily at bedtime as needed for restless legs"
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Note

Source: https://docs.canvasmedical.com/api/note/

> **Warning:** This API will be deprecated in favor of the Canvas SDK's [Note Effects](/sdk/effect-notes/), which create, update, sign, lock, and unlock notes from a plugin. Build new integrations against Note Effects.
This API allows customers to create and update notes. The effect of creating a note is the same as creating a note in the user interface (for example for a note with category "encounter" will create an encounter, a note that is billable will create a claim). Not all note attributes can be modified on update. For example, note type cannot be changed after note creation.
##  Authentication 
The Note API uses the existing OAuth authentication flow from the FHIR API, so you can simply post to the existing auth token endpoint /auth/token/
Read and search requests need the `user/Note.read` scope. Create and update requests need `user/Note.write`.
The `user/Note.read` and `user/Note.write` scopes are available in the existing OAuth authentication flow used by the FHIR API. These scopes will not be in OAuth applications that were created prior to the release of this feature. Therefore to get access, you have two options:
  - Create a new [OAuth application](/api/customer-authentication)
  - Ask Canvas to add the new scopes to an existing OAuth application
The Note API is a staff API. It refuses tokens with a patient context and tokens that act as a user who isn't a staff member, with `401 Unauthorized`. See [Tokens with a patient context](/api/customer-authentication/#tokens-with-a-patient-context).
![description](/assets/images/allowed-scopes.png)
    ```python
    import requests
    url = "https://<your-instance>.canvasmedical.com/auth/token/"
    payload = 'grant_type=client_credentials&client_id=canvas&client_secret=canvas'
    headers = {
      'Content-Type': 'application/x-www-form-urlencoded'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    print(response.text)
    ```
Then use your token in the request headers as you do with the FHIR API:
![description](/assets/images/note-api-token.png)
##  Create 
To create a Note resource, POST to `https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note` using the supported attributes below. Notes will be created with the state "NEW" by default.
###  Attributes 
**`title`** text  
The user-defined title of the Note.
* * *
**`encounterStartTime`** datetime  
The datetime of the encounter. This will display in the datetimeOfService.
* * *
**`patientKey`** text  
The unique key of the Patient for which this Note is written.
* * *
**`providerKey`** text  
The unique key of the Provider staff who is writing the Note.
* * *
**`practiceLocationKey`** text  
The unique key of the PracticeLocation for which this Note is written.
* * *
**`noteTypeName text`**  
Represents the note type in a human-readable format.
* * *
**`noteTypeSystem`** text  
Defines a coding system for the note type, to be used with the paired noteTypeCoding.
* * *
**`noteTypeCoding`** text  
Defines a code for the note type, to be used with the paired noteTypeSystem.
###  Example 
    ```python
    import requests
    import json
    url = "https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note"
    payload = json.dumps({
      "title": "Some Custom Title",
      "noteTypeName": "Office visit",
      "patientKey": "8d84776879de49518a4bc3bb81d96dd4",
      "providerKey": "5eede137ecfe4124b8b773040e33be14",
      "practiceLocationKey": "c67e0c59-d4d2-428c-bc13-b6e85d181ad0",
      "encounterStartTime": "2023-11-28T19:00:00.016852Z"
    })
    headers = {
      'Authorization': 'Bearer HqFtbSnBNX4S65VhRrg8sRxO6XcSFp',
      'Content-Type': 'application/json'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    print(response.text)
    ```
##  Read 
To read a Note resource, request a GET from   
`https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note/{noteKey}`
###  Attributes 
**`noteKey`** string  
The unique key of the Note.
* * *
**`title`** text  
The user-defined title of the Note.
* * *
**`datetimeOfService`** datetime  
The datetime of the service, as defined as encounter start time for encounters, appointment datetime for appointments, or the created datetime for other note types.
* * *
**`titleDisplay`** text  
Represents the computed title of the Note, as displayed in the UI. If a user-defined title is not provided, this defaults to other display logic.
* * *
**`currentState`** text  
The most recent state of the Note.
* * *
**`patientKey`** text  
The unique key of the Patient for which this Note was written.
* * *
**`providerKey`** text  
The unique key of the Provider staff who wrote the Note.
* * *
**`practiceLocationKey`** text  
The unique key of the PracticeLocation for which this Note was written.
* * *
**`noteTypeName text`**  
Represents the note type in a human-readable format.
* * *
**`noteTypeSystem`** text  
Defines a coding system for the note type, to be used with the paired noteTypeCoding.
* * *
**`noteTypeCoding`** text  
Defines a code for the note type, to be used with the paired noteTypeSystem.
###  Example 
    ```python
    import requests
    url = "https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note/4a6064e9-293c-4541-b1cc-515f81435e74"
    payload = ""
    headers = {
      'Authorization': 'Bearer QdPhY9QLIs4zlawv5UG42JDASGqX0l'
    }
    response = requests.request("GET", url, headers=headers, data=payload)
    print(response.text)
    ```
##  Update 
To update an existing Note resource, `PATCH` to   
`https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note/{noteKey}`   
using any of the following allowed attributes.
###  Attributes 
**`title`** text  
The user-defined title of the Note.
* * *
**`providerKey`** text  
The unique key of the Provider staff who is writing the Note.
* * *
**`practiceLocationKey`** text  
The unique key of the PracticeLocation for which this Note is written.
* * *
**`stateChange`** text   
The new note state to be set. Allowed transitions in v1 include:
Locking an unlocked note (excluding DATA notes). Locking a note will result in the Note PDF being generated along with it associated FHIR DocumentReference record.   
"ULK" → "LKD", "NEW" → "LKD", "CVD" → "LKD"  
Unlocking a locked note (excluding DATA notes)  
"LKD" → "ULK"  
Marking an appointment as a no show   
"BKD" → "NSW" & "RVT" → "NSW"  
Checking in an appointment  
"BKD" → "CVD", "NSW" → "CVD", "RVT" → "CVD"
###  Example 
    ```python
    import requests
    import json
    url = "https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note/4a6064e9-293c-4541-b1cc-515f81435e74"
    payload = json.dumps({
      "stateChange": "LKD",
      "providerKey": "4150cd20de8a470aa570a852859ac87e",
      "practiceLocationKey": "c67e0c59-d4d2-428c-bc13-b6e85d181ad0",
      "title": "New Custom Title"
    })
    headers = {
      'Authorization': 'Bearer QdPhY9QLIs4zlawv5UG42JDASGqX0l',
      'Content-Type': 'application/json'
    }
    response = requests.request("PATCH", url, headers=headers, data=payload)
    print(response.text)
    ```
##  Search 
To search for Note resources, request a `GET` from   
`https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note`   
and append your search criteria as URL parameters.
###  Query Params 
**patient_key** text filters to this patient's notes only
**provider_key** text filters to this provider's notes only
**note_type_name** text filters to this type of note (human-readable)
**note_type_system** and **note_type_coding** text filters to this type of note with system/code pair
**datetime_of_service** datetime filters the service datetime with the following options:
  - = (exact)
  - lte (less than or equal to)
  - gte (greater than or equal to)
  - lt (less than)
  - gt (greater than)
`&datetime_of_service__gte=2023-12-06T19:10:56.115532Z`
###  Pagination 
To paginate your requests, simply add a limit query parameter, e.g. `GET` from `https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note?limit=10`. You can also page through the results with the offset parameter, e.g. `https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note?limit=10&offset=10`. The response will include a record count, as well as **next** , and **previous** URLs for convenience, and the note data will be contained in the **results** value.
###  Ordering 
To order your results, simply add an ordering query parameter, e.g. `GET` from `https://<your-instance>.canvasmedical.com/core/api/notes/v1/Note?ordering=datetime_of_service`. To reverse the sort order, prepend the field with a hyphen, e.g. `?ordering=-datetime_of_service`. Available ordering fields include:
  - created (the datetime the note was created)
  - modified (the datetime the note was last updated)
  - datetime_of_service (the datetime of the actual service associated with the note)
###  Example 
    ```python
    import requests
    url = "https://<your_instance>.canvasmedical.com/core/api/notes/v1/Note?patient_key=8d84776879de49518a4bc3bb81d96dd4&note_type_name=Office%20visit"
    payload = ""
    headers = {
      'Authorization': 'Bearer QdPhY9QLIs4zlawv5UG42JDASGqX0l'
    }
    response = requests.request("GET", url, headers=headers, data=payload)
    print(response.text)
    ```

---

# Observation

Source: https://docs.canvasmedical.com/api/observation/

### 
Measurements and simple assertions made about a patient, device or other subject.  
Canvas supports the following US Core Profiles for Observations:  
  - [US Core Observation Clinical Result Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-clinical-result.html)
  - [US Core Laboratory Result Observation Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-lab.html)
  - [US Core Observation Occupation Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-occupation.html)
  - [US Core Observation Pregnancy Intent Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-pregnancyintent.html)
  - [US Core Observation Pregnancy Status Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-pregnancystatus.html)
  - [US Core Observation Screening Assessment Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-screening-assessment.html)
  - [US Core Observation Sexual Orientation Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-sexual-orientation.html)
  - [US Core Simple Observation Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-simple-observation.html)
  - [US Core Smoking Status Observation Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-smokingstatus.html)
  - [US Core Vital Signs Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-vital-signs.html)
  - [US Core Pediatric Head Occipital-frontal Circumference Percentile Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-head-occipital-frontal-circumference-percentile.html)
  - [US Core Pediatric BMI for Age Observation Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-pediatric-bmi-for-age.html)
  - [US Core Pediatric Weight for Height Observation Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-pediatric-weight-for-height.html)
  - [US Core Blood Pressure Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-blood-pressure.html)
  - [US Core BMI Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-bmi.html)
  - [US Core Body Height Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-body-height.html)
  - [US Core Body Temperature Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-body-temperature.html)
  - [US Core Body Weight Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-body-weight.html)
  - [US Core Head Circumference Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-head-circumference.html)
  - [US Core Heart Rate Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-heart-rate.html)
  - [US Core Pulse Oximetry Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-pulse-oximetry.html)
  - [US Core Respiratory Rate Profile](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-respiratory-rate.html)
The following USCDI data elements are retrievable from this endpoint:  
  - Laboratory Tests
  - Laboratory Values/Results
  - Smoking Status
Here are some Canvas specific workflows where observations will be created:
  1. Documenting Vitals via our [Vital Command](https://canvas-medical.help.usepylon.com/articles/9426091672-command-vitals) (category coding will be `vital-signs`)  
  2. Submitting a Questionnaire, Review Of System (ROS), Structured Assessment (SA), or a Physical Exam will result in an observation for each question answered if the question's code system is LOINC or SNOMED (category coding will be `social-history`).   
  3. There is a specific Physical Exam to capture Pediatric Vitals. Upon submission of the Exam, associated observations for Body Length, Head Circumference, and Head Occipital-Frontal Circumference Percentile (category coding will be `vital-signs`) will be created along with the observations for the answers of the exam (category coding will be `social-history`). Please contact Customer Support for help loading this Exam into your instance if you want to utilize it.   
  4. Once weight and either height or pediatric body length is entered on a patients chart, the vital observations of BMI for Age Percentile (for patients 2 years or older) and Weight-for-Length Percentile will be calculated (category coding will be `vital-signs`).
  5. Submitting a Questionnaire that has custom scoring defined will result in an observation containing the scored value (category coding will be `survey`).   
  6. When a lab report is created in Canvas through [DI](https://canvas-medical.help.usepylon.com/articles/1652834476-labs-lab-reports), API, integration with HG, or [POC Lab Test Command](https://canvas-medical.help.usepylon.com/articles/7060961677-point-of-care-poc-tests), there will be resulting Observations made (category coding will be `laboratory`). Canvas lab orders are placed with a lab-specific identifier or a CPT code rather than a LOINC code, so treat the lab vendor as the source of truth for a result's LOINC code. When you create lab results through the API, prefer the vendor's specific LOINC code over a generic laboratory result code, because what is ordered can differ slightly from what the lab performs.
**Related guides:**
  - [Submit a Full Vital Panel through Canvas FHIR API](/guides/submit-vitals-via-fhir/)
### Endpoints
post/Observation get/Observation/{id} get/Observation
post
/Observation
#### Observation create
Although the observation endpoint houses many different Canvas models, currently, **only vital signs and panels can be created through this endpoint**.  
**Vital signs and Vital Sign Panels**  
See this [helpful guide](/guides/submit-vitals-via-fhir/) to walk you through creating a vital panel via FHIR.  
  - Vital sign panels and vital signs are both observations.  
    - Vital sign panels are the parent that "contain" the vital sign observations. The `hasMembers` attribute contains references to the child observations  
    - Each vital sign that is part of the panel links back to the parent Observation via the `derivedFrom` attribute.  
    - If a `derivedFrom` value is not included for a vital sign observation, then a new vital sign panel observation is created and will autofill the `derivedFrom` attribute field.  
  - Vital signs and their parent panel feed into our [Vitals command](https://canvas-medical.help.usepylon.com/articles/9426091672-command-vitals).  
**Note types**  
Most our FHIR endpoints insert commands into a Data Import Note type on the patient's timeline. With the release of [configurable note types](https://help.canvasmedical.com/articles/6785045644-appointment-event-note-types), if you create a new Note Type in Settings with **system = Canvas** and **code = VitalsImport** , then the Observation Create endpoint will always import into that note type instead.  
**Supported vital sign codes used in create**
vital sign| LOINC code| default unit| additional accepted units  
---|---|---|---  
vital sign panel| 85353-1|  |   
blood pressure| 85354-9| mmHg|   
weight| 29463-7| oz| lb, kg  
height| 8302-2| in| cm  
pulse rate| 8867-4| bpm|   
body temperature| 8310-5| °F|   
oxygen saturation (arterial)*| 2708-6| %|   
oxygen saturation*| 59408-5| %|   
respiration rate| 9279-1| bpm|   
waist circumference| 56086-2| cm| in  
note| 80339-5|  |   
pulse rhythm| 8884-9|  |   
*If an oxygen saturation vital sign is created, an oxygen saturation (arterial) vital sign code is also automatically generated.  
A vital sign code that is not listed in the table above is rejected with a 405 and the message `Sign is not supported by Canvas`. In particular, **supplemental oxygen (88658-0) cannot be created through this endpoint** — it can only be captured through the Vitals command in Canvas. Supplemental oxygen observations are still returned by read and search, where the value appears as a `valueCodeableConcept`.  
**Additional examples**
  - [Creating a vital panel](https://github.com/canvas-medical/canvas-fhir-example-requests/blob/main/Observation/Create%20Observation%20-%20panel.bru)
  - [Creating a vital sign with components (should only be used for blood pressure)](https://github.com/canvas-medical/canvas-fhir-example-requests/blob/main/Observation/Create%20Observation%20-%20w-%20components.bru)
  - [Creating a vital sign without components](https://github.com/canvas-medical/canvas-fhir-example-requests/blob/main/Observation/Create%20Observation%20-%20w-o%20components.bru)
### Attributes
resourceType
string
The FHIR Resource name.
status
enum [ final | unknown | entered-in-error ] required
The status of the result value. Observations created via the FHIR API can only be `final`.
code
json required
Describes what was observed.  
For create interactions, only vital sign LOINC codes are supported.
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
code
string required
The code of the observation.
**Value Options Supported:**
  - 85353-1 (panel)
  - 85354-9 (blood pressure)
  - 29463-7 (weight)
  - 8302-2 (height)
  - 8867-4 (pulse rate)
  - 8310-5 (body temperature)
  - 2708-6 (oxygen saturation arterial)
  - 59408-5 (oxygen saturation)
  - 9279-1 (respiration rate)
  - 56086-2 (waist circumference)
  - 80339-5 (note)
  - 8884-9 (pulse rhythm)
display
string required
The display name of the coding.
subject
json required
Canvas Patient reference the Observation is for.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
effectiveDateTime
datetime
Clinically relevant time/time-period for observation.  
For an individual vital sign, if the effectiveDateTime differs from the panel time, it will be reflected in a read/search; however, you will not see the individual date in the UI, only the panel's datetime.  
If omitted from create, Canvas will save a default value of the current datetime.
performer
array[json]
Who is responsible for the observation
Click to view child attributes
reference
string
The reference string of the performer in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"` or `"Patient/a39cafb9d1b445be95a2e2548e12a787"`. Performer can be a Practitioner or a Patient.
type
string
Type the reference refers to (e.g. "Practitioner" or "Patient").
valueQuantity
json
Actual result.  
This is used for vital observation that correspond with a numeric value. If this field is not provided or specifically the value attribute in the json is omitted, Canvas will interpret that as an empty value. A Read/Search of this observation will display the `dataAbsentReason` attribute.   
Currently supported numeric values are  
\- height  
\- weight  
\- waist circumference  
\- body temperature  
\- pulse rate  
\- oxygen saturation  
\- respiration rate A `valueQuantity` can also be used to represent a diagnostic score. Scores will have a unit of 'score'.
Click to view child attributes
value
number required
Numerical value (with implicit precision).
unit
string
Unit representation. If omitted, it will default to the values in the table defined above. For the submitted `code`, only units from the table above can be sent. Sending a different unit will result in a 422 error.
valueString
string
Actual result.  
This is used for vital observation that correspond with a string value. If this field is not provided or specifically the value attribute in the json is omitted, Canvas will interpret that as an empty value. A Read/Search of this observation will display the `dataAbsentReason` attribute.   
Currently supported string values are   
\- **note** \- this is a free text comment field in the Canvas Vital Command   
\- **pulse rhythm** \- This is an enum in the Canvas Vital command. Values supported are **Regular** , **Irregularly Irregular** , **Regulary Irregular**. If one of these values is not provided, a 422 error will occur.   
\- **blood pressure** \- This is a string reprentation of the systolic and diastolic combined in the format `"100/80"`. If this valueString is not given, it will not appear correctly in the Canvas Vital Command.
hasMember
array[json]
Related Observation reference(s) that belongs to the Observation group/panel.  
Only need to supply this attribute in a Vital Sign Panel to specify specific child observations that are a part of the panel. In Canvas these will form the Vitals Command. This observation IDs can be found using the [Observation Search](/api/observation/#search).   
If a new vital sign panel is created and links pre-existing vital signs via the `hasMember` attribute, those linked observations will update their `derivedFrom` attribute to be set to the newly created vital sign panel.
Click to view child attributes
reference
string required
The reference string of the child observation in the format of `"Observation/920807d3-034b-4423-a65b-980068cb4bd1"`.
type
string
Type the reference refers to (e.g. "Observation").
display
string
The coding display of the reference.
derivedFrom
array[json]
Related Observation resource that the Observation is made from.  
This attribute should only be used to link a vital sign to an existing "parent" vital sign panel. It ingests a reference to the vital sign panel's observation. This observation ID can be found using the [Observation Search](/api/observation/#search).  
If this field is omitted on a vital sign observation, a vital sign panel will automatically be created.   
It is important to note that each vital sign panel can only contain a single vital sign of each type. Adding a duplicate of a vital sign will result in a 422 error: "Vital sign reading already exists for the given reading".
Click to view child attributes
reference
string required
The reference string of the child observation in the format of `"Observation/920807d3-034b-4423-a65b-980068cb4bd1"` or `"QuestionnaireResponse/0e34b12d-0494-4ade-9a51-aa12225dd959"`.
type
string
Type the reference refers to (e.g. "Observation", "QuestionnaireResponse").
component
array[json]
Component results  
This attribute is only used for blood pressure, as it has two components (systolic and diastolic).   
  - These components are added to a vital sign observation by including their `code` and `valueQuantity`.
  - The components are what will be stored in the database; however, they will not display on the UI. The `Observation.valueString` will be the attribute that displays on the UI.
  - The `valueQuantity` for the systolic component should match the first number in the blood pressure vital sign `valueQuantity`, where the `valueQuantity` of the diastole component should match the second number.
Click to view child attributes
code
json required
Type of component observation (code / type).
Click to view child attributes
coding
array[json] required
Code defined by a terminology system.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
code
string required
The code of the observation.
**Value Options Supported:**
  - 8480-6 (systolic)
  - 8462-4 (diastolic)
display
string required
The display name of the coding.
**Value Options Supported:**
  - Systolic blood pressure
  - Diastolic blood pressure
valueQuantity
json
Actual component result. Since this endpoint only supports blood pressure systolic/diastolic components, the units are already defaulted to `mmHg`.
Click to view child attributes
value
number required
Numerical value (with implicit precision).
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Observation/{id}
#### Observation read
### Path Parameters
id required
string
The unique identifier for the Observation   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The Canvas identifier of the observation
status
enum [ final | unknown | entered-in-error ]
The status of the result value.
category
array[json]
Classifies the general type of observation being made.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/observation-category
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-category
code
string
The code of the observation.
**Value Options Supported:**
  - vital-signs
  - social-history
  - imaging
  - laboratory
  - procedure
  - survey
  - exam
  - therapy
  - activity
  - sdoh
  - functional-status
  - cognitive-status
  - disability-status
display
string
The display name of the coding.
**Value Options Supported:**
  - Vital Signs
  - Social History
  - Imaging
  - Laboratory
  - Procedure
  - Survey
  - Exam
  - Therapy
  - Activity
  - SDOH
  - Functional Status
  - Cognitive Status
  - Disability Status
code
json
Describes what was observed.
Click to view child attributes
extension
For observations that do not have an associated code (e.g Laboratory Observations), an extension will be displayed to denote an absent of a coding.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://hl7.org/fhir/StructureDefinition/data-absent-reason
valueCode
code
The reason the Observation.coding attribute is missing.
**Value Options Supported:**
  - unsupported
  - unknown
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
code
string
The code of the observation.
**Value Options Supported:**
  - Any LOINC codes from Vital Panel or Vital Signs captured in the Observation Create / Vital Command
  - 88658-0 (LOINC code for Supplemental Oxygen). This vital sign is read-only over FHIR: it can only be captured through the Vitals command, not created through this endpoint. Its value is returned as a `valueCodeableConcept` holding an answer code from LOINC answer list LL4908-1, rather than as a `valueQuantity` or `valueString` like the other vital signs.
  - Any LOINC or SNOMED code from questions filled out through a Questionnaire, Structured Assessment, Physical Exam, Review of Systems
  - Any code from a Questionnaire Scoring Result
  - Pediatric Vital observations: 8306-3 (Body Length), 8289-1 (Head Occipital-Frontal Circumference Percentile), and 8287-5 (Head Circumference)
  - 59576-9 (LOINC code for BMI for Age Percentile)
  - 77606-2 (LOINC code for Weight-for-Length Percentile)
  - Any LOINC codes from Lab Report Values captured
display
string
The display name of the coding.
subject
json
Canvas Patient reference the Observation is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
effectiveDateTime
datetime
Clinically relevant time/time-period for observation.
effectivePeriod
json
Clinically relevant time/time-period for observation.  
The US Core Occupation profile presents the `effective` attribute as a time period with start and end datetimes.  
This attribute can only be read via FHIR, but not written.
Click to view child attributes
start
datetime
Starting time with inclusive boundary
end
datetime
End time with inclusive boundary, if not ongoing
performer
array[json]
Who is responsible for the observation
Click to view child attributes
reference
string
The reference string of the performer in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"` or `"Patient/a39cafb9d1b445be95a2e2548e12a787"`. Performer can be a Practitioner or a Patient.
type
string
Type the reference refers to (e.g. "Practitioner" or "Patient").
issued
datetime
Date/Time this version was made available. It is the timestamp in Canvas when the observation was ingested.
valueQuantity
json
Actual result.   
Used for observations with numeric values like vitals, lab report values, any questionnaire result scoring programed in Canvas.
Click to view child attributes
value
number
Numerical value (with implicit precision).
unit
string
Unit representation.
system
string
System that defines coded unit form.
**Value Options Supported:**
  - http://unitsofmeasure.org
code
string
Coded form of the unit may be shown.
**Value Options Supported:**
  - [lb_av]
  - cm
  - [in_i]
  - [degF]
  - mm[Hg]
  - %
  - /min
  - kg/m2
  - L/min
valueString
string
Actual result.   
Used for observations containing text values like vitals that are strings (e.g Blood Pressure, notes, and pulse rhythm) and free text lab result values.
valueCodeableConcept
json
Actual result.  
Used for observations with a selected coding like Questionnaire Responses showing the answer to a specific question. This comes from Questionnaires, Structured Assessment, Physical Exam, and Review of Systems in Canvas.  
Also used for the **supplemental oxygen** vital sign (88658-0), whose value is an answer code from LOINC answer list LL4908-1 (`LA28684-1` Continuously depending on high oxygen flow, `LA28685-8` Continuously depending on low oxygen flow, `LA28686-6` Intermittent oxygen consumption). Supplemental oxygen is read-only over FHIR — it is not in the list of vital sign codes supported in create.
Click to view child attributes
coding
array[json]
Code defined by a terminology system. Codings are used when the Observation comes from a QuestionnaireResponse.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the observation.
display
string
The display name of the coding.
dataAbsentReason
json
Why the result is missing (if there is no `value[x]` section)
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/data-absent-reason
code
string
The code of the observation.
**Value Options Supported:**
  - not-performed
display
string
The display name of the coding.
**Value Options Supported:**
  - Not Performed
hasMember
array[json]
Related Observation reference(s) that belongs to the Observation group/panel.   
In Canvas, all the vital signs taken in a Vitals Command will be listed in this `hasMember` attribute.
Click to view child attributes
reference
string
The reference string of the child observation in the format of `"Observation/920807d3-034b-4423-a65b-980068cb4bd1"`.
type
string
Type the reference refers to (e.g. "Observation").
display
string
The coding display of the reference.
derivedFrom
array[json]
Related resource that the Observation is made from.  
For vital signs, the derivedFrom reference would be the observation that corresponds to the "parent" vital sign panel this observation is part of.   
For observations originating from a custom scoring of a Questionnaire or from answers filled out in Questionnaires, ROS, SA, or Physical Exams the `derivedFrom` attribute will be a reference to the associated QuestionnaireResponse record.
Click to view child attributes
reference
string
The reference string of the child observation in the format of `"Observation/920807d3-034b-4423-a65b-980068cb4bd1"` or `"QuestionnaireResponse/0e34b12d-0494-4ade-9a51-aa12225dd959"`.
type
string
Type the reference refers to (e.g. "Observation", "QuestionnaireResponse").
specimen
json
Reference to the Specimen resource that was used for this observation.  
This field is populated for laboratory observations that have an associated specimen from a lab order. The specimen reference includes the specimen's externally exposable ID.
Click to view child attributes
reference
string
The reference string of the specimen in the format of `"Specimen/0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d"`.
type
string
Type the reference refers to (e.g. "Specimen").
component
array[json]
Component results.   
Currently only used for blood pressure observations to display the systolic and diastolic components.
Click to view child attributes
code
json
Type of component observation (code / type).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
code
string
The code of the observation.
**Value Options Supported:**
  - 8480-6 (systolic)
  - 8462-4 (diastolic)
display
string
The display name of the coding.
**Value Options Supported:**
  - Systolic blood pressure
  - Diastolic blood pressure
valueCodeableConcept
json
Actual component result.  
Used when a component is represented by a value that is a reference to one or more terminologies or ontologies.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the observation.
display
string
The display name of the coding.
valueQuantity
json
Actual component result.
Click to view child attributes
value
number
Numerical value (with implicit precision).
unit
string
Unit representation.
**Value Options Supported:**
  - mmHg
system
string
System that defines coded unit form.
**Value Options Supported:**
  - http://unitsofmeasure.org
code
string
Coded form of the unit
**Value Options Supported:**
  - mm[Hg]
valueString
string
Actual component result, when the value is non-numeric and not coded.
dataAbsentReason
json
Why the result is missing (if there is no `Component[x].value[y]` section)
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/data-absent-reason
code
string
The code of the observation.
**Value Options Supported:**
  - not-performed
display
string
The display name of the coding.
**Value Options Supported:**
  - Not Performed
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Observation
#### Observation search
### Query Parameters
****
_id
string
The Canvas resource id for the Observation
category
string
Classification of the type of observation. Filters by the code and/or system under `category.coding` attribute. You can search by just the code value or you can search by the system and code in the format `system|code` (e.g `http://terminology.hl7.org/CodeSystem/observation-category|vital-signs`).
code
string
The code of the observation type. Filters by the code and/or system under `code.coding` attribute. You can search by just the code value or you can search by the system and code in the format `system|code` (e.g `http://loinc.org|85353-1`).
date
date
Filter by the `effectiveDateTime` attribute. See [Date Filtering](/api/date-filtering) for more information.
derived-from
string
A reference to a related measurement the observation is made from.   
Use this search parameter to find all observations of a specific vital panel or questionnaire response observations from the same interview.
**Search Values Supported:**
  - QuestionnaireResponse/{id}
  - Observation/{id}
patient
string
The patient reference associated to the observation in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The Canvas identifier of the observation
status
enum [ final | unknown | entered-in-error ]
The status of the result value.
category
array[json]
Classifies the general type of observation being made.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/observation-category
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-category
code
string
The code of the observation.
**Value Options Supported:**
  - vital-signs
  - social-history
  - imaging
  - laboratory
  - procedure
  - survey
  - exam
  - therapy
  - activity
  - sdoh
  - functional-status
  - cognitive-status
  - disability-status
display
string
The display name of the coding.
**Value Options Supported:**
  - Vital Signs
  - Social History
  - Imaging
  - Laboratory
  - Procedure
  - Survey
  - Exam
  - Therapy
  - Activity
  - SDOH
  - Functional Status
  - Cognitive Status
  - Disability Status
code
json
Describes what was observed.
Click to view child attributes
extension
For observations that do not have an associated code (e.g Laboratory Observations), an extension will be displayed to denote an absent of a coding.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://hl7.org/fhir/StructureDefinition/data-absent-reason
valueCode
code
The reason the Observation.coding attribute is missing.
**Value Options Supported:**
  - unsupported
  - unknown
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
code
string
The code of the observation.
**Value Options Supported:**
  - Any LOINC codes from Vital Panel or Vital Signs captured in the Observation Create / Vital Command
  - 88658-0 (LOINC code for Supplemental Oxygen). This vital sign is read-only over FHIR: it can only be captured through the Vitals command, not created through this endpoint. Its value is returned as a `valueCodeableConcept` holding an answer code from LOINC answer list LL4908-1, rather than as a `valueQuantity` or `valueString` like the other vital signs.
  - Any LOINC or SNOMED code from questions filled out through a Questionnaire, Structured Assessment, Physical Exam, Review of Systems
  - Any code from a Questionnaire Scoring Result
  - Pediatric Vital observations: 8306-3 (Body Length), 8289-1 (Head Occipital-Frontal Circumference Percentile), and 8287-5 (Head Circumference)
  - 59576-9 (LOINC code for BMI for Age Percentile)
  - 77606-2 (LOINC code for Weight-for-Length Percentile)
  - Any LOINC codes from Lab Report Values captured
display
string
The display name of the coding.
subject
json
Canvas Patient reference the Observation is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
effectiveDateTime
datetime
Clinically relevant time/time-period for observation.
effectivePeriod
json
Clinically relevant time/time-period for observation.  
The US Core Occupation profile presents the `effective` attribute as a time period with start and end datetimes.  
This attribute can only be read via FHIR, but not written.
Click to view child attributes
start
datetime
Starting time with inclusive boundary
end
datetime
End time with inclusive boundary, if not ongoing
performer
array[json]
Who is responsible for the observation
Click to view child attributes
reference
string
The reference string of the performer in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"` or `"Patient/a39cafb9d1b445be95a2e2548e12a787"`. Performer can be a Practitioner or a Patient.
type
string
Type the reference refers to (e.g. "Practitioner" or "Patient").
issued
datetime
Date/Time this version was made available. It is the timestamp in Canvas when the observation was ingested.
valueQuantity
json
Actual result.   
Used for observations with numeric values like vitals, lab report values, any questionnaire result scoring programed in Canvas.
Click to view child attributes
value
number
Numerical value (with implicit precision).
unit
string
Unit representation.
system
string
System that defines coded unit form.
**Value Options Supported:**
  - http://unitsofmeasure.org
code
string
Coded form of the unit may be shown.
**Value Options Supported:**
  - [lb_av]
  - cm
  - [in_i]
  - [degF]
  - mm[Hg]
  - %
  - /min
  - kg/m2
  - L/min
valueString
string
Actual result.   
Used for observations containing text values like vitals that are strings (e.g Blood Pressure, notes, and pulse rhythm) and free text lab result values.
valueCodeableConcept
json
Actual result.  
Used for observations with a selected coding like Questionnaire Responses showing the answer to a specific question. This comes from Questionnaires, Structured Assessment, Physical Exam, and Review of Systems in Canvas.  
Also used for the **supplemental oxygen** vital sign (88658-0), whose value is an answer code from LOINC answer list LL4908-1 (`LA28684-1` Continuously depending on high oxygen flow, `LA28685-8` Continuously depending on low oxygen flow, `LA28686-6` Intermittent oxygen consumption). Supplemental oxygen is read-only over FHIR — it is not in the list of vital sign codes supported in create.
Click to view child attributes
coding
array[json]
Code defined by a terminology system. Codings are used when the Observation comes from a QuestionnaireResponse.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the observation.
display
string
The display name of the coding.
dataAbsentReason
json
Why the result is missing (if there is no `value[x]` section)
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/data-absent-reason
code
string
The code of the observation.
**Value Options Supported:**
  - not-performed
display
string
The display name of the coding.
**Value Options Supported:**
  - Not Performed
hasMember
array[json]
Related Observation reference(s) that belongs to the Observation group/panel.   
In Canvas, all the vital signs taken in a Vitals Command will be listed in this `hasMember` attribute.
Click to view child attributes
reference
string
The reference string of the child observation in the format of `"Observation/920807d3-034b-4423-a65b-980068cb4bd1"`.
type
string
Type the reference refers to (e.g. "Observation").
display
string
The coding display of the reference.
derivedFrom
array[json]
Related resource that the Observation is made from.  
For vital signs, the derivedFrom reference would be the observation that corresponds to the "parent" vital sign panel this observation is part of.   
For observations originating from a custom scoring of a Questionnaire or from answers filled out in Questionnaires, ROS, SA, or Physical Exams the `derivedFrom` attribute will be a reference to the associated QuestionnaireResponse record.
Click to view child attributes
reference
string
The reference string of the child observation in the format of `"Observation/920807d3-034b-4423-a65b-980068cb4bd1"` or `"QuestionnaireResponse/0e34b12d-0494-4ade-9a51-aa12225dd959"`.
type
string
Type the reference refers to (e.g. "Observation", "QuestionnaireResponse").
specimen
json
Reference to the Specimen resource that was used for this observation.  
This field is populated for laboratory observations that have an associated specimen from a lab order. The specimen reference includes the specimen's externally exposable ID.
Click to view child attributes
reference
string
The reference string of the specimen in the format of `"Specimen/0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d"`.
type
string
Type the reference refers to (e.g. "Specimen").
component
array[json]
Component results.   
Currently only used for blood pressure observations to display the systolic and diastolic components.
Click to view child attributes
code
json
Type of component observation (code / type).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
code
string
The code of the observation.
**Value Options Supported:**
  - 8480-6 (systolic)
  - 8462-4 (diastolic)
display
string
The display name of the coding.
**Value Options Supported:**
  - Systolic blood pressure
  - Diastolic blood pressure
valueCodeableConcept
json
Actual component result.  
Used when a component is represented by a value that is a reference to one or more terminologies or ontologies.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
code
string
The code of the observation.
display
string
The display name of the coding.
valueQuantity
json
Actual component result.
Click to view child attributes
value
number
Numerical value (with implicit precision).
unit
string
Unit representation.
**Value Options Supported:**
  - mmHg
system
string
System that defines coded unit form.
**Value Options Supported:**
  - http://unitsofmeasure.org
code
string
Coded form of the unit
**Value Options Supported:**
  - mm[Hg]
valueString
string
Actual component result, when the value is non-numeric and not coded.
dataAbsentReason
json
Why the result is missing (if there is no `Component[x].value[y]` section)
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/data-absent-reason
code
string
The code of the observation.
**Value Options Supported:**
  - not-performed
display
string
The display name of the coding.
**Value Options Supported:**
  - Not Performed
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Observation' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
          "resourceType": "Observation",
          "status": "final",
          "code": {
            "coding": [
              {
                "system": "http://loinc.org",
                "code": "29463-7",
                "display": "Weight"
              }
            ]
          },
          "subject": {
            "reference": "Patient/ee8672f3497e4a83937b9e71d0a704a5"
          },
          "effectiveDateTime": "2022-07-29T08:50:24.883809+00:00",
          "valueQuantity": {
            "value": "50",
            "unit": "kg"
          },
          "derivedFrom": [
            {
              "reference": "Observation/6173fbe8-110e-4a4a-9647-e949f7b1c35e",
              "type": "Observation"
            }
          ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Observation"
        payload = {
            "resourceType": "Observation",
            "status": "final",
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "29463-7",
                  "display": "Weight"
                }
              ]
            },
            "subject": { "reference": "Patient/ee8672f3497e4a83937b9e71d0a704a5" },
            "effectiveDateTime": "2022-07-29T08:50:24.883809+00:00",
            "valueQuantity": { "value": "50", "unit": "lb" },
            "derivedFrom": [{ "reference": "Observation/6173fbe8-110e-4a4a-9647-e949f7b1c35e" }]
        }
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Observation/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Observation/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Observation",
            "id": "43b74793-5de6-435a-871d-8ae2232f3aa0",
            "status": "final",
            "category": [
                {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                            "code": "vital-signs",
                            "display": "Vital Signs"
                        }
                    ]
                }
            ],
            "code": {
                "coding": [
                    {
                        "system": "http://loinc.org",
                        "code": "85353-1"
                    }
                ]
            },
            "subject": {
                "reference": "Patient/a1197fa9e65b4a5195af15e0234f61c2",
                "type": "Patient"
            },
            "effectiveDateTime": "2022-06-28T20:18:54.141759+00:00",
            "performer":
            [
                {
                    "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                    "type": "Practitioner"
                }
            ],
            "issued": "2022-06-28T20:43:10.465819+00:00",
            "dataAbsentReason": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                        "code": "not-performed",
                        "display": "Not Performed"
                    }
                ]
            },
            "hasMember": [
                {
                    "reference": "Observation/dd7f25f3-0fa6-4f15-9b8c-c61c24f139d8",
                    "type": "Observation",
                    "display": "Weight"
                },
                {
                    "reference": "Observation/3b96ab8b-aef6-4cbe-8ec5-b88c8e120e19",
                    "type": "Observation",
                    "display": "Body Temperature"
                },
                {
                    "reference": "Observation/201d4404-60c0-4f07-88c1-534456271a74",
                    "type": "Observation",
                    "display": "Blood Pressure"
                },
                {
                    "reference": "Observation/841187ae-0c35-4db7-8852-b5370e4a5c51",
                    "type": "Observation",
                    "display": "Pulse Rhythm"
                },
                {
                    "reference": "Observation/60e563bd-7848-487d-8852-c0db383dc115",
                    "type": "Observation",
                    "display": "Oxygen Saturation Arterial"
                },
                {
                    "reference": "Observation/cb8bca44-d0de-48b0-8786-6887a4b649ec",
                    "type": "Observation",
                    "display": "Height"
                },
                {
                    "reference": "Observation/b96e8bd4-1db9-46db-b292-e9a474bdca44",
                    "type": "Observation",
                    "display": "Waist Circumference"
                },
                {
                    "reference": "Observation/1e8b6774-82c3-4f0b-9b28-fca5fc17e8c9",
                    "type": "Observation",
                    "display": "Pulse"
                },
                {
                    "reference": "Observation/8642e444-53a6-4db8-a15f-17fdb2e01247",
                    "type": "Observation",
                    "display": "Respiration Rate"
                },
                {
                    "reference": "Observation/d0996ff1-643a-4711-88f8-2e303d208663",
                    "type": "Observation",
                    "display": "Note"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Observation resource 'a47c7b0ebbb442cdbc4adf259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Observation?category=vital-signs&patient=Patient/b60b818fad134c3095b34dd392be9533' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Observation?category=vital-signs&patient=Patient/b60b818fad134c3095b34dd392be9533"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 19,
            "link": [
                {
                    "relation": "self",
                    "url": "/Observation?patient=Patient%2Fb60b818fad134c3095b34dd392be9533&_count=20&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Observation?patient=Patient%2Fb60b818fad134c3095b34dd392be9533&_count=20&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Observation?patient=Patient%2Fb60b818fad134c3095b34dd392be9533&_count=20&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "378d88eb-cbfc-4668-a96e-c1e011f9f015",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "vital-signs",
                                        "display": "Vital Signs"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "85353-1",
                                    "display": "Vital Signs Panel"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-09T18:35:35.633932+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:35:35.651181+00:00",
                        "dataAbsentReason": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                    "code": "not-performed",
                                    "display": "Not Performed"
                                }
                            ]
                        },
                        "hasMember": [
                            {
                                "reference": "Observation/201d4404-60c0-4f07-88c1-534456271a74",
                                "type": "Observation",
                                "display": "Blood Pressure"
                            },
                            {
                                "reference": "Observation/60e563bd-7848-487d-8852-c0db383dc115",
                                "type": "Observation",
                                "display": "Oxygen Saturation Arterial"
                            },
                            {
                                "reference": "Observation/cb8bca44-d0de-48b0-8786-6887a4b649ec",
                                "type": "Observation",
                                "display": "Height"
                            },
                            {
                                "reference": "Observation/841187ae-0c35-4db7-8852-b5370e4a5c51",
                                "type": "Observation",
                                "display": "Pulse Rhythm"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "cb8bca44-d0de-48b0-8786-6887a4b649ec",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "vital-signs",
                                        "display": "Vital Signs"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "8302-2",
                                    "display": "Height"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-09T18:35:35.754424+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:35:35.756630+00:00",
                        "valueQuantity": {
                            "value": 69.0,
                            "unit": "in",
                            "system": "http://unitsofmeasure.org",
                            "code": "[in_i]"
                        },
                        "derivedFrom": [
                            {
                                "reference": "Observation/378d88eb-cbfc-4668-a96e-c1e011f9f015",
                                "type": "Observation"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "60e563bd-7848-487d-8852-c0db383dc115",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "vital-signs",
                                        "display": "Vital Signs"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "2708-6",
                                    "display": "Oxygen Saturation Arterial"
                                },
                                {
                                    "system": "http://loinc.org",
                                    "code": "59408-5",
                                    "display": "Oxygen Saturation"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-09T18:35:35.744026+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:35:35.745602+00:00",
                        "valueQuantity": {
                            "value": 98.0,
                            "unit": "%",
                            "system": "http://unitsofmeasure.org",
                            "code": "%"
                        },
                        "derivedFrom": [
                            {
                                "reference": "Observation/378d88eb-cbfc-4668-a96e-c1e011f9f015",
                                "type": "Observation"
                            }
                        ],
                        "component": [
                            {
                                "code": {
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "3150-0",
                                            "display": "Inhaled oxygen concentration"
                                        }
                                    ]
                                },
                                "valueQuantity": {
                                    "value": 98.0,
                                    "unit": "%",
                                    "system": "http://unitsofmeasure.org",
                                    "code": "%"
                                }
                            },
                            {
                                "code": {
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "3151-8",
                                            "display": "Inhaled oxygen flow rate"
                                        }
                                    ]
                                },
                                "dataAbsentReason": {
                                    "coding": [
                                        {
                                            "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                            "code": "not-performed",
                                            "display": "Not Performed"
                                        }
                                    ]
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "841187ae-0c35-4db7-8852-b5370e4a5c51",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "vital-signs",
                                        "display": "Vital Signs"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "8884-9",
                                    "display": "Pulse Rhythm"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-09T18:35:35.739851+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:35:35.741587+00:00",
                        "valueString": "Regular",
                        "derivedFrom": [
                            {
                                "reference": "Observation/378d88eb-cbfc-4668-a96e-c1e011f9f015",
                                "type": "Observation"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "201d4404-60c0-4f07-88c1-534456271a74",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "vital-signs",
                                        "display": "Vital Signs"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "85354-9",
                                    "display": "Blood Pressure"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-09T18:35:35.714893+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:35:35.716508+00:00",
                        "valueString": "120/80 mmHg",
                        "derivedFrom": [
                            {
                                "reference": "Observation/378d88eb-cbfc-4668-a96e-c1e011f9f015",
                                "type": "Observation"
                            }
                        ],
                        "component": [
                            {
                                "code": {
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "8480-6",
                                            "display": "Systolic blood pressure"
                                        }
                                    ]
                                },
                                "valueQuantity": {
                                    "value": 120.0,
                                    "unit": "mmHg",
                                    "system": "http://unitsofmeasure.org",
                                    "code": "mm[Hg]"
                                }
                            },
                            {
                                "code": {
                                    "coding": [
                                        {
                                            "system": "http://loinc.org",
                                            "code": "8462-4",
                                            "display": "Diastolic blood pressure"
                                        }
                                    ]
                                },
                                "valueQuantity": {
                                    "value": 80.0,
                                    "unit": "mmHg",
                                    "system": "http://unitsofmeasure.org",
                                    "code": "mm[Hg]"
                                }
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "93d50727-307e-4be4-b4b3-fad266e22083",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "social-history",
                                        "display": "Social History"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "76503-2",
                                    "display": "HARK - Kick"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:34.594656+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:41:38.029091+00:00",
                        "valueCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "LA33-6",
                                    "display": "Yes"
                                }
                            ]
                        },
                        "derivedFrom": [
                            {
                                "reference": "QuestionnaireResponse/74b511d0-a112-48ff-9e03-ba5f103a2a15",
                                "type": "QuestionnaireResponse"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "b37b8285-b1e7-4298-9c25-a62b1303f799",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "social-history",
                                        "display": "Social History"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "76502-4",
                                    "display": "HARK - Rape"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:34.594656+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:41:38.024815+00:00",
                        "valueCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "LA33-6",
                                    "display": "Yes"
                                }
                            ]
                        },
                        "derivedFrom": [
                            {
                                "reference": "QuestionnaireResponse/74b511d0-a112-48ff-9e03-ba5f103a2a15",
                                "type": "QuestionnaireResponse"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "d3d10677-c211-4a04-ab8f-d5fe4b736bf8",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "social-history",
                                        "display": "Social History"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "76501-6",
                                    "display": "HARK - Afraid"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:34.594656+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:41:38.020391+00:00",
                        "valueCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "LA33-6",
                                    "display": "Yes"
                                }
                            ]
                        },
                        "derivedFrom": [
                            {
                                "reference": "QuestionnaireResponse/74b511d0-a112-48ff-9e03-ba5f103a2a15",
                                "type": "QuestionnaireResponse"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "77e9ef2c-f702-4cf7-ae6d-a093527a9727",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "social-history",
                                        "display": "Social History"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "76500-8",
                                    "display": "HARK - Humiliated"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:34.594656+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:41:38.012952+00:00",
                        "valueCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "LA33-6",
                                    "display": "Yes"
                                }
                            ]
                        },
                        "derivedFrom": [
                            {
                                "reference": "QuestionnaireResponse/74b511d0-a112-48ff-9e03-ba5f103a2a15",
                                "type": "QuestionnaireResponse"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "79e21363-d1e2-4be9-a9d0-2a737c595cd6",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "laboratory",
                                        "display": "Laboratory"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "extension": [
                                {
                                    "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
                                    "valueCode": "unsupported"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-03T07:00:00+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-08T20:11:12.198162+00:00",
                        "dataAbsentReason": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                    "code": "not-performed",
                                    "display": "Not Performed"
                                }
                            ]
                        },
                        "hasMember": [
                            {
                                "reference": "Observation/13a6df29-a0c7-4233-a4e5-940c82f58006",
                                "type": "Observation",
                                "display": "Act.Prt.C Resist."
                            },
                            {
                                "reference": "Observation/84c34368-d839-4bb2-b967-787ecef5b595",
                                "type": "Observation",
                                "display": "Amended report:"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "84c34368-d839-4bb2-b967-787ecef5b595",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "laboratory",
                                        "display": "Laboratory"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "N/A",
                                    "display": "Amended report:"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-03T07:00:00+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-08T20:11:12.256507+00:00",
                        "valueString": "test"
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "13a6df29-a0c7-4233-a4e5-940c82f58006",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "laboratory",
                                        "display": "Laboratory"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "13590-5",
                                    "display": "Act.Prt.C Resist."
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-03T07:00:00+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-08T20:11:12.243418+00:00",
                        "specimen": {
                            "reference": "Specimen/0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d",
                            "type": "Specimen"
                        },
                        "valueQuantity": {
                            "value": 1.0,
                            "unit": "ratio",
                            "system": "http://unitsofmeasure.org"
                        }
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "f7370ea2-f44b-4f47-9ba1-073db8e6c365",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "survey",
                                        "display": "Survey"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "76499-3"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:34.594656+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-09T18:41:37.996595+00:00",
                        "valueQuantity": {
                            "value": 4.0,
                            "system": "http://unitsofmeasure.org"
                        },
                        "derivedFrom": [
                            {
                                "reference": "QuestionnaireResponse/74b511d0-a112-48ff-9e03-ba5f103a2a15",
                                "type": "QuestionnaireResponse"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "1397bed8-7bab-4fdf-b926-b7542ccfbef0",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "social-history",
                                        "display": "Social History"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "8287-5",
                                    "display": "Head circumference (cm)"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:34.594656+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-08T18:58:45.819506+00:00",
                        "valueCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "8287-5",
                                    "display": "20"
                                }
                            ]
                        },
                        "derivedFrom": [
                            {
                                "reference": "QuestionnaireResponse/82f09164-afa8-462c-88e0-552b89976613",
                                "type": "QuestionnaireResponse"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "221534cf-690f-4166-86f2-7f392edf4348",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "social-history",
                                        "display": "Social History"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "8306-3",
                                    "display": "Body length (in)"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:34.594656+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-08T18:58:45.805651+00:00",
                        "valueCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "8306-3",
                                    "display": "30"
                                }
                            ]
                        },
                        "derivedFrom": [
                            {
                                "reference": "QuestionnaireResponse/82f09164-afa8-462c-88e0-552b89976613",
                                "type": "QuestionnaireResponse"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "84a41e03-34f2-414e-8bf8-c7fc8ee75c16",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "vital-signs",
                                        "display": "Vital Signs"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "8289-1",
                                    "display": "Head Occipital-frontal circumference Percentile"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:45.616779+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-08T18:58:45.781371+00:00",
                        "valueQuantity": {
                            "value": 90.0,
                            "unit": "%",
                            "system": "http://unitsofmeasure.org",
                            "code": "%"
                        },
                        "derivedFrom": [
                            {
                                "reference": "Observation/74c7bcd6-a229-4bef-82fa-b0fec3c0cc1a",
                                "type": "Observation"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "ab2cce20-4186-4ccd-bf7d-93009fbe7748",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "vital-signs",
                                        "display": "Vital Signs"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "8287-5",
                                    "display": "Head Circumference"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:45.616779+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-08T18:58:45.766580+00:00",
                        "valueQuantity": {
                            "value": 37.0,
                            "unit": "cm",
                            "system": "http://unitsofmeasure.org",
                            "code": "cm"
                        },
                        "derivedFrom": [
                            {
                                "reference": "Observation/74c7bcd6-a229-4bef-82fa-b0fec3c0cc1a",
                                "type": "Observation"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "d0bb3a0f-8925-4bb8-958a-af0d37b095ab",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "vital-signs",
                                        "display": "Vital Signs"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "8306-3",
                                    "display": "Length"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:45.616779+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-08T18:58:45.751224+00:00",
                        "valueQuantity": {
                            "value": 20.0,
                            "unit": "in",
                            "system": "http://unitsofmeasure.org",
                            "code": "[in_i]"
                        },
                        "derivedFrom": [
                            {
                                "reference": "Observation/74c7bcd6-a229-4bef-82fa-b0fec3c0cc1a",
                                "type": "Observation"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Observation",
                        "id": "74c7bcd6-a229-4bef-82fa-b0fec3c0cc1a",
                        "status": "final",
                        "category": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                        "code": "vital-signs",
                                        "display": "Vital Signs"
                                    }
                                ]
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://loinc.org",
                                    "code": "85353-1",
                                    "display": "Vital Signs Panel"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b60b818fad134c3095b34dd392be9533",
                            "type": "Patient"
                        },
                        "effectiveDateTime": "2024-04-08T18:58:45.616779+00:00",
                        "performer":
                        [
                            {
                                "reference": "Practitioner/883f7147517e444fb746cdac3860b0dc",
                                "type": "Practitioner"
                            }
                        ],
                        "issued": "2024-04-08T18:58:45.629738+00:00",
                        "dataAbsentReason": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                                    "code": "not-performed",
                                    "display": "Not Performed"
                                }
                            ]
                        },
                        "hasMember": [
                            {
                                "reference": "Observation/d0bb3a0f-8925-4bb8-958a-af0d37b095ab",
                                "type": "Observation",
                                "display": "Length"
                            },
                            {
                                "reference": "Observation/ab2cce20-4186-4ccd-bf7d-93009fbe7748",
                                "type": "Observation",
                                "display": "Head Circumference"
                            },
                            {
                                "reference": "Observation/84a41e03-34f2-414e-8bf8-c7fc8ee75c16",
                                "type": "Observation",
                                "display": "Head Occipital-frontal circumference Percentile"
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Organization

Source: https://docs.canvasmedical.com/api/organization/

### 
A formally or informally recognized grouping of people or organizations formed for the purpose of achieving some form of collective action. Includes companies, institutions, corporations, departments, community groups, healthcare practice groups, payer/insurer, etc.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-organization.html>   
Organizations come from four different Canvas data types: Organizations, Vendors, Insurers, and Service Providers. Organizations, Vendors, and Insurers can be managed in Canvas Settings. Service Providers are created automatically when an external provider is referenced, such as when a referral or imaging order is placed, when an external member is added to a patient's Care Team, or when an inbound fax is received. They appear as Organization participants on patient [Care Teams](/api/careteam). FHIR Organizations created by Insurers in Canvas are useful in the [FHIR Coverage](/api/coverage) payor attribute.
### Endpoints
get/Organization/{id} get/Organization
get
/Organization/{id}
#### Organization read
Read an Organization resource.
### Path Parameters
id required
string
The unique identifier for the Organization   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Organization.
identifier
array[json]
Identifies this organization across multiple systems.  
When relevant, group NPI values, taxonomy ids, and tax ids will be found for relevant organizations. Identifiers for vendors and transactors, such as insurance payor values, are not yet supported.
Click to view child attributes
type
array
Description of identifier.   
Currently only type will appear for Organizations with a Tax ID.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v2-0203
code
string
The code identifying the identifier type.
**Value Options Supported:**
  - TAX
display
string
The display name of the coding.
**Value Options Supported:**
  - Tax ID number
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - urn:oid:2.16.840.1.113883.4.4 (for Tax ID)
  - http://hl7.org/fhir/sid/us-npi (for NPI)
  - http://nucc.org/provider-taxonomy (for Provider Taxonomy)
value
string
The value that is unique.
type
array[json]
The kind of organization.   
Maps Canvas data types to the `http://terminology.hl7.org/CodeSystem/organization-type` value set:  
`prov` — ServiceProviders and Organizations  
`pay` — Transactors/Insurers  
`other` — the Canvas Vendor
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/organization-type
code
string
The code for the organization type.
**Value Options Supported:**
  - prov (Healthcare Provider)
  - pay (Payer)
  - other (Other)
display
string
The display name of the coding.
text
string
Plain text representation of the type.
**Value Options Supported:**
  - Healthcare Provider
  - Payer
  - Other
active
boolean
Whether the organization's record is still in active use.
name
string
Name used for the organization.
telecom
array[json]
A contact detail for the organization (phone / email / fax).
Click to view child attributes
system
enum [ phone | fax | email | pager | other ]
Telecommunications form for contact point - what communications system is required to make use of the contact.
value
string
The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address).
use
enum [ work | temp | old | mobile ]
Identifies the purpose for the contact point.
address
array[json]
An address for the organization. This will include both physical and billing addresses, when available.
Click to view child attributes
use
enum [ work | temp | old | billing ]
Defines the purpose of this address.
type
enum [ both | physical | postal ]
Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses).
line
array[string]
This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.  
The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.
city
string
The name of the city, town, suburb, village or other community or delivery center.
state
string
Two-letter state abbreviation of the address.
postalCode
string
The 5-digit postal code of the address.
country
string
Specifies the country in which the organization's address is located.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Organization
#### Organization search
Search for Organization resources.
### Query Parameters
****
_id
string
The identifier of the Organization
address
string
A server defined search that may match any of the string fields in the Address, including line, city, state, and/or postalCode
name
string
A portion of the organization's name
type
token
A code for the type of organization.
**Search Values Supported:**
  - prov
  - pay
  - other
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Organization.
identifier
array[json]
Identifies this organization across multiple systems.  
When relevant, group NPI values, taxonomy ids, and tax ids will be found for relevant organizations. Identifiers for vendors and transactors, such as insurance payor values, are not yet supported.
Click to view child attributes
type
array
Description of identifier.   
Currently only type will appear for Organizations with a Tax ID.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v2-0203
code
string
The code identifying the identifier type.
**Value Options Supported:**
  - TAX
display
string
The display name of the coding.
**Value Options Supported:**
  - Tax ID number
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - urn:oid:2.16.840.1.113883.4.4 (for Tax ID)
  - http://hl7.org/fhir/sid/us-npi (for NPI)
  - http://nucc.org/provider-taxonomy (for Provider Taxonomy)
value
string
The value that is unique.
type
array[json]
The kind of organization.   
Maps Canvas data types to the `http://terminology.hl7.org/CodeSystem/organization-type` value set:  
`prov` — ServiceProviders and Organizations  
`pay` — Transactors/Insurers  
`other` — the Canvas Vendor
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/organization-type
code
string
The code for the organization type.
**Value Options Supported:**
  - prov (Healthcare Provider)
  - pay (Payer)
  - other (Other)
display
string
The display name of the coding.
text
string
Plain text representation of the type.
**Value Options Supported:**
  - Healthcare Provider
  - Payer
  - Other
active
boolean
Whether the organization's record is still in active use.
name
string
Name used for the organization.
telecom
array[json]
A contact detail for the organization (phone / email / fax).
Click to view child attributes
system
enum [ phone | fax | email | pager | other ]
Telecommunications form for contact point - what communications system is required to make use of the contact.
value
string
The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address).
use
enum [ work | temp | old | mobile ]
Identifies the purpose for the contact point.
address
array[json]
An address for the organization. This will include both physical and billing addresses, when available.
Click to view child attributes
use
enum [ work | temp | old | billing ]
Defines the purpose of this address.
type
enum [ both | physical | postal ]
Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses).
line
array[string]
This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.  
The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.
city
string
The name of the city, town, suburb, village or other community or delivery center.
state
string
Two-letter state abbreviation of the address.
postalCode
string
The 5-digit postal code of the address.
country
string
Specifies the country in which the organization's address is located.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Organization/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Organization/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Organization",
            "id": "192cf534-fc40-4c68-a233-062807338635",
            "identifier": [
                {
                    "system": "http://hl7.org/fhir/sid/us-npi",
                    "value": "1111111112"
                },
                {
                    "system": "http://nucc.org/provider-taxonomy",
                    "value": "207Q00000X"
                },
                {
                    "type": {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                "code": "TAX",
                                "display": "Tax ID number"
                            }
                        ]
                    },
                    "system": "urn:oid:2.16.840.1.113883.4.4",
                    "value": "123456789"
                }
            ],
            "type": [
                {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                            "code": "prov",
                            "display": "Healthcare Provider"
                        }
                    ],
                    "text": "Healthcare Provider"
                }
            ],
            "active": true,
            "name": "Canvas Training Organization",
            "telecom": [
                {
                    "system": "fax",
                    "value": "2314217892",
                    "use": "work"
                },
                {
                    "system": "email",
                    "value": "example@example.com",
                    "use": "work"
                },
                {
                    "system": "phone",
                    "value": "9567768088",
                    "use": "work"
                }
            ],
            "address": [
                {
                    "use": "work",
                    "type": "both",
                    "line": [
                        "3300 Washtenaw Avenue, Suite 227"
                    ],
                    "city": "Amherst",
                    "state": "MA",
                    "postalCode": "01002",
                    "country": "United States"
                },
                {
                    "use": "billing",
                    "type": "both",
                    "line": [
                        "1 Billing Lane"
                    ],
                    "city": "NY",
                    "state": "NY",
                    "postalCode": "11111",
                    "country": "USA"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Organization resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Organization?name=Canvas' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Organization?name=Canvas"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 2,
            "link": [
                {
                    "relation": "self",
                    "url": "/Organization?name=Canvas&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Organization?name=Canvas&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Organization?name=Canvas&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Organization",
                        "id": "00000000-0000-0000-0002-000000000000",
                        "type": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                                        "code": "other",
                                        "display": "Other"
                                    }
                                ],
                                "text": "Other"
                            }
                        ],
                        "active": true,
                        "name": "Canvas Medical",
                        "telecom": [
                            {
                                "system": "phone",
                                "value": "8003701416",
                                "use": "work"
                            },
                            {
                                "system": "email",
                                "value": "example@canvasmedical.com",
                                "use": "work"
                            }
                        ],
                        "address": [
                            {
                                "use": "work",
                                "type": "both",
                                "line": [
                                    "2037 Irving Street",
                                    "Suite 228"
                                ],
                                "city": "San Francisco",
                                "state": "CA",
                                "postalCode": "94122"
                            }
                        ]
                    }
                },
                {
                    "resource": {
                        "resourceType": "Organization",
                        "id": "192cf534-fc40-4c68-a233-062807338635",
                        "identifier": [
                            {
                                "system": "http://hl7.org/fhir/sid/us-npi",
                                "value": "1111111112"
                            },
                            {
                                "system": "http://nucc.org/provider-taxonomy",
                                "value": "207Q00000X"
                            },
                            {
                                "type": {
                                    "coding": [
                                        {
                                            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                            "code": "TAX",
                                            "display": "Tax ID number"
                                        }
                                    ]
                                },
                                "system": "urn:oid:2.16.840.1.113883.4.4",
                                "value": "123456789"
                            }
                        ],
                        "type": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/organization-type",
                                        "code": "prov",
                                        "display": "Healthcare Provider"
                                    }
                                ],
                                "text": "Healthcare Provider"
                            }
                        ],
                        "active": true,
                        "name": "Canvas Training Organization",
                        "telecom": [
                            {
                                "system": "fax",
                                "value": "2314217892",
                                "use": "work"
                            },
                            {
                                "system": "email",
                                "value": "example@example.com",
                                "use": "work"
                            },
                            {
                                "system": "phone",
                                "value": "9567768088",
                                "use": "work"
                            }
                        ],
                        "address": [
                            {
                                "use": "work",
                                "type": "both",
                                "line": [
                                    "3300 Washtenaw Avenue, Suite 227"
                                ],
                                "city": "Amherst",
                                "state": "MA",
                                "postalCode": "01002",
                                "country": "United States"
                            },
                            {
                                "use": "billing",
                                "type": "both",
                                "line": [
                                    "1 Billing Lane"
                                ],
                                "city": "NY",
                                "state": "NY",
                                "postalCode": "11111",
                                "country": "USA"
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Pagination

Source: https://docs.canvasmedical.com/api/pagination/

Most endpoints that perform search operations support pagination. For these endpoints, search results are paginated by default, with a `links` section as defined [by FHIR](http://hl7.org/fhir/R4/http.html#paging). The links include urls for `self`, `first`, `next`, and `last` as needed for the searchset. Clients that want all results will need to make use of these links to page through the data. Pagination links will not be provided for an empty result set. A tip when traversing through the pages, if a `next` relation is not in the links list, you are on the last page!
There is a maximum page size (`_count`) that is enforced by the server. This value is at 100 at the time of writing, but can change without warning. Clients must use the links in a search bundle to paginate after an initial search request is sent. When no count is specified in a search, it will default to 10.
In this example, `entry` contains 10 Observation resources - following the relative link marked as `next` returns the remaining 9.
    ```json
    {
        "resourceType": "Bundle",
        "type": "searchset",
        "total": 19,
        "link": [
            {
                "relation": "self",
                "url": "/Observation?_count=10&_offset=0"
            },
            {
                "relation": "first",
                "url": "/Observation?_count=10&_offset=0"
            },
            {
                "relation": "next",
                "url": "/Observation?_count=10&_offset=10"
            },
            {
                "relation": "last",
                "url": "/Observation?_count=10&_offset=10"
            }
        ],
        "entry": [
            {
                "resource": {
                    "resourceType": "Observation",
    ```

---

# Patient

Source: https://docs.canvasmedical.com/api/patient/

### 
Demographics and other administrative information about an individual or animal receiving care or other health-related services.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-patient.html>  
Canvas supports a number of FHIR extensions on this resource. See the `extension` attribute below for the full list of supported extension URLs and their value shapes. The `birthsex` extension is **required** on create and update.
#### Additional information
  - Manage a patient's patient-group membership with the FHIR [Group](/api/group) endpoints, or from a plugin with the SDK [Patient Group effect](/sdk/effect-patient-group/). Group create and update take the complete `member` array, so read the current group, change the member list (append a patient to add, filter a reference out to remove), and send the whole list back.
  - External identifiers you send on create or update (for example, an MRN from your own system) are stored and returned on a later Read, but they are not shown anywhere in the Canvas UI. The Canvas MRN itself is system-issued and cannot be set or overwritten.
  - Setting `active` to `false` hides the patient from the default patient list in the Canvas UI, which is a common way to hide duplicate records; clinical users can still search all patients, including inactive ones. FHIR Patient Search returns inactive patients by default; add `active=true` to exclude them.
  - Leave out the `photo` block entirely when you are not supplying a photo. A `photo` entry whose `data` is null makes the create request return a 500, even though the patient is still created.
**Related guides:**
  - [Testing Pharmacy Workflows in a Staging Environment](/guides/pharmacy-staging-testing/)
### Endpoints
post/Patient get/Patient/{id} put/Patient/{id} get/Patient
post
/Patient
#### Patient create
On success, the new Patient's identifier is returned in the `Location` header of the response. The patient record can be viewed in Canvas at _https:// <instance>.canvasmedical.com/patient/<id>_.   
Most fields populated through this endpoint will display and be editable on the Patient profile page.
### Attributes
resourceType
string required
The FHIR Resource name.
extension
array[json] required
Canvas-supported FHIR extensions on this resource. Each entry has a `url` identifying the extension, plus either a `valueX` field or — for compound extensions (**race** , **ethnicity** , **tribal-affiliation** , **preferred-pharmacy**) — a nested `extension` array carrying the value. The `url` is matched as an exact string.   
The **birthsex** extension (`http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex`) is **required** on create and update.
Click to view child attributes
url
string required
Identifies the extension. See the value-field descriptions below for which `url` pairs with which `valueX` (or nested `extension`) shape.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex (Required. Patient's sex assigned at birth, per ONC; aligns with the C-CDA Birth Sex Observation (LOINC 76689-9).)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex (Documented sex, distinct from sex at birth.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity (Gender the patient identifies as. Overrides the root gender field when provided.)
  - http://schemas.canvasmedical.com/fhir/extensions/sexual-orientation (Patient's sexual orientation.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-race (Patient's races. Compound — uses nested extension.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity (Patient's ethnicities. Compound — uses nested extension.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation (Tribe or band the patient associates with. Compound — uses nested extension.)
  - http://hl7.org/fhir/StructureDefinition/tz-code (Patient's timezone.)
  - http://schemas.canvasmedical.com/fhir/extensions/clinical-note (Free-text note shown under the patient's name on the clinical chart.)
  - http://schemas.canvasmedical.com/fhir/extensions/administrative-note (Free-text note shown under the patient's name on the administrative profile.)
  - http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy (Patient's preferred pharmacy. Compound — multiple allowed; one may be marked default.)
  - http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider (Default Practitioner used for eligibility checks.)
  - http://schemas.canvasmedical.com/fhir/extensions/patient-default-location (Default Location used for eligibility checks.)
  - http://schemas.canvasmedical.com/fhir/extensions/business-line (Business line the patient belongs to. Requires Business Line functionality on the instance.)
valueCode
string
Used by extensions whose value is a single code.   
**birthsex** — required when this extension is included.   
Code| Meaning  
---|---  
`M`| Male  
`F`| Female  
`OTH`| Other  
`UNK`| Unknown  
**sex**   
Code| Meaning  
---|---  
`184115007`| Patient sex unknown  
`248152002`| Female  
`248153007`| Male  
`33791000087105`| Identifies as nonbinary gender  
`asked-declined`| Asked but declined  
**sexual-orientation**   
Code| Meaning  
---|---  
`20430005`| Straight or heterosexual  
`38628009`| Lesbian, gay or homosexual  
`42035005`| Bisexual  
`OTH`| Something else, please describe  
`UNK`| Don't know  
`ASKU`| Choose not to disclose  
**tz-code** — any valid timezone code from the [FHIR timezone ValueSet](http://build.fhir.org/valueset-timezones.html), e.g., `America/New_York`.
valueString
string
Used by free-text extensions:   
  - **clinical-note** — displayed under the patient's name on the clinical chart. - **administrative-note** — displayed under the patient's name on the administrative profile.
valueId
string
Used by the **business-line** extension. The value is the `externallyExposableId` of the business line in Canvas.
valueCodeableConcept
json
Used by the **genderIdentity** extension. When this extension is provided, it overrides the root `gender` field.
Click to view child attributes
coding
array[json] required
Exactly one coding entry is allowed.
Click to view child attributes
system
string required
**Value Options Supported:**
  - http://snomed.info/sct
  - http://terminology.hl7.org/CodeSystem/v3-NullFlavor
code
string required
Gender identity code.
**Value Options Supported:**
  - 446151000124109 (Identifies as male gender)
  - 446141000124107 (Identifies as female gender)
  - 407377005 (Female-to-male transsexual)
  - 407376001 (Male-to-female transsexual)
  - 446131000124102 (Identifies as non-conforming gender)
  - OTH (Other)
  - ASKU (Asked but unknown)
display
string
Representation defined by the system.
text
string
valueReference
json
Used by **patient-default-provider** (must reference a Practitioner) and **patient-default-location** (must reference a Location). Both set the default used for eligibility checks.
Click to view child attributes
reference
string required
Reference string in the form `Practitioner/{id}` or `Location/{id}`.
type
string
Resource type the reference points to.
**Value Options Supported:**
  - Practitioner
  - Location
extension
array[json]
Used by compound extensions whose value is itself a list of extensions. The shape of each inner entry depends on the outer `url`:   
**us-core-race** / **us-core-ethnicity** — one or more inner extensions with `url`: `ombCategory`, `detailed`, or `text`. For `ombCategory` / `detailed`, provide a `valueCoding`. For `text`, provide a `valueString`.   
**us-core-tribal-affiliation** — exactly one inner extension with `url`: `tribalAffiliation` and a `valueCodeableConcept` containing one or more codings (each requires `system`, `code`, and `display`).   
**preferred-pharmacy** — one inner extension with `url`: `ncpdp-id` is **required** ; the NCPDP number goes in `valueIdentifier.value` (must be exactly **7 digits** , left-padded with zeros). Optional inner extensions: `default` (boolean — at most one preferred pharmacy per patient may be set to `true`), `name`, `phone-number`, `address`, `fax-number`, `specialty_type` (each `valueString`).
Click to view child attributes
url
string required
Identifies the inner extension. See the parent description above for which value applies to which compound extension.
**Value Options Supported:**
  - ombCategory (race / ethnicity — coded category (with valueCoding).)
  - detailed (race / ethnicity — detailed coded value (with valueCoding).)
  - text (race / ethnicity — free-text representation (with valueString).)
  - tribalAffiliation (tribal-affiliation — wraps the codings (with valueCodeableConcept).)
  - ncpdp-id (preferred-pharmacy — required. Pharmacy NCPDP id (with valueIdentifier).)
  - default (preferred-pharmacy — marks this pharmacy as the default (with valueBoolean).)
  - name (preferred-pharmacy — pharmacy name (with valueString).)
  - phone-number (preferred-pharmacy — pharmacy phone number (with valueString).)
  - address (preferred-pharmacy — pharmacy address (with valueString).)
  - fax-number (preferred-pharmacy — pharmacy fax (with valueString).)
  - specialty_type (preferred-pharmacy — pharmacy specialty (with valueString).)
valueCoding
json
For race / ethnicity `ombCategory` and `detailed` inner extensions.
Click to view child attributes
system
string required
For known race / ethnicity codes use the OID; for `ASKU` use the v3-NullFlavor system.
**Value Options Supported:**
  - urn:oid:2.16.840.1.113883.6.238
  - http://terminology.hl7.org/CodeSystem/v3-NullFlavor
code
string required
Race or ethnicity code from the [CDC Race and Ethnicity CodeSystem](https://hl7.org/fhir/us/core/STU3.1.1/CodeSystem-cdcrec.html). Example race codes — `2131-1` (Other Race), `2106-3` (White). Example ethnicity codes — `2186-5` (Not Hispanic or Latino), `2135-2` (Hispanic or Latino).
display
string
valueCodeableConcept
json
For the **tribal-affiliation** inner extension. Contains a `coding` list with at least one entry; each coding requires `system`, `code`, and `display`.
Click to view child attributes
coding
array[json] required
Click to view child attributes
system
string required
Typically `http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS`.
code
string required
display
string required
valueIdentifier
json
For the **preferred-pharmacy** `ncpdp-id` inner extension.
Click to view child attributes
value
string required
NCPDP identifier — must be **exactly 7 digits** , left-padded with zeros if needed.
system
string required
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber
valueBoolean
boolean
For the **preferred-pharmacy** `default` inner extension. At most one preferred-pharmacy entry per patient may be set to true.
valueString
string
Used in two contexts:   
• For the **race** / **ethnicity** `text` inner extension — a free-text representation of the race or ethnicity.   
• For the **preferred-pharmacy** metadata inner extensions (`name`, `phone-number`, `address`, `fax-number`, `specialty_type`) — free-text values about the pharmacy.
identifier
array[json]
External identifiers for this patient. None of these identifiers are surfaced on the patient chart, but they may help you correlate the Canvas patient with records in your own systems.
The MRN is auto-issued by Canvas; do not include it on create.
Click to view child attributes
use
enum [ usual | official | temp | secondary | old ]
Purpose of this identifier. Defaults to **usual** if omitted.
system
string required
Free-text namespace for the value (e.g., "HealthCo", or a URL).
value
string required
The identifier value. Must be 1–255 characters.
period
json
Validity window for this identifier. End-before-start is not validated.
Click to view child attributes
start
date
Inclusive start date (YYYY-MM-DD). Defaults to **1970-01-01** if omitted.
end
date
Inclusive end date (YYYY-MM-DD). Defaults to **2100-12-31** if omitted.
active
boolean
Whether the patient is active in the healthcare system. Defaults to `true` if omitted on create.
name
array[json] required
One or more names for the patient. At least one entry is required, and exactly one entry must have `use`: **official** — that entry determines the patient's first/middle/last/prefix/suffix shown across the Canvas UI.   
Additional entries with `use`: **nickname** , **maiden** , or **old** are accepted: the first item in the `given` list of a **nickname** entry is stored as the patient's preferred name. **maiden** and **old** entries are stored but not displayed in the Canvas UI. Entries with any other `use` value are ignored.   
In the Canvas UI, patients display as `first last suffix (nickname)`, and search supports first, middle, last, suffix, and nickname.
Click to view child attributes
use
enum [ official | nickname | old | maiden ] required
At least one entry with `use`: **official** is required. See the parent description for how each accepted value is handled.
family
string required
Family name (often called 'Surname'). Required on the **official** entry to populate the patient's last name.
given
array[string] required
Given names. The first item populates the patient's first name; remaining items are joined with a space and stored as the middle name.   
For a **nickname** entry, only the first item is read and stored as the patient's preferred name. Surrounding whitespace is trimmed, and a value that is empty or whitespace-only is stored as an empty preferred name.
prefix
array[string]
Parts that come before the name (e.g., "Dr.", "Mr."). Stored but not displayed in the Canvas UI.
suffix
array[string]
Parts that come after the name (e.g., "Jr.", "III"). Surfaced in the Canvas UI.
period
json
Validity window for this name.
Click to view child attributes
start
date
Inclusive start date (YYYY-MM-DD).
end
date
Inclusive end date (YYYY-MM-DD).
telecom
array[json]
Patient contact points (phone / email / fax / etc.).   
Phone and email entries are surfaced in the Canvas UI. Other systems are accepted and stored but are not displayed.
Click to view child attributes
extension
array[json]
Optional flags about the contact point. The `has-consent` extension records that the patient has consented to receive messages at this contact point — set the `url` to **http://schemas.canvasmedical.com/fhir/extensions/has-consent** with `valueBoolean: true`.   
**Note:** Setting `has-consent` here does not send a verification email or text as the Canvas UI does — it bypasses verification and marks the contact point as verified.
Click to view child attributes
url
string required
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/has-consent
valueBoolean
boolean required
system
enum [ phone | fax | email | pager | url | sms | other ] required
Telecommunications form. `url` is stored internally as **other** , and `sms` is stored as **phone**.
value
string required
The contact point value (phone number, email address, etc.).
use
enum [ home | work | temp | old | mobile ]
Purpose of this contact point. Defaults to **home** if omitted.
rank
integer
Preferred order across contact points of the same `system`. Defaults to **1**.
gender
enum [ male | female | other | unknown ] required
Maps to the gender identity field in the Canvas UI. See the [administrative gender ValueSet](https://hl7.org/fhir/R4/valueset-administrative-gender.html).   
**unknown** displays as "choose not to disclose" on the patient chart. **other** displays as "Additional gender category or other, please specify".   
**Note:** If the `genderIdentity` extension is also provided, it overrides this field.
birthDate
date required
Patient's date of birth, formatted **YYYY-MM-DD**.   
Canvas also accepts partial dates: **YYYY-MM** defaults to the 1st of the month, and **YYYY** defaults to January 1st.
deceasedDateTime
datetime
Date/time the patient died. Mutually exclusive with `deceasedBoolean` — provide one or the other.
deceasedBoolean
boolean
Whether the patient is deceased. Use when an exact date/time isn't known.
address
array[json]
Address(es) for the patient.
Click to view child attributes
use
enum [ home | work | temp | old ]
Defaults to **home** if omitted.
type
enum [ both | physical | postal ]
Defaults to **both** if omitted.
line
array[string]
First item populates address line 1; remaining items are concatenated as address line 2.
city
string
City of the address.
state
string
2-letter state abbreviation.
postalCode
string
5-digit postal code.
country
string
ISO 3166 2-letter country code. Defaults to **us**.
period
json
Validity window for this address.
Click to view child attributes
start
date
Inclusive start date.
end
date
Inclusive end date.
photo
array[json]
Patient photo. Displayed as the avatar in the Canvas UI. Omit the block when not supplying a photo.
Click to view child attributes
data
string
Base64-encoded image content. Use on create or update to upload a photo. Do not send a `photo` entry with null `data`.
contact
array[json]
Contact parties (e.g., guardian, partner, friend, emergency contact) for the patient. Contact details display on the Patient profile page in the Canvas UI.
Click to view child attributes
relationship
array[json]
Codings describing the relationship of the contact to the patient. Codings can come from the standard `v3-RoleCode` system or from your instance's [configurable contact categories](https://help.canvasmedical.com/articles/8258338559-contact-categories), including the built-in **Emergency contact** category (`code`: `EMC`). Multiple codings can be combined on a single relationship to capture, e.g., both a familial relationship (`SPS` = spouse) and a contact-category role (`EMC` = emergency contact).
Click to view child attributes
coding
array[json]
Code(s) defined by a terminology system.
Click to view child attributes
system
string required
The system URL of the coding. Use **http://terminology.hl7.org/CodeSystem/v3-RoleCode** for relationship-type codings from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html), or **http://schemas.canvasmedical.com/fhir/contact-category** for Canvas's configurable contact categories.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-RoleCode
  - http://schemas.canvasmedical.com/fhir/contact-category
code
string required
The code of the relationship or contact category.   
For the `v3-RoleCode` system, values come from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html).   
For the `contact-category` system, values are the codes configured under [Contact Categories](https://help.canvasmedical.com/articles/8258338559-contact-categories) on your instance — for example, `EMC` (Emergency contact), `ARI` (Authorized for release of information), `POA` (Power of attorney).
display
string
Human-readable name of the coding.
name
json required
A name for the contact.   
Canvas only stores `name.text`. The structured sub-fields (`family`, `given`, `prefix`, `suffix`) are populated on read **only when the contact is itself a Canvas patient** , and are derived from that patient's record — they are not accepted on create or update.
Click to view child attributes
text
string required
Free-text representation of the contact's full name. The only name field stored for a non-patient contact.
telecom
array[json]
Contact points for this contact.   
Canvas stores at most one phone and one email per contact: the **first** entry with `system`: **phone** is stored as the contact's phone number, and the **first** entry with `system`: **email** is stored as the email. Entries with any other `system` value are ignored.
Click to view child attributes
system
enum [ phone | fax | email | pager | url | sms | other ] required
Only `phone` and `email` are stored on the contact; other values are ignored.
value
string required
The contact point value.   
For `system: phone`, the value must be **exactly 10 digits** with no other characters (no dashes, spaces, or country code). Phone values that don't match are rejected.
use
enum [ home | work | temp | old | mobile ]
Purpose of this contact point.
communication
array[json]
Languages used to communicate with the patient.
Click to view child attributes
language
json
A language usable for communicating with the patient. See [Common Languages](https://hl7.org/fhir/R4/valueset-languages.html) (preferred) or [AllLanguages](https://hl7.org/fhir/R4/valueset-all-languages.html).
Click to view child attributes
coding
array[json]
Exactly one coding entry is allowed.
Click to view child attributes
system
string required
**Value Options Supported:**
  - urn:ietf:bcp:47
  - http://hl7.org/fhir/ValueSet/all-languages
code
string required
BCP-47 language code (e.g., `en`).
display
string required
Human-readable language name (e.g., `English`).
text
string
Plain-text representation of the language.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Patient/{id}
#### Patient read
### Path Parameters
id required
string
The unique identifier for the Patient   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
Canvas-issued unique identifier (UUID) for this Patient. It is the same id that appears in the URL of the patient's chart.
text
json
A human-readable narrative summarizing the resource. Generated by Canvas; not accepted on create or update.
extension
array[json]
Canvas-supported FHIR extensions on this resource. Each entry has a `url` identifying the extension, plus either a `valueX` field or — for compound extensions (**race** , **ethnicity** , **tribal-affiliation** , **preferred-pharmacy**) — a nested `extension` array carrying the value. The `url` is matched as an exact string.   
The **birthsex** extension (`http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex`) is **required** on create and update.
Click to view child attributes
url
string
Identifies the extension. See the value-field descriptions below for which `url` pairs with which `valueX` (or nested `extension`) shape.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex (Required. Patient's sex assigned at birth, per ONC; aligns with the C-CDA Birth Sex Observation (LOINC 76689-9).)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex (Documented sex, distinct from sex at birth.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity (Gender the patient identifies as. Overrides the root gender field when provided.)
  - http://schemas.canvasmedical.com/fhir/extensions/sexual-orientation (Patient's sexual orientation.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-race (Patient's races. Compound — uses nested extension.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity (Patient's ethnicities. Compound — uses nested extension.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation (Tribe or band the patient associates with. Compound — uses nested extension.)
  - http://hl7.org/fhir/StructureDefinition/tz-code (Patient's timezone.)
  - http://schemas.canvasmedical.com/fhir/extensions/clinical-note (Free-text note shown under the patient's name on the clinical chart.)
  - http://schemas.canvasmedical.com/fhir/extensions/administrative-note (Free-text note shown under the patient's name on the administrative profile.)
  - http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy (Patient's preferred pharmacy. Compound — multiple allowed; one may be marked default.)
  - http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider (Default Practitioner used for eligibility checks.)
  - http://schemas.canvasmedical.com/fhir/extensions/patient-default-location (Default Location used for eligibility checks.)
  - http://schemas.canvasmedical.com/fhir/extensions/business-line (Business line the patient belongs to. Requires Business Line functionality on the instance.)
valueCode
string
Used by extensions whose value is a single code.   
**birthsex** — required when this extension is included.   
Code| Meaning  
---|---  
`M`| Male  
`F`| Female  
`OTH`| Other  
`UNK`| Unknown  
**sex**   
Code| Meaning  
---|---  
`184115007`| Patient sex unknown  
`248152002`| Female  
`248153007`| Male  
`33791000087105`| Identifies as nonbinary gender  
`asked-declined`| Asked but declined  
**sexual-orientation**   
Code| Meaning  
---|---  
`20430005`| Straight or heterosexual  
`38628009`| Lesbian, gay or homosexual  
`42035005`| Bisexual  
`OTH`| Something else, please describe  
`UNK`| Don't know  
`ASKU`| Choose not to disclose  
**tz-code** — any valid timezone code from the [FHIR timezone ValueSet](http://build.fhir.org/valueset-timezones.html), e.g., `America/New_York`.
valueString
string
Used by free-text extensions:   
  - **clinical-note** — displayed under the patient's name on the clinical chart. - **administrative-note** — displayed under the patient's name on the administrative profile.
valueId
string
Used by the **business-line** extension. The value is the `externallyExposableId` of the business line in Canvas.
valueCodeableConcept
json
Used by the **genderIdentity** extension. When this extension is provided, it overrides the root `gender` field.
Click to view child attributes
coding
array[json]
Exactly one coding entry is allowed.
Click to view child attributes
system
string
**Value Options Supported:**
  - http://snomed.info/sct
  - http://terminology.hl7.org/CodeSystem/v3-NullFlavor
code
string
Gender identity code.
**Value Options Supported:**
  - 446151000124109 (Identifies as male gender)
  - 446141000124107 (Identifies as female gender)
  - 407377005 (Female-to-male transsexual)
  - 407376001 (Male-to-female transsexual)
  - 446131000124102 (Identifies as non-conforming gender)
  - OTH (Other)
  - ASKU (Asked but unknown)
display
string
Representation defined by the system.
text
string
valueReference
json
Used by **patient-default-provider** (must reference a Practitioner) and **patient-default-location** (must reference a Location). Both set the default used for eligibility checks.
Click to view child attributes
reference
string
Reference string in the form `Practitioner/{id}` or `Location/{id}`.
type
string
Resource type the reference points to.
**Value Options Supported:**
  - Practitioner
  - Location
extension
array[json]
Used by compound extensions whose value is itself a list of extensions. The shape of each inner entry depends on the outer `url`:   
**us-core-race** / **us-core-ethnicity** — one or more inner extensions with `url`: `ombCategory`, `detailed`, or `text`. For `ombCategory` / `detailed`, provide a `valueCoding`. For `text`, provide a `valueString`.   
**us-core-tribal-affiliation** — exactly one inner extension with `url`: `tribalAffiliation` and a `valueCodeableConcept` containing one or more codings (each requires `system`, `code`, and `display`).   
**preferred-pharmacy** — one inner extension with `url`: `ncpdp-id` is **required** ; the NCPDP number goes in `valueIdentifier.value` (must be exactly **7 digits** , left-padded with zeros). Optional inner extensions: `default` (boolean — at most one preferred pharmacy per patient may be set to `true`), `name`, `phone-number`, `address`, `fax-number`, `specialty_type` (each `valueString`).
Click to view child attributes
url
string
Identifies the inner extension. See the parent description above for which value applies to which compound extension.
**Value Options Supported:**
  - ombCategory (race / ethnicity — coded category (with valueCoding).)
  - detailed (race / ethnicity — detailed coded value (with valueCoding).)
  - text (race / ethnicity — free-text representation (with valueString).)
  - tribalAffiliation (tribal-affiliation — wraps the codings (with valueCodeableConcept).)
  - ncpdp-id (preferred-pharmacy — required. Pharmacy NCPDP id (with valueIdentifier).)
  - default (preferred-pharmacy — marks this pharmacy as the default (with valueBoolean).)
  - name (preferred-pharmacy — pharmacy name (with valueString).)
  - phone-number (preferred-pharmacy — pharmacy phone number (with valueString).)
  - address (preferred-pharmacy — pharmacy address (with valueString).)
  - fax-number (preferred-pharmacy — pharmacy fax (with valueString).)
  - specialty_type (preferred-pharmacy — pharmacy specialty (with valueString).)
valueCoding
json
For race / ethnicity `ombCategory` and `detailed` inner extensions.
Click to view child attributes
system
string
For known race / ethnicity codes use the OID; for `ASKU` use the v3-NullFlavor system.
**Value Options Supported:**
  - urn:oid:2.16.840.1.113883.6.238
  - http://terminology.hl7.org/CodeSystem/v3-NullFlavor
code
string
Race or ethnicity code from the [CDC Race and Ethnicity CodeSystem](https://hl7.org/fhir/us/core/STU3.1.1/CodeSystem-cdcrec.html). Example race codes — `2131-1` (Other Race), `2106-3` (White). Example ethnicity codes — `2186-5` (Not Hispanic or Latino), `2135-2` (Hispanic or Latino).
display
string
valueCodeableConcept
json
For the **tribal-affiliation** inner extension. Contains a `coding` list with at least one entry; each coding requires `system`, `code`, and `display`.
Click to view child attributes
coding
array[json]
Click to view child attributes
system
string
Typically `http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS`.
code
string
display
string
valueIdentifier
json
For the **preferred-pharmacy** `ncpdp-id` inner extension.
Click to view child attributes
value
string
NCPDP identifier — must be **exactly 7 digits** , left-padded with zeros if needed.
system
string
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber
valueBoolean
boolean
For the **preferred-pharmacy** `default` inner extension. At most one preferred-pharmacy entry per patient may be set to true.
valueString
string
Used in two contexts:   
• For the **race** / **ethnicity** `text` inner extension — a free-text representation of the race or ethnicity.   
• For the **preferred-pharmacy** metadata inner extensions (`name`, `phone-number`, `address`, `fax-number`, `specialty_type`) — free-text values about the pharmacy.
identifier
array[json]
External identifiers for this patient. None of these identifiers are surfaced on the patient chart, but they may help you correlate the Canvas patient with records in your own systems.
The array always includes the Canvas-issued MRN (an entry with `system`: **http://canvasmedical.com** and a coded `type` of MR). Additional entries are external identifiers added through prior create/update calls or via the Patient profile in the Canvas UI.
Click to view child attributes
id
string
Canvas-issued identifier for this entry. Include on update to target an existing identifier; omit to create a new one.
use
enum [ usual | official | temp | secondary | old ]
Purpose of this identifier. Defaults to **usual** if omitted.
system
string
Free-text namespace for the value (e.g., "HealthCo", or a URL).
value
string
The identifier value. Must be 1–255 characters.
period
json
Validity window for this identifier. End-before-start is not validated.
Click to view child attributes
start
date
Inclusive start date (YYYY-MM-DD). Defaults to **1970-01-01** if omitted.
end
date
Inclusive end date (YYYY-MM-DD). Defaults to **2100-12-31** if omitted.
type
json
Codeable concept identifying the kind of identifier.
assigner
json
Organization that issued id.
active
boolean
Whether the patient is active in the healthcare system. Defaults to `true` if omitted on create.
name
array[json]
One or more names for the patient. At least one entry is required, and exactly one entry must have `use`: **official** — that entry determines the patient's first/middle/last/prefix/suffix shown across the Canvas UI.   
Additional entries with `use`: **nickname** , **maiden** , or **old** are accepted: the first item in the `given` list of a **nickname** entry is stored as the patient's preferred name. **maiden** and **old** entries are stored but not displayed in the Canvas UI. Entries with any other `use` value are ignored.   
In the Canvas UI, patients display as `first last suffix (nickname)`, and search supports first, middle, last, suffix, and nickname.
Click to view child attributes
use
enum [ official | nickname | old | maiden ]
At least one entry with `use`: **official** is required. See the parent description for how each accepted value is handled.
family
string
Family name (often called 'Surname'). Required on the **official** entry to populate the patient's last name.
given
array[string]
Given names. The first item populates the patient's first name; remaining items are joined with a space and stored as the middle name.   
For a **nickname** entry, only the first item is read and stored as the patient's preferred name. Surrounding whitespace is trimmed, and a value that is empty or whitespace-only is stored as an empty preferred name.
prefix
array[string]
Parts that come before the name (e.g., "Dr.", "Mr."). Stored but not displayed in the Canvas UI.
suffix
array[string]
Parts that come after the name (e.g., "Jr.", "III"). Surfaced in the Canvas UI.
period
json
Validity window for this name.
Click to view child attributes
start
date
Inclusive start date (YYYY-MM-DD).
end
date
Inclusive end date (YYYY-MM-DD).
telecom
array[json]
Patient contact points (phone / email / fax / etc.).   
Phone and email entries are surfaced in the Canvas UI. Other systems are accepted and stored but are not displayed.
Click to view child attributes
id
string
Canvas-issued identifier for this contact point. Include on update to target an existing entry; omit to create a new one.
extension
array[json]
Optional flags about the contact point. The `has-consent` extension records that the patient has consented to receive messages at this contact point — set the `url` to **http://schemas.canvasmedical.com/fhir/extensions/has-consent** with `valueBoolean: true`.   
**Note:** Setting `has-consent` here does not send a verification email or text as the Canvas UI does — it bypasses verification and marks the contact point as verified.
Click to view child attributes
url
string
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/has-consent
valueBoolean
boolean
system
enum [ phone | fax | email | pager | url | sms | other ]
Telecommunications form. `url` is stored internally as **other** , and `sms` is stored as **phone**.
value
string
The contact point value (phone number, email address, etc.).
use
enum [ home | work | temp | old | mobile ]
Purpose of this contact point. Defaults to **home** if omitted.
rank
integer
Preferred order across contact points of the same `system`. Defaults to **1**.
gender
enum [ male | female | other | unknown ]
Maps to the gender identity field in the Canvas UI. See the [administrative gender ValueSet](https://hl7.org/fhir/R4/valueset-administrative-gender.html).   
**unknown** displays as "choose not to disclose" on the patient chart. **other** displays as "Additional gender category or other, please specify".   
**Note:** If the `genderIdentity` extension is also provided, it overrides this field.
birthDate
date
Patient's date of birth, formatted **YYYY-MM-DD**.   
Canvas also accepts partial dates: **YYYY-MM** defaults to the 1st of the month, and **YYYY** defaults to January 1st.
deceasedDateTime
datetime
Date/time the patient died. Mutually exclusive with `deceasedBoolean` — provide one or the other.
Returned in place of `deceasedBoolean` when an exact datetime is on file.
deceasedBoolean
boolean
Whether the patient is deceased. Use when an exact date/time isn't known.
Returned in place of `deceasedDateTime` when no exact datetime is on file.
address
array[json]
Address(es) for the patient.
Click to view child attributes
id
string
Canvas-issued identifier for this address.
use
enum [ home | work | temp | old ]
Defaults to **home** if omitted.
type
enum [ both | physical | postal ]
Defaults to **both** if omitted.
line
array[string]
First item populates address line 1; remaining items are concatenated as address line 2.
city
string
City of the address.
state
string
2-letter state abbreviation.
postalCode
string
5-digit postal code.
country
string
ISO 3166 2-letter country code. Defaults to **us**.
period
json
Validity window for this address.
Click to view child attributes
start
date
Inclusive start date.
end
date
Inclusive end date.
photo
array[json]
Patient photo. Displayed as the avatar in the Canvas UI. Omit the block when not supplying a photo.
Click to view child attributes
url
string
URI where the image can be retrieved. Returned on read/search; requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files).
contact
array[json]
Contact parties (e.g., guardian, partner, friend, emergency contact) for the patient. Contact details display on the Patient profile page in the Canvas UI.
Click to view child attributes
id
string
Canvas-issued identifier for this contact. Include on update to target an existing contact; omit to create a new one.
relationship
array[json]
Codings describing the relationship of the contact to the patient. Codings can come from the standard `v3-RoleCode` system or from your instance's [configurable contact categories](https://help.canvasmedical.com/articles/8258338559-contact-categories), including the built-in **Emergency contact** category (`code`: `EMC`). Multiple codings can be combined on a single relationship to capture, e.g., both a familial relationship (`SPS` = spouse) and a contact-category role (`EMC` = emergency contact).
Click to view child attributes
coding
array[json]
Code(s) defined by a terminology system.
Click to view child attributes
system
string
The system URL of the coding. Use **http://terminology.hl7.org/CodeSystem/v3-RoleCode** for relationship-type codings from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html), or **http://schemas.canvasmedical.com/fhir/contact-category** for Canvas's configurable contact categories.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-RoleCode
  - http://schemas.canvasmedical.com/fhir/contact-category
code
string
The code of the relationship or contact category.   
For the `v3-RoleCode` system, values come from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html).   
For the `contact-category` system, values are the codes configured under [Contact Categories](https://help.canvasmedical.com/articles/8258338559-contact-categories) on your instance — for example, `EMC` (Emergency contact), `ARI` (Authorized for release of information), `POA` (Power of attorney).
display
string
Human-readable name of the coding.
name
json
A name for the contact.   
Canvas only stores `name.text`. The structured sub-fields (`family`, `given`, `prefix`, `suffix`) are populated on read **only when the contact is itself a Canvas patient** , and are derived from that patient's record — they are not accepted on create or update.
Click to view child attributes
text
string
Free-text representation of the contact's full name. The only name field stored for a non-patient contact.
family
string
Family name. Populated on read only when the contact is a Canvas patient; derived from that patient's record.
given
array[string]
Given names. Populated on read only when the contact is a Canvas patient.
prefix
array[string]
Parts that come before the name. Populated on read only when the contact is a Canvas patient.
suffix
array[string]
Parts that come after the name. Populated on read only when the contact is a Canvas patient.
telecom
array[json]
Contact points for this contact.   
Canvas stores at most one phone and one email per contact: the **first** entry with `system`: **phone** is stored as the contact's phone number, and the **first** entry with `system`: **email** is stored as the email. Entries with any other `system` value are ignored.
Click to view child attributes
system
enum [ phone | fax | email | pager | url | sms | other ]
Only `phone` and `email` are stored on the contact; other values are ignored.
value
string
The contact point value.   
For `system: phone`, the value must be **exactly 10 digits** with no other characters (no dashes, spaces, or country code). Phone values that don't match are rejected.
use
enum [ home | work | temp | old | mobile ]
Purpose of this contact point.
address
json
Address where the contact can be reached. Populated on read only when the contact is itself a Canvas patient (the contact's primary address is surfaced); ignored on create and update.
Click to view child attributes
use
enum [ home | work | temp | old ]
type
enum [ both | physical | postal ]
line
array[string]
First item is address line 1; remaining items are concatenated as address line 2.
city
string
district
string
District name (aka county).
state
string
2-letter state abbreviation.
postalCode
string
5-digit postal code.
country
string
ISO 3166 2-letter country code.
period
json
Click to view child attributes
start
date
end
date
communication
array[json]
Languages used to communicate with the patient.
Click to view child attributes
language
json
A language usable for communicating with the patient. See [Common Languages](https://hl7.org/fhir/R4/valueset-languages.html) (preferred) or [AllLanguages](https://hl7.org/fhir/R4/valueset-all-languages.html).
Click to view child attributes
coding
array[json]
Exactly one coding entry is allowed.
Click to view child attributes
system
string
**Value Options Supported:**
  - urn:ietf:bcp:47
  - http://hl7.org/fhir/ValueSet/all-languages
code
string
BCP-47 language code (e.g., `en`).
display
string
Human-readable language name (e.g., `English`).
text
string
Plain-text representation of the language.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Patient/{id}
#### Patient update
**How updates and deletions to`identifier`, `telecom`, `address`, and `contact` are handled:**  
Each entry returned via Search/Read includes an `id`.   
• If the `id` is included in an entry, Canvas updates the matching record.   
• If the `id` is omitted, Canvas creates a new record.   
• If an entry returned via Search/Read is **not** included in the update body, it is deleted (with the exception of `identifier`, which is only deleted when its `period.end` is in the future).   
The same delete-on-omission behavior applies to the `preferred-pharmacy`, `patient-default-provider`, `patient-default-location`, and `business-line` extensions — their values are dropped if those extensions are not present on update. To keep a patient's current values, read the patient first and send these extensions back on the update.   
**Other fields**  
Any field that is required on create is also required on update. Optional fields that are not included in the update body retain their stored values.
### Attributes
resourceType
string required
The FHIR Resource name.
id
string
Canvas-issued unique identifier (UUID) for this Patient. It is the same id that appears in the URL of the patient's chart.
Must match the ID in the path parameter.
extension
array[json] required
Canvas-supported FHIR extensions on this resource. Each entry has a `url` identifying the extension, plus either a `valueX` field or — for compound extensions (**race** , **ethnicity** , **tribal-affiliation** , **preferred-pharmacy**) — a nested `extension` array carrying the value. The `url` is matched as an exact string.   
The **birthsex** extension (`http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex`) is **required** on create and update.
**Replace semantics on update:** the **preferred-pharmacy** , **patient-default-provider** , **patient-default-location** , and **business-line** extensions follow delete-on-omission — if not included in the request, the stored value is dropped. To keep a patient's current values, read the patient first and send these extensions back on the update.
Click to view child attributes
url
string required
Identifies the extension. See the value-field descriptions below for which `url` pairs with which `valueX` (or nested `extension`) shape.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex (Required. Patient's sex assigned at birth, per ONC; aligns with the C-CDA Birth Sex Observation (LOINC 76689-9).)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex (Documented sex, distinct from sex at birth.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity (Gender the patient identifies as. Overrides the root gender field when provided.)
  - http://schemas.canvasmedical.com/fhir/extensions/sexual-orientation (Patient's sexual orientation.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-race (Patient's races. Compound — uses nested extension.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity (Patient's ethnicities. Compound — uses nested extension.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation (Tribe or band the patient associates with. Compound — uses nested extension.)
  - http://hl7.org/fhir/StructureDefinition/tz-code (Patient's timezone.)
  - http://schemas.canvasmedical.com/fhir/extensions/clinical-note (Free-text note shown under the patient's name on the clinical chart.)
  - http://schemas.canvasmedical.com/fhir/extensions/administrative-note (Free-text note shown under the patient's name on the administrative profile.)
  - http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy (Patient's preferred pharmacy. Compound — multiple allowed; one may be marked default.)
  - http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider (Default Practitioner used for eligibility checks.)
  - http://schemas.canvasmedical.com/fhir/extensions/patient-default-location (Default Location used for eligibility checks.)
  - http://schemas.canvasmedical.com/fhir/extensions/business-line (Business line the patient belongs to. Requires Business Line functionality on the instance.)
valueCode
string
Used by extensions whose value is a single code.   
**birthsex** — required when this extension is included.   
Code| Meaning  
---|---  
`M`| Male  
`F`| Female  
`OTH`| Other  
`UNK`| Unknown  
**sex**   
Code| Meaning  
---|---  
`184115007`| Patient sex unknown  
`248152002`| Female  
`248153007`| Male  
`33791000087105`| Identifies as nonbinary gender  
`asked-declined`| Asked but declined  
**sexual-orientation**   
Code| Meaning  
---|---  
`20430005`| Straight or heterosexual  
`38628009`| Lesbian, gay or homosexual  
`42035005`| Bisexual  
`OTH`| Something else, please describe  
`UNK`| Don't know  
`ASKU`| Choose not to disclose  
**tz-code** — any valid timezone code from the [FHIR timezone ValueSet](http://build.fhir.org/valueset-timezones.html), e.g., `America/New_York`.
valueString
string
Used by free-text extensions:   
  - **clinical-note** — displayed under the patient's name on the clinical chart. - **administrative-note** — displayed under the patient's name on the administrative profile.
valueId
string
Used by the **business-line** extension. The value is the `externallyExposableId` of the business line in Canvas.
valueCodeableConcept
json
Used by the **genderIdentity** extension. When this extension is provided, it overrides the root `gender` field.
Click to view child attributes
coding
array[json] required
Exactly one coding entry is allowed.
Click to view child attributes
system
string required
**Value Options Supported:**
  - http://snomed.info/sct
  - http://terminology.hl7.org/CodeSystem/v3-NullFlavor
code
string required
Gender identity code.
**Value Options Supported:**
  - 446151000124109 (Identifies as male gender)
  - 446141000124107 (Identifies as female gender)
  - 407377005 (Female-to-male transsexual)
  - 407376001 (Male-to-female transsexual)
  - 446131000124102 (Identifies as non-conforming gender)
  - OTH (Other)
  - ASKU (Asked but unknown)
display
string
Representation defined by the system.
text
string
valueReference
json
Used by **patient-default-provider** (must reference a Practitioner) and **patient-default-location** (must reference a Location). Both set the default used for eligibility checks.
Click to view child attributes
reference
string required
Reference string in the form `Practitioner/{id}` or `Location/{id}`.
type
string
Resource type the reference points to.
**Value Options Supported:**
  - Practitioner
  - Location
extension
array[json]
Used by compound extensions whose value is itself a list of extensions. The shape of each inner entry depends on the outer `url`:   
**us-core-race** / **us-core-ethnicity** — one or more inner extensions with `url`: `ombCategory`, `detailed`, or `text`. For `ombCategory` / `detailed`, provide a `valueCoding`. For `text`, provide a `valueString`.   
**us-core-tribal-affiliation** — exactly one inner extension with `url`: `tribalAffiliation` and a `valueCodeableConcept` containing one or more codings (each requires `system`, `code`, and `display`).   
**preferred-pharmacy** — one inner extension with `url`: `ncpdp-id` is **required** ; the NCPDP number goes in `valueIdentifier.value` (must be exactly **7 digits** , left-padded with zeros). Optional inner extensions: `default` (boolean — at most one preferred pharmacy per patient may be set to `true`), `name`, `phone-number`, `address`, `fax-number`, `specialty_type` (each `valueString`).
Click to view child attributes
url
string required
Identifies the inner extension. See the parent description above for which value applies to which compound extension.
**Value Options Supported:**
  - ombCategory (race / ethnicity — coded category (with valueCoding).)
  - detailed (race / ethnicity — detailed coded value (with valueCoding).)
  - text (race / ethnicity — free-text representation (with valueString).)
  - tribalAffiliation (tribal-affiliation — wraps the codings (with valueCodeableConcept).)
  - ncpdp-id (preferred-pharmacy — required. Pharmacy NCPDP id (with valueIdentifier).)
  - default (preferred-pharmacy — marks this pharmacy as the default (with valueBoolean).)
  - name (preferred-pharmacy — pharmacy name (with valueString).)
  - phone-number (preferred-pharmacy — pharmacy phone number (with valueString).)
  - address (preferred-pharmacy — pharmacy address (with valueString).)
  - fax-number (preferred-pharmacy — pharmacy fax (with valueString).)
  - specialty_type (preferred-pharmacy — pharmacy specialty (with valueString).)
valueCoding
json
For race / ethnicity `ombCategory` and `detailed` inner extensions.
Click to view child attributes
system
string required
For known race / ethnicity codes use the OID; for `ASKU` use the v3-NullFlavor system.
**Value Options Supported:**
  - urn:oid:2.16.840.1.113883.6.238
  - http://terminology.hl7.org/CodeSystem/v3-NullFlavor
code
string required
Race or ethnicity code from the [CDC Race and Ethnicity CodeSystem](https://hl7.org/fhir/us/core/STU3.1.1/CodeSystem-cdcrec.html). Example race codes — `2131-1` (Other Race), `2106-3` (White). Example ethnicity codes — `2186-5` (Not Hispanic or Latino), `2135-2` (Hispanic or Latino).
display
string
valueCodeableConcept
json
For the **tribal-affiliation** inner extension. Contains a `coding` list with at least one entry; each coding requires `system`, `code`, and `display`.
Click to view child attributes
coding
array[json] required
Click to view child attributes
system
string required
Typically `http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS`.
code
string required
display
string required
valueIdentifier
json
For the **preferred-pharmacy** `ncpdp-id` inner extension.
Click to view child attributes
value
string required
NCPDP identifier — must be **exactly 7 digits** , left-padded with zeros if needed.
system
string required
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber
valueBoolean
boolean
For the **preferred-pharmacy** `default` inner extension. At most one preferred-pharmacy entry per patient may be set to true.
valueString
string
Used in two contexts:   
• For the **race** / **ethnicity** `text` inner extension — a free-text representation of the race or ethnicity.   
• For the **preferred-pharmacy** metadata inner extensions (`name`, `phone-number`, `address`, `fax-number`, `specialty_type`) — free-text values about the pharmacy.
identifier
array[json]
External identifiers for this patient. None of these identifiers are surfaced on the patient chart, but they may help you correlate the Canvas patient with records in your own systems.
The MRN is managed by Canvas — do not modify it.   
**Replace semantics:** Each entry returned via Search/Read includes an `id`. Include the `id` to preserve or modify an existing identifier; omit `id` to add a new one. An identifier already in Canvas that is **not** included in the update message will be deleted only if its `period.end` is in the future.
Click to view child attributes
id
string
Canvas-issued identifier for this entry. Include on update to target an existing identifier; omit to create a new one.
use
enum [ usual | official | temp | secondary | old ]
Purpose of this identifier. Defaults to **usual** if omitted.
system
string required
Free-text namespace for the value (e.g., "HealthCo", or a URL).
value
string required
The identifier value. Must be 1–255 characters.
period
json
Validity window for this identifier. End-before-start is not validated.
Click to view child attributes
start
date
Inclusive start date (YYYY-MM-DD). Defaults to **1970-01-01** if omitted.
end
date
Inclusive end date (YYYY-MM-DD). Defaults to **2100-12-31** if omitted.
active
boolean
Whether the patient is active in the healthcare system. Defaults to `true` if omitted on create.
name
array[json] required
One or more names for the patient. At least one entry is required, and exactly one entry must have `use`: **official** — that entry determines the patient's first/middle/last/prefix/suffix shown across the Canvas UI.   
Additional entries with `use`: **nickname** , **maiden** , or **old** are accepted: the first item in the `given` list of a **nickname** entry is stored as the patient's preferred name. **maiden** and **old** entries are stored but not displayed in the Canvas UI. Entries with any other `use` value are ignored.   
In the Canvas UI, patients display as `first last suffix (nickname)`, and search supports first, middle, last, suffix, and nickname.
**Replace semantics:** Names are not addressed by `id` — the `name` array sent in the update replaces the names stored in Canvas (subject to the use-based rules above). To preserve a previously stored name, include it in the update body.
Click to view child attributes
use
enum [ official | nickname | old | maiden ] required
At least one entry with `use`: **official** is required. See the parent description for how each accepted value is handled.
family
string required
Family name (often called 'Surname'). Required on the **official** entry to populate the patient's last name.
given
array[string] required
Given names. The first item populates the patient's first name; remaining items are joined with a space and stored as the middle name.   
For a **nickname** entry, only the first item is read and stored as the patient's preferred name. Surrounding whitespace is trimmed, and a value that is empty or whitespace-only is stored as an empty preferred name.
prefix
array[string]
Parts that come before the name (e.g., "Dr.", "Mr."). Stored but not displayed in the Canvas UI.
suffix
array[string]
Parts that come after the name (e.g., "Jr.", "III"). Surfaced in the Canvas UI.
period
json
Validity window for this name.
Click to view child attributes
start
date
Inclusive start date (YYYY-MM-DD).
end
date
Inclusive end date (YYYY-MM-DD).
telecom
array[json]
Patient contact points (phone / email / fax / etc.).   
Phone and email entries are surfaced in the Canvas UI. Other systems are accepted and stored but are not displayed.
**Replace semantics:** Each entry returned via Search/Read includes an `id`. Include the `id` to preserve or modify an existing contact point; omit `id` to add a new one. A contact point not included in the update message will be deleted.
Click to view child attributes
id
string
Canvas-issued identifier for this contact point. Include on update to target an existing entry; omit to create a new one.
extension
array[json]
Optional flags about the contact point. The `has-consent` extension records that the patient has consented to receive messages at this contact point — set the `url` to **http://schemas.canvasmedical.com/fhir/extensions/has-consent** with `valueBoolean: true`.   
**Note:** Setting `has-consent` here does not send a verification email or text as the Canvas UI does — it bypasses verification and marks the contact point as verified.
Click to view child attributes
url
string required
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/has-consent
valueBoolean
boolean required
system
enum [ phone | fax | email | pager | url | sms | other ] required
Telecommunications form. `url` is stored internally as **other** , and `sms` is stored as **phone**.
value
string required
The contact point value (phone number, email address, etc.).
use
enum [ home | work | temp | old | mobile ]
Purpose of this contact point. Defaults to **home** if omitted.
rank
integer
Preferred order across contact points of the same `system`. Defaults to **1**.
gender
enum [ male | female | other | unknown ] required
Maps to the gender identity field in the Canvas UI. See the [administrative gender ValueSet](https://hl7.org/fhir/R4/valueset-administrative-gender.html).   
**unknown** displays as "choose not to disclose" on the patient chart. **other** displays as "Additional gender category or other, please specify".   
**Note:** If the `genderIdentity` extension is also provided, it overrides this field.
birthDate
date required
Patient's date of birth, formatted **YYYY-MM-DD**.   
Canvas also accepts partial dates: **YYYY-MM** defaults to the 1st of the month, and **YYYY** defaults to January 1st.
deceasedDateTime
datetime
Date/time the patient died. Mutually exclusive with `deceasedBoolean` — provide one or the other.
deceasedBoolean
boolean
Whether the patient is deceased. Use when an exact date/time isn't known.
Setting this to `false` clears the stored datetime of death; setting to `true` does not modify a previously stored datetime of death.
address
array[json]
Address(es) for the patient.
**Replace semantics:** Each entry returned via Search/Read includes an `id`. Include the `id` to preserve or modify an existing address; omit `id` to add a new one. An address not included in the update message will be deleted.
Click to view child attributes
id
string
Canvas-issued identifier for this address.
use
enum [ home | work | temp | old ]
Defaults to **home** if omitted.
type
enum [ both | physical | postal ]
Defaults to **both** if omitted.
line
array[string]
First item populates address line 1; remaining items are concatenated as address line 2.
city
string
City of the address.
state
string
2-letter state abbreviation.
postalCode
string
5-digit postal code.
country
string
ISO 3166 2-letter country code. Defaults to **us**.
period
json
Validity window for this address.
Click to view child attributes
start
date
Inclusive start date.
end
date
Inclusive end date.
photo
array[json]
Patient photo. Displayed as the avatar in the Canvas UI. Omit the block when not supplying a photo.
Click to view child attributes
data
string
Base64-encoded image content. Use on create or update to upload a photo. Do not send a `photo` entry with null `data`.
contact
array[json]
Contact parties (e.g., guardian, partner, friend, emergency contact) for the patient. Contact details display on the Patient profile page in the Canvas UI.
**Replace semantics:** Each entry returned via Search/Read includes an `id`. Include the `id` to preserve or modify an existing contact; omit `id` to add a new one. A contact not included in the update message will be deleted.
Click to view child attributes
id
string
Canvas-issued identifier for this contact. Include on update to target an existing contact; omit to create a new one.
relationship
array[json]
Codings describing the relationship of the contact to the patient. Codings can come from the standard `v3-RoleCode` system or from your instance's [configurable contact categories](https://help.canvasmedical.com/articles/8258338559-contact-categories), including the built-in **Emergency contact** category (`code`: `EMC`). Multiple codings can be combined on a single relationship to capture, e.g., both a familial relationship (`SPS` = spouse) and a contact-category role (`EMC` = emergency contact).
Click to view child attributes
coding
array[json]
Code(s) defined by a terminology system.
Click to view child attributes
system
string required
The system URL of the coding. Use **http://terminology.hl7.org/CodeSystem/v3-RoleCode** for relationship-type codings from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html), or **http://schemas.canvasmedical.com/fhir/contact-category** for Canvas's configurable contact categories.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-RoleCode
  - http://schemas.canvasmedical.com/fhir/contact-category
code
string required
The code of the relationship or contact category.   
For the `v3-RoleCode` system, values come from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html).   
For the `contact-category` system, values are the codes configured under [Contact Categories](https://help.canvasmedical.com/articles/8258338559-contact-categories) on your instance — for example, `EMC` (Emergency contact), `ARI` (Authorized for release of information), `POA` (Power of attorney).
display
string
Human-readable name of the coding.
name
json required
A name for the contact.   
Canvas only stores `name.text`. The structured sub-fields (`family`, `given`, `prefix`, `suffix`) are populated on read **only when the contact is itself a Canvas patient** , and are derived from that patient's record — they are not accepted on create or update.
Click to view child attributes
text
string required
Free-text representation of the contact's full name. The only name field stored for a non-patient contact.
telecom
array[json]
Contact points for this contact.   
Canvas stores at most one phone and one email per contact: the **first** entry with `system`: **phone** is stored as the contact's phone number, and the **first** entry with `system`: **email** is stored as the email. Entries with any other `system` value are ignored.
Click to view child attributes
system
enum [ phone | fax | email | pager | url | sms | other ] required
Only `phone` and `email` are stored on the contact; other values are ignored.
value
string required
The contact point value.   
For `system: phone`, the value must be **exactly 10 digits** with no other characters (no dashes, spaces, or country code). Phone values that don't match are rejected.
use
enum [ home | work | temp | old | mobile ]
Purpose of this contact point.
communication
array[json]
Languages used to communicate with the patient.
Click to view child attributes
language
json
A language usable for communicating with the patient. See [Common Languages](https://hl7.org/fhir/R4/valueset-languages.html) (preferred) or [AllLanguages](https://hl7.org/fhir/R4/valueset-all-languages.html).
Click to view child attributes
coding
array[json]
Exactly one coding entry is allowed.
Click to view child attributes
system
string required
**Value Options Supported:**
  - urn:ietf:bcp:47
  - http://hl7.org/fhir/ValueSet/all-languages
code
string required
BCP-47 language code (e.g., `en`).
display
string required
Human-readable language name (e.g., `English`).
text
string
Plain-text representation of the language.
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Patient
#### Patient search
Search for patient resources.
### Query Parameters
****
_has:CareTeam:participant:member
string
Search for patients based on references from other resources using the FHIR reverse-chaining syntax. Currently supported for CareTeam, e.g. `_has:CareTeam:participant:member=Practitioner/{practitioner_id}`.
_id
string
A Canvas-issued unique identifier for the patient. This can be found in the URL of the patient's chart.
_revinclude
string
Standard FHIR `_revinclude` parameter.
_sort
string
Sort the results by a specific field. Supported values are **_id** , **birthdate** , **family** , and **given**. Prefix with **-** (e.g., **-birthdate**) to sort in descending order.
active
boolean
By default, both active and inactive patients are returned. Use this parameter to return only active (`true`) or only inactive (`false`) patients.
birthdate
date
The patient's birth date.
email
string
Patient email address.
family
string
Last name.
gender
enum [ male | female | other | unknown ]
The gender of the patient.
given
string
First name.
identifier
string
The Canvas-issued MRN or a saved identifier from an external system.   
**Examples:**  
`/Patient?identifier=abc123` — patients with an identifier of "abc123" issued by any system, including Canvas-issued MRNs.  
`/Patient?identifier=foo|abc123` — patients with an identifier of "abc123" issued by the system named "foo".  
`/Patient?identifier=http://canvasmedical.com|012345` — the patient with the Canvas-issued MRN of "012345".  
`/Patient?identifier=foo|` — all patients with an identifier issued by the system named "foo".  
`/Patient?identifier=|abc123` — patients with an identifier of "abc123" issued by the system named "" (empty string).
name
string
Part of a first or last name.
nickname
string
Preferred or alternate name.
phone
string
Patient phone number. Expected to be 10 digits.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
Canvas-issued unique identifier (UUID) for this Patient. It is the same id that appears in the URL of the patient's chart.
text
json
A human-readable narrative summarizing the resource. Generated by Canvas; not accepted on create or update.
extension
array[json]
Canvas-supported FHIR extensions on this resource. Each entry has a `url` identifying the extension, plus either a `valueX` field or — for compound extensions (**race** , **ethnicity** , **tribal-affiliation** , **preferred-pharmacy**) — a nested `extension` array carrying the value. The `url` is matched as an exact string.   
The **birthsex** extension (`http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex`) is **required** on create and update.
Click to view child attributes
url
string
Identifies the extension. See the value-field descriptions below for which `url` pairs with which `valueX` (or nested `extension`) shape.
**Value Options Supported:**
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex (Required. Patient's sex assigned at birth, per ONC; aligns with the C-CDA Birth Sex Observation (LOINC 76689-9).)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex (Documented sex, distinct from sex at birth.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity (Gender the patient identifies as. Overrides the root gender field when provided.)
  - http://schemas.canvasmedical.com/fhir/extensions/sexual-orientation (Patient's sexual orientation.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-race (Patient's races. Compound — uses nested extension.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity (Patient's ethnicities. Compound — uses nested extension.)
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation (Tribe or band the patient associates with. Compound — uses nested extension.)
  - http://hl7.org/fhir/StructureDefinition/tz-code (Patient's timezone.)
  - http://schemas.canvasmedical.com/fhir/extensions/clinical-note (Free-text note shown under the patient's name on the clinical chart.)
  - http://schemas.canvasmedical.com/fhir/extensions/administrative-note (Free-text note shown under the patient's name on the administrative profile.)
  - http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy (Patient's preferred pharmacy. Compound — multiple allowed; one may be marked default.)
  - http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider (Default Practitioner used for eligibility checks.)
  - http://schemas.canvasmedical.com/fhir/extensions/patient-default-location (Default Location used for eligibility checks.)
  - http://schemas.canvasmedical.com/fhir/extensions/business-line (Business line the patient belongs to. Requires Business Line functionality on the instance.)
valueCode
string
Used by extensions whose value is a single code.   
**birthsex** — required when this extension is included.   
Code| Meaning  
---|---  
`M`| Male  
`F`| Female  
`OTH`| Other  
`UNK`| Unknown  
**sex**   
Code| Meaning  
---|---  
`184115007`| Patient sex unknown  
`248152002`| Female  
`248153007`| Male  
`33791000087105`| Identifies as nonbinary gender  
`asked-declined`| Asked but declined  
**sexual-orientation**   
Code| Meaning  
---|---  
`20430005`| Straight or heterosexual  
`38628009`| Lesbian, gay or homosexual  
`42035005`| Bisexual  
`OTH`| Something else, please describe  
`UNK`| Don't know  
`ASKU`| Choose not to disclose  
**tz-code** — any valid timezone code from the [FHIR timezone ValueSet](http://build.fhir.org/valueset-timezones.html), e.g., `America/New_York`.
valueString
string
Used by free-text extensions:   
  - **clinical-note** — displayed under the patient's name on the clinical chart. - **administrative-note** — displayed under the patient's name on the administrative profile.
valueId
string
Used by the **business-line** extension. The value is the `externallyExposableId` of the business line in Canvas.
valueCodeableConcept
json
Used by the **genderIdentity** extension. When this extension is provided, it overrides the root `gender` field.
Click to view child attributes
coding
array[json]
Exactly one coding entry is allowed.
Click to view child attributes
system
string
**Value Options Supported:**
  - http://snomed.info/sct
  - http://terminology.hl7.org/CodeSystem/v3-NullFlavor
code
string
Gender identity code.
**Value Options Supported:**
  - 446151000124109 (Identifies as male gender)
  - 446141000124107 (Identifies as female gender)
  - 407377005 (Female-to-male transsexual)
  - 407376001 (Male-to-female transsexual)
  - 446131000124102 (Identifies as non-conforming gender)
  - OTH (Other)
  - ASKU (Asked but unknown)
display
string
Representation defined by the system.
text
string
valueReference
json
Used by **patient-default-provider** (must reference a Practitioner) and **patient-default-location** (must reference a Location). Both set the default used for eligibility checks.
Click to view child attributes
reference
string
Reference string in the form `Practitioner/{id}` or `Location/{id}`.
type
string
Resource type the reference points to.
**Value Options Supported:**
  - Practitioner
  - Location
extension
array[json]
Used by compound extensions whose value is itself a list of extensions. The shape of each inner entry depends on the outer `url`:   
**us-core-race** / **us-core-ethnicity** — one or more inner extensions with `url`: `ombCategory`, `detailed`, or `text`. For `ombCategory` / `detailed`, provide a `valueCoding`. For `text`, provide a `valueString`.   
**us-core-tribal-affiliation** — exactly one inner extension with `url`: `tribalAffiliation` and a `valueCodeableConcept` containing one or more codings (each requires `system`, `code`, and `display`).   
**preferred-pharmacy** — one inner extension with `url`: `ncpdp-id` is **required** ; the NCPDP number goes in `valueIdentifier.value` (must be exactly **7 digits** , left-padded with zeros). Optional inner extensions: `default` (boolean — at most one preferred pharmacy per patient may be set to `true`), `name`, `phone-number`, `address`, `fax-number`, `specialty_type` (each `valueString`).
Click to view child attributes
url
string
Identifies the inner extension. See the parent description above for which value applies to which compound extension.
**Value Options Supported:**
  - ombCategory (race / ethnicity — coded category (with valueCoding).)
  - detailed (race / ethnicity — detailed coded value (with valueCoding).)
  - text (race / ethnicity — free-text representation (with valueString).)
  - tribalAffiliation (tribal-affiliation — wraps the codings (with valueCodeableConcept).)
  - ncpdp-id (preferred-pharmacy — required. Pharmacy NCPDP id (with valueIdentifier).)
  - default (preferred-pharmacy — marks this pharmacy as the default (with valueBoolean).)
  - name (preferred-pharmacy — pharmacy name (with valueString).)
  - phone-number (preferred-pharmacy — pharmacy phone number (with valueString).)
  - address (preferred-pharmacy — pharmacy address (with valueString).)
  - fax-number (preferred-pharmacy — pharmacy fax (with valueString).)
  - specialty_type (preferred-pharmacy — pharmacy specialty (with valueString).)
valueCoding
json
For race / ethnicity `ombCategory` and `detailed` inner extensions.
Click to view child attributes
system
string
For known race / ethnicity codes use the OID; for `ASKU` use the v3-NullFlavor system.
**Value Options Supported:**
  - urn:oid:2.16.840.1.113883.6.238
  - http://terminology.hl7.org/CodeSystem/v3-NullFlavor
code
string
Race or ethnicity code from the [CDC Race and Ethnicity CodeSystem](https://hl7.org/fhir/us/core/STU3.1.1/CodeSystem-cdcrec.html). Example race codes — `2131-1` (Other Race), `2106-3` (White). Example ethnicity codes — `2186-5` (Not Hispanic or Latino), `2135-2` (Hispanic or Latino).
display
string
valueCodeableConcept
json
For the **tribal-affiliation** inner extension. Contains a `coding` list with at least one entry; each coding requires `system`, `code`, and `display`.
Click to view child attributes
coding
array[json]
Click to view child attributes
system
string
Typically `http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS`.
code
string
display
string
valueIdentifier
json
For the **preferred-pharmacy** `ncpdp-id` inner extension.
Click to view child attributes
value
string
NCPDP identifier — must be **exactly 7 digits** , left-padded with zeros if needed.
system
string
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber
valueBoolean
boolean
For the **preferred-pharmacy** `default` inner extension. At most one preferred-pharmacy entry per patient may be set to true.
valueString
string
Used in two contexts:   
• For the **race** / **ethnicity** `text` inner extension — a free-text representation of the race or ethnicity.   
• For the **preferred-pharmacy** metadata inner extensions (`name`, `phone-number`, `address`, `fax-number`, `specialty_type`) — free-text values about the pharmacy.
identifier
array[json]
External identifiers for this patient. None of these identifiers are surfaced on the patient chart, but they may help you correlate the Canvas patient with records in your own systems.
The array always includes the Canvas-issued MRN (an entry with `system`: **http://canvasmedical.com** and a coded `type` of MR). Additional entries are external identifiers added through prior create/update calls or via the Patient profile in the Canvas UI.
Click to view child attributes
id
string
Canvas-issued identifier for this entry. Include on update to target an existing identifier; omit to create a new one.
use
enum [ usual | official | temp | secondary | old ]
Purpose of this identifier. Defaults to **usual** if omitted.
system
string
Free-text namespace for the value (e.g., "HealthCo", or a URL).
value
string
The identifier value. Must be 1–255 characters.
period
json
Validity window for this identifier. End-before-start is not validated.
Click to view child attributes
start
date
Inclusive start date (YYYY-MM-DD). Defaults to **1970-01-01** if omitted.
end
date
Inclusive end date (YYYY-MM-DD). Defaults to **2100-12-31** if omitted.
type
json
Codeable concept identifying the kind of identifier.
assigner
json
Organization that issued id.
active
boolean
Whether the patient is active in the healthcare system. Defaults to `true` if omitted on create.
name
array[json]
One or more names for the patient. At least one entry is required, and exactly one entry must have `use`: **official** — that entry determines the patient's first/middle/last/prefix/suffix shown across the Canvas UI.   
Additional entries with `use`: **nickname** , **maiden** , or **old** are accepted: the first item in the `given` list of a **nickname** entry is stored as the patient's preferred name. **maiden** and **old** entries are stored but not displayed in the Canvas UI. Entries with any other `use` value are ignored.   
In the Canvas UI, patients display as `first last suffix (nickname)`, and search supports first, middle, last, suffix, and nickname.
Click to view child attributes
use
enum [ official | nickname | old | maiden ]
At least one entry with `use`: **official** is required. See the parent description for how each accepted value is handled.
family
string
Family name (often called 'Surname'). Required on the **official** entry to populate the patient's last name.
given
array[string]
Given names. The first item populates the patient's first name; remaining items are joined with a space and stored as the middle name.   
For a **nickname** entry, only the first item is read and stored as the patient's preferred name. Surrounding whitespace is trimmed, and a value that is empty or whitespace-only is stored as an empty preferred name.
prefix
array[string]
Parts that come before the name (e.g., "Dr.", "Mr."). Stored but not displayed in the Canvas UI.
suffix
array[string]
Parts that come after the name (e.g., "Jr.", "III"). Surfaced in the Canvas UI.
period
json
Validity window for this name.
Click to view child attributes
start
date
Inclusive start date (YYYY-MM-DD).
end
date
Inclusive end date (YYYY-MM-DD).
telecom
array[json]
Patient contact points (phone / email / fax / etc.).   
Phone and email entries are surfaced in the Canvas UI. Other systems are accepted and stored but are not displayed.
Click to view child attributes
id
string
Canvas-issued identifier for this contact point. Include on update to target an existing entry; omit to create a new one.
extension
array[json]
Optional flags about the contact point. The `has-consent` extension records that the patient has consented to receive messages at this contact point — set the `url` to **http://schemas.canvasmedical.com/fhir/extensions/has-consent** with `valueBoolean: true`.   
**Note:** Setting `has-consent` here does not send a verification email or text as the Canvas UI does — it bypasses verification and marks the contact point as verified.
Click to view child attributes
url
string
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/has-consent
valueBoolean
boolean
system
enum [ phone | fax | email | pager | url | sms | other ]
Telecommunications form. `url` is stored internally as **other** , and `sms` is stored as **phone**.
value
string
The contact point value (phone number, email address, etc.).
use
enum [ home | work | temp | old | mobile ]
Purpose of this contact point. Defaults to **home** if omitted.
rank
integer
Preferred order across contact points of the same `system`. Defaults to **1**.
gender
enum [ male | female | other | unknown ]
Maps to the gender identity field in the Canvas UI. See the [administrative gender ValueSet](https://hl7.org/fhir/R4/valueset-administrative-gender.html).   
**unknown** displays as "choose not to disclose" on the patient chart. **other** displays as "Additional gender category or other, please specify".   
**Note:** If the `genderIdentity` extension is also provided, it overrides this field.
birthDate
date
Patient's date of birth, formatted **YYYY-MM-DD**.   
Canvas also accepts partial dates: **YYYY-MM** defaults to the 1st of the month, and **YYYY** defaults to January 1st.
deceasedDateTime
datetime
Date/time the patient died. Mutually exclusive with `deceasedBoolean` — provide one or the other.
Returned in place of `deceasedBoolean` when an exact datetime is on file.
deceasedBoolean
boolean
Whether the patient is deceased. Use when an exact date/time isn't known.
Returned in place of `deceasedDateTime` when no exact datetime is on file.
address
array[json]
Address(es) for the patient.
Click to view child attributes
id
string
Canvas-issued identifier for this address.
use
enum [ home | work | temp | old ]
Defaults to **home** if omitted.
type
enum [ both | physical | postal ]
Defaults to **both** if omitted.
line
array[string]
First item populates address line 1; remaining items are concatenated as address line 2.
city
string
City of the address.
state
string
2-letter state abbreviation.
postalCode
string
5-digit postal code.
country
string
ISO 3166 2-letter country code. Defaults to **us**.
period
json
Validity window for this address.
Click to view child attributes
start
date
Inclusive start date.
end
date
Inclusive end date.
photo
array[json]
Patient photo. Displayed as the avatar in the Canvas UI. Omit the block when not supplying a photo.
Click to view child attributes
url
string
URI where the image can be retrieved. Returned on read/search; requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files).
contact
array[json]
Contact parties (e.g., guardian, partner, friend, emergency contact) for the patient. Contact details display on the Patient profile page in the Canvas UI.
Click to view child attributes
id
string
Canvas-issued identifier for this contact. Include on update to target an existing contact; omit to create a new one.
relationship
array[json]
Codings describing the relationship of the contact to the patient. Codings can come from the standard `v3-RoleCode` system or from your instance's [configurable contact categories](https://help.canvasmedical.com/articles/8258338559-contact-categories), including the built-in **Emergency contact** category (`code`: `EMC`). Multiple codings can be combined on a single relationship to capture, e.g., both a familial relationship (`SPS` = spouse) and a contact-category role (`EMC` = emergency contact).
Click to view child attributes
coding
array[json]
Code(s) defined by a terminology system.
Click to view child attributes
system
string
The system URL of the coding. Use **http://terminology.hl7.org/CodeSystem/v3-RoleCode** for relationship-type codings from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html), or **http://schemas.canvasmedical.com/fhir/contact-category** for Canvas's configurable contact categories.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-RoleCode
  - http://schemas.canvasmedical.com/fhir/contact-category
code
string
The code of the relationship or contact category.   
For the `v3-RoleCode` system, values come from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html).   
For the `contact-category` system, values are the codes configured under [Contact Categories](https://help.canvasmedical.com/articles/8258338559-contact-categories) on your instance — for example, `EMC` (Emergency contact), `ARI` (Authorized for release of information), `POA` (Power of attorney).
display
string
Human-readable name of the coding.
name
json
A name for the contact.   
Canvas only stores `name.text`. The structured sub-fields (`family`, `given`, `prefix`, `suffix`) are populated on read **only when the contact is itself a Canvas patient** , and are derived from that patient's record — they are not accepted on create or update.
Click to view child attributes
text
string
Free-text representation of the contact's full name. The only name field stored for a non-patient contact.
family
string
Family name. Populated on read only when the contact is a Canvas patient; derived from that patient's record.
given
array[string]
Given names. Populated on read only when the contact is a Canvas patient.
prefix
array[string]
Parts that come before the name. Populated on read only when the contact is a Canvas patient.
suffix
array[string]
Parts that come after the name. Populated on read only when the contact is a Canvas patient.
telecom
array[json]
Contact points for this contact.   
Canvas stores at most one phone and one email per contact: the **first** entry with `system`: **phone** is stored as the contact's phone number, and the **first** entry with `system`: **email** is stored as the email. Entries with any other `system` value are ignored.
Click to view child attributes
system
enum [ phone | fax | email | pager | url | sms | other ]
Only `phone` and `email` are stored on the contact; other values are ignored.
value
string
The contact point value.   
For `system: phone`, the value must be **exactly 10 digits** with no other characters (no dashes, spaces, or country code). Phone values that don't match are rejected.
use
enum [ home | work | temp | old | mobile ]
Purpose of this contact point.
address
json
Address where the contact can be reached. Populated on read only when the contact is itself a Canvas patient (the contact's primary address is surfaced); ignored on create and update.
Click to view child attributes
use
enum [ home | work | temp | old ]
type
enum [ both | physical | postal ]
line
array[string]
First item is address line 1; remaining items are concatenated as address line 2.
city
string
district
string
District name (aka county).
state
string
2-letter state abbreviation.
postalCode
string
5-digit postal code.
country
string
ISO 3166 2-letter country code.
period
json
Click to view child attributes
start
date
end
date
communication
array[json]
Languages used to communicate with the patient.
Click to view child attributes
language
json
A language usable for communicating with the patient. See [Common Languages](https://hl7.org/fhir/R4/valueset-languages.html) (preferred) or [AllLanguages](https://hl7.org/fhir/R4/valueset-all-languages.html).
Click to view child attributes
coding
array[json]
Exactly one coding entry is allowed.
Click to view child attributes
system
string
**Value Options Supported:**
  - urn:ietf:bcp:47
  - http://hl7.org/fhir/ValueSet/all-languages
code
string
BCP-47 language code (e.g., `en`).
display
string
Human-readable language name (e.g., `English`).
text
string
Plain-text representation of the language.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```sh
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Patient' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Patient",
            "extension":
            [
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                    "valueCode": "F"
                },
                {
                    "url" : "http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex",
                    "valueCode" : "248152002"
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity",
                    "valueCodeableConcept":
                    {
                        "coding":
                        [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "446141000124107",
                                "display": "Identifies as female gender (finding)"
                            }
                        ],
                        "text": "Identifies as female gender (finding)"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/sexual-orientation",
                    "valueCode": "20430005"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy",
                    "extension":
                    [
                        {
                            "url": "ncpdp-id",
                            "valueIdentifier":
                            {
                                "value": "1123152",
                                "system": "http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber"
                            }
                        }
                    ]
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider",
                    "valueReference": {
                        "reference": "Practitioner/55096fbcdfb240fd8c999c325304de03",
                        "type": "Practitioner"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location"
                    }
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "code": "2131-1",
                                "system": "urn:oid:2.16.840.1.113883.6.238"
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "code": "2186-5",
                                "system": "urn:oid:2.16.840.1.113883.6.238"
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation",
                    "extension":
                    [
                        {
                            "url": "tribalAffiliation",
                            "valueCodeableConcept":
                            {
                                "coding":
                                [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS",
                                        "code": "187",
                                        "display": "Paiute-Shoshone Tribe of the Fallon Reservation and Colony, Nevada"
                                    }
                                ]
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/StructureDefinition/tz-code",
                    "valueCode": "America/New_York"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/clinical-note",
                    "valueString": "I am a clinical caption from a Create message"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/administrative-note",
                    "valueString": "I am an administrative caption from a Create message"
                }
            ],
            "identifier":
            [
                {
                    "use": "usual",
                    "system": "HealthCo",
                    "value": "s07960990"
                }
            ],
            "active": true,
            "name":
            [
                {
                    "use": "official",
                    "family": "Jones",
                    "given":
                    [
                        "Samantha",
                        "Ann"
                    ],
                    "prefix": [
                        "Dr."
                    ],
                    "suffix": [
                        "Jr."
                    ]
                },
                {
                    "use": "nickname",
                    "given":
                    [
                        "Sammy"
                    ]
                }
            ],
            "telecom":
            [
                {
                    "system": "phone",
                    "value": "5554320555",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                }
            ],
            "gender": "female",
            "birthDate": "1980-11-13",
            "address":
            [
                {
                    "use": "home",
                    "type": "both",
                    "text": "1234 Main St., Los Angeles, CA 94107",
                    "line":
                    [
                        "1234 Main St."
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107"
                }
            ],
            "photo":
            [
                {
                    "data": "R0lGODlhEwARAPcAAAAAAAAA/+9aAO+1AP/WAP/eAP/eCP/eEP/eGP/nAP/nCP/nEP/nIf/nKf/nUv/nWv/vAP/vCP/vEP/vGP/vIf/vKf/vMf/vOf/vWv/vY//va//vjP/3c//3lP/3nP//tf//vf///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////yH5BAEAAAEALAAAAAATABEAAAi+AAMIDDCgYMGBCBMSvMCQ4QCFCQcwDBGCA4cLDyEGECDxAoAQHjxwyKhQAMeGIUOSJJjRpIAGDS5wCDly4AALFlYOgHlBwwOSNydM0AmzwYGjBi8IHWoTgQYORg8QIGDAwAKhESI8HIDgwQaRDI1WXXAhK9MBBzZ8/XDxQoUFZC9IiCBh6wEHGz6IbNuwQoSpWxEgyLCXL8O/gAnylNlW6AUEBRIL7Og3KwQIiCXb9HsZQoIEUzUjNEiaNMKAAAA7"
                }
            ],
            "contact":
            [
                {
                    "name":
                    {
                        "text": "Dan Jones"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "SPS",
                                    "display": "spouse"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "ARI",
                                    "display": "Authorized for release of information"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "POA",
                                    "display": "Power of attorney"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "EMC",
                                    "display": "Emergency contact"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "danjones@example.com"
                        }
                    ]
                },
                {
                    "name":
                    {
                        "text": "Linda Stewart"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "MTH",
                                    "display": "mother"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "phone",
                            "value": "5557327068"
                        }
                    ]
                },
                {
                    "name":
                    {
                        "text": "Jimmy Stewart"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "FTH",
                                    "display": "father"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "j.stewart@example.com"
                        }
                    ]
                }
            ],
            "communication":
            [
                {
                    "language":
                    {
                        "coding":
                        [
                            {
                                "system": "urn:ietf:bcp:47",
                                "code": "en",
                                "display": "English"
                            }
                        ],
                        "text": "English"
                    }
                }
            ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Patient"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Patient",
            "extension":
            [
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                    "valueCode": "F"
                },
                {
                    "url" : "http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex",
                    "valueCode" : "248152002"
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity",
                    "valueCodeableConcept":
                    {
                        "coding":
                        [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "446141000124107",
                                "display": "Identifies as female gender (finding)"
                            }
                        ],
                        "text": "Identifies as female gender (finding)"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/sexual-orientation",
                    "valueCode": "20430005"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy",
                    "extension":
                    [
                        {
                            "url": "ncpdp-id",
                            "valueIdentifier":
                            {
                                "value": "1123152",
                                "system": "http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber"
                            }
                        }
                    ]
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider",
                    "valueReference": {
                        "reference": "Practitioner/55096fbcdfb240fd8c999c325304de03",
                        "type": "Practitioner"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location"
                    }
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "code": "2131-1",
                                "system": "urn:oid:2.16.840.1.113883.6.238"
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "code": "2186-5",
                                "system": "urn:oid:2.16.840.1.113883.6.238"
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation",
                    "extension":
                    [
                        {
                            "url": "tribalAffiliation",
                            "valueCodeableConcept":
                            {
                                "coding":
                                [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS",
                                        "code": "187",
                                        "display": "Paiute-Shoshone Tribe of the Fallon Reservation and Colony, Nevada"
                                    }
                                ]
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/StructureDefinition/tz-code",
                    "valueCode": "America/New_York"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/clinical-note",
                    "valueString": "I am a clinical caption from a Create message"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/administrative-note",
                    "valueString": "I am an administrative caption from a Create message"
                }
            ],
            "identifier":
            [
                {
                    "use": "usual",
                    "system": "HealthCo",
                    "value": "s07960990"
                }
            ],
            "active": True,
            "name":
            [
                {
                    "use": "official",
                    "family": "Jones",
                    "given":
                    [
                        "Samantha",
                        "Ann"
                    ]
                },
                {
                    "use": "nickname",
                    "given":
                    [
                        "Sammy"
                    ]
                }
            ],
            "telecom":
            [
                {
                    "system": "phone",
                    "value": "5554320555",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                }
            ],
            "gender": "female",
            "birthDate": "1980-11-13",
            "address":
            [
                {
                    "use": "home",
                    "type": "both",
                    "text": "1234 Main St., Los Angeles, CA 94107",
                    "line":
                    [
                        "1234 Main St."
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107"
                }
            ],
            "photo":
            [
                {
                    "data": "R0lGODlhEwARAPcAAAAAAAAA/+9aAO+1AP/WAP/eAP/eCP/eEP/eGP/nAP/nCP/nEP/nIf/nKf/nUv/nWv/vAP/vCP/vEP/vGP/vIf/vKf/vMf/vOf/vWv/vY//va//vjP/3c//3lP/3nP//tf//vf///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////yH5BAEAAAEALAAAAAATABEAAAi+AAMIDDCgYMGBCBMSvMCQ4QCFCQcwDBGCA4cLDyEGECDxAoAQHjxwyKhQAMeGIUOSJJjRpIAGDS5wCDly4AALFlYOgHlBwwOSNydM0AmzwYGjBi8IHWoTgQYORg8QIGDAwAKhESI8HIDgwQaRDI1WXXAhK9MBBzZ8/XDxQoUFZC9IiCBh6wEHGz6IbNuwQoSpWxEgyLCXL8O/gAnylNlW6AUEBRIL7Og3KwQIiCXb9HsZQoIEUzUjNEiaNMKAAAA7"
                }
            ],
            "contact":
            [
                {
                    "name":
                    {
                        "text": "Dan Jones"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "SPS",
                                    "display": "spouse"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "ARI",
                                    "display": "Authorized for release of information"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "POA",
                                    "display": "Power of attorney"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "EMC",
                                    "display": "Emergency contact"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "danjones@example.com"
                        }
                    ]
                },
                {
                    "name":
                    {
                        "text": "Linda Stewart"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "MTH",
                                    "display": "mother"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "phone",
                            "value": "5557327068"
                        }
                    ]
                },
                {
                    "name":
                    {
                        "text": "Jimmy Stewart"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "FTH",
                                    "display": "father"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "j.stewart@example.com"
                        }
                    ]
                }
            ],
            "communication":
            [
                {
                    "language":
                    {
                        "coding":
                        [
                            {
                                "system": "urn:ietf:bcp:47",
                                "code": "en",
                                "display": "English"
                            }
                        ],
                        "text": "English"
                    }
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Patient/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Patient/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Patient",
            "id": "7162fd82487e4dc8aa2581ddbca91892",
            "text":
            {
                "status": "generated",
                "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><div class=\"hapiHeaderText\">Samantha<b>Jones</b></div><table class=\"hapiPropertyTable\"><tbody><tr><td>Identifier</td><td>963277285</td></tr><tr><td>Date of birth</td><td><span>1980-11-13</span></td></tr></tbody></table></div>"
            },
            "extension":
            [
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                    "valueCode": "F"
                },
                {
                    "url" : "http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex",
                    "valueCode" : "248152002"
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity",
                    "valueCodeableConcept":
                    {
                        "coding":
                        [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "446141000124107",
                                "display": "Identifies as female gender (finding)"
                            }
                        ],
                        "text": "Identifies as female gender (finding)"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/sexual-orientation",
                    "valueCode": "20430005"
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "system": "urn:oid:2.16.840.1.113883.6.238",
                                "code": "2131-1",
                                "display": "Other Race"
                            }
                        },
                        {
                            "url": "text",
                            "valueString": "Other Race"
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "system": "urn:oid:2.16.840.1.113883.6.238",
                                "code": "2186-5",
                                "display": "Not Hispanic or Latino"
                            }
                        },
                        {
                            "url": "text",
                            "valueString": "Not Hispanic or Latino"
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation",
                    "extension":
                    [
                        {
                            "url": "tribalAffiliation",
                            "valueCodeableConcept":
                            {
                                "coding":
                                [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS",
                                        "code": "187",
                                        "display": "Paiute-Shoshone Tribe of the Fallon Reservation and Colony, Nevada"
                                    }
                                ]
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/StructureDefinition/tz-code",
                    "valueCode": "America/New_York"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/clinical-note",
                    "valueString": "I am a clinical caption from a Create message"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/administrative-note",
                    "valueString": "I am an administrative caption from a Create message"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy",
                    "extension":
                    [
                        {
                            "url": "ncpdp-id",
                            "valueIdentifier":
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber",
                                "value": "1123152"
                            }
                        },
                        {
                            "url": "specialty_type",
                            "valueString": "Retail"
                        },
                        {
                            "url": "default",
                            "valueBoolean": false
                        }
                    ]
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider",
                    "valueReference": {
                        "reference": "Practitioner/55096fbcdfb240fd8c999c325304de03",
                        "type": "Practitioner",
                        "display": "Steven Magee"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location",
                        "display": "Canvas Clinic San Francisco"
                    }
                }
            ],
            "identifier":
            [
                {
                    "use": "usual",
                    "type":
                    {
                        "coding":
                        [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                "code": "MR"
                            }
                        ]
                    },
                    "system": "http://canvasmedical.com",
                    "value": "963277285",
                    "assigner":
                    {
                        "display": "Canvas Medical"
                    }
                },
                {
                    "id": "1e628d77-5cdd-400f-a239-b24929d4a0aa",
                    "use": "usual",
                    "system": "HealthCo",
                    "value": "s07960990",
                    "period":
                    {
                        "start": "1970-01-01",
                        "end": "2100-12-31"
                    }
                }
            ],
            "active": true,
            "name":
            [
                {
                    "use": "official",
                    "family": "Jones",
                    "given":
                    [
                        "Samantha",
                        "Ann"
                    ],
                    "period":
                    {
                        "start": "0001-01-01T00:00:00+00:00",
                        "end": "9999-12-31T23:59:59.999999+00:00"
                    }
                },
                {
                    "use": "nickname",
                    "given":
                    [
                        "Sammy"
                    ],
                    "period":
                    {
                        "start": "0001-01-01T00:00:00+00:00",
                        "end": "9999-12-31T23:59:59.999999+00:00"
                    }
                }
            ],
            "telecom":
            [
                {
                    "id": "aa0d6ad0-0b69-4740-9c8c-759c769a63d1",
                    "extension":
                    [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/has-consent",
                            "valueBoolean": false
                        }
                    ],
                    "system": "phone",
                    "value": "5554320555",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "id": "49c0c29d-c56e-41bb-89ab-79562bb75afc",
                    "extension":
                    [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/has-consent",
                            "valueBoolean": false
                        }
                    ],
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                }
            ],
            "gender": "female",
            "birthDate": "1980-11-13",
            "deceasedBoolean": false,
            "address":
            [
                {
                    "id": "611aaf01-a515-4d55-b43d-88b8735359f7",
                    "use": "home",
                    "type": "both",
                    "line":
                    [
                        "1234 Main St."
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107",
                    "country": "United States"
                }
            ],
            "photo":
            [
                {
                    "url": "https://fumage-example.canvasmedical.com/Patient/7162fd82487e4dc8aa2581ddbca91892/files/photo"
                }
            ],
            "contact":
            [
                {
                    "id": "1ba81cb4-7f97-429d-b0d8-4c4f067b11a5",
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "SPS",
                                    "display": "spouse"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "ARI",
                                    "display": "Authorized for release of information"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "POA",
                                    "display": "Power of attorney"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "EMC",
                                    "display": "Emergency contact"
                                }
                            ]
                        }
                    ],
                    "name":
                    {
                        "text": "Dan Jones"
                    },
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "danjones@example.com"
                        }
                    ]
                },
                {
                    "id": "f259a2b0-6bae-479b-8efe-f9436046cfb3",
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "MTH",
                                    "display": "mother"
                                }
                            ]
                        }
                    ],
                    "name":
                    {
                        "text": "Linda Stewart"
                    },
                    "telecom":
                    [
                        {
                            "system": "phone",
                            "value": "5557327068"
                        }
                    ]
                },
                {
                    "id": "30639a10-18c2-4222-8d26-32b2ca36a1bb",
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "FTH",
                                    "display": "father"
                                }
                            ]
                        }
                    ],
                    "name":
                    {
                        "text": "Jimmy Stewart"
                    },
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "j.stewart@example.com"
                        }
                    ]
                }
            ],
            "communication":
            [
                {
                    "language":
                    {
                        "coding":
                        [
                            {
                                "system": "urn:ietf:bcp:47",
                                "code": "en",
                                "display": "English"
                            }
                        ],
                        "text": "English"
                    }
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Patient resource 'a47c7b0ebbb442cdbc4adf259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```sh
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/Patient/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Patient",
            "extension":
            [
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                    "valueCode": "F"
                },
                {
                    "url" : "http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex",
                    "valueCode" : "248152002"
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity",
                    "valueCodeableConcept":
                    {
                        "coding":
                        [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "446141000124107",
                                "display": "Identifies as female gender (finding)"
                            }
                        ],
                        "text": "Identifies as female gender (finding)"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/sexual-orientation",
                    "valueCode": "20430005"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy",
                    "extension":
                    [
                        {
                            "url": "ncpdp-id",
                            "valueIdentifier":
                            {
                                "value": "1123152",
                                "system": "http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber"
                            }
                        }
                    ]
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider",
                    "valueReference": {
                        "reference": "Practitioner/55096fbcdfb240fd8c999c325304de03",
                        "type": "Practitioner"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location"
                    }
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "code": "2131-1",
                                "system": "urn:oid:2.16.840.1.113883.6.238"
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "code": "2186-5",
                                "system": "urn:oid:2.16.840.1.113883.6.238"
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation",
                    "extension":
                    [
                        {
                            "url": "tribalAffiliation",
                            "valueCodeableConcept":
                            {
                                "coding":
                                [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS",
                                        "code": "187",
                                        "display": "Paiute-Shoshone Tribe of the Fallon Reservation and Colony, Nevada"
                                    }
                                ]
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/StructureDefinition/tz-code",
                    "valueCode": "America/New_York"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/clinical-note",
                    "valueString": "Prefers to be called Sammy"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/administrative-note",
                    "valueString": "I am an administrative caption from a Create message"
                }
            ],
            "identifier":
            [
                {
                    "use": "usual",
                    "system": "HealthCo",
                    "value": "s07960990"
                }
            ],
            "active": true,
            "name":
            [
                {
                    "use": "official",
                    "family": "Jones",
                    "given":
                    [
                        "Samantha",
                        "Ann"
                    ],
                    "prefix": [
                        "Dr."
                    ],
                    "suffix": [
                        "Jr."
                    ]
                },
                {
                    "use": "nickname",
                    "given":
                    [
                        "Sammy"
                    ]
                }
            ],
            "telecom":
            [
                {
                    "system": "phone",
                    "value": "5554320555",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                }
            ],
            "gender": "female",
            "birthDate": "1980-11-13",
            "address":
            [
                {
                    "use": "home",
                    "type": "both",
                    "text": "1234 Main St., Los Angeles, CA 94107",
                    "line":
                    [
                        "1234 Main St."
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107"
                }
            ],
            "photo":
            [
                {
                    "data": "R0lGODlhEwARAPcAAAAAAAAA/+9aAO+1AP/WAP/eAP/eCP/eEP/eGP/nAP/nCP/nEP/nIf/nKf/nUv/nWv/vAP/vCP/vEP/vGP/vIf/vKf/vMf/vOf/vWv/vY//va//vjP/3c//3lP/3nP//tf//vf///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////yH5BAEAAAEALAAAAAATABEAAAi+AAMIDDCgYMGBCBMSvMCQ4QCFCQcwDBGCA4cLDyEGECDxAoAQHjxwyKhQAMeGIUOSJJjRpIAGDS5wCDly4AALFlYOgHlBwwOSNydM0AmzwYGjBi8IHWoTgQYORg8QIGDAwAKhESI8HIDgwQaRDI1WXXAhK9MBBzZ8/XDxQoUFZC9IiCBh6wEHGz6IbNuwQoSpWxEgyLCXL8O/gAnylNlW6AUEBRIL7Og3KwQIiCXb9HsZQoIEUzUjNEiaNMKAAAA7"
                }
            ],
            "contact":
            [
                {
                    "id": "1ba81cb4-7f97-429d-b0d8-4c4f067b11a5",
                    "name":
                    {
                        "text": "Dan Jones"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "SPS",
                                    "display": "spouse"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "ARI",
                                    "display": "Authorized for release of information"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "POA",
                                    "display": "Power of attorney"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "EMC",
                                    "display": "Emergency contact"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "danjones@example.com"
                        }
                    ]
                },
                {
                    "id": "f259a2b0-6bae-479b-8efe-f9436046cfb3",
                    "name":
                    {
                        "text": "Linda Stewart"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "MTH",
                                    "display": "mother"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "phone",
                            "value": "5557327068"
                        }
                    ]
                },
                {
                    "id": "30639a10-18c2-4222-8d26-32b2ca36a1bb",
                    "name":
                    {
                        "text": "Jimmy Stewart"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "FTH",
                                    "display": "father"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "j.stewart@example.com"
                        }
                    ]
                }
            ],
            "communication":
            [
                {
                    "language":
                    {
                        "coding":
                        [
                            {
                                "system": "urn:ietf:bcp:47",
                                "code": "en",
                                "display": "English"
                            }
                        ],
                        "text": "English"
                    }
                }
            ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Patient/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Patient",
            "extension":
            [
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                    "valueCode": "F"
                },
                {
                    "url" : "http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex",
                    "valueCode" : "248152002"
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity",
                    "valueCodeableConcept":
                    {
                        "coding":
                        [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "446141000124107",
                                "display": "Identifies as female gender (finding)"
                            }
                        ],
                        "text": "Identifies as female gender (finding)"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy",
                    "extension":
                    [
                        {
                            "url": "ncpdp-id",
                            "valueIdentifier":
                            {
                                "value": "1123152",
                                "system": "http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber"
                            }
                        }
                    ]
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider",
                    "valueReference": {
                        "reference": "Practitioner/55096fbcdfb240fd8c999c325304de03",
                        "type": "Practitioner"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location"
                    }
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "code": "2131-1",
                                "system": "urn:oid:2.16.840.1.113883.6.238"
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
                    "extension":
                    [
                        {
                            "url": "ombCategory",
                            "valueCoding":
                            {
                                "code": "2186-5",
                                "system": "urn:oid:2.16.840.1.113883.6.238"
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation",
                    "extension":
                    [
                        {
                            "url": "tribalAffiliation",
                            "valueCodeableConcept":
                            {
                                "coding":
                                [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS",
                                        "code": "187",
                                        "display": "Paiute-Shoshone Tribe of the Fallon Reservation and Colony, Nevada"
                                    }
                                ]
                            }
                        }
                    ]
                },
                {
                    "url": "http://hl7.org/fhir/StructureDefinition/tz-code",
                    "valueCode": "America/New_York"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/clinical-note",
                    "valueString": "Prefers to be called Sammy"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/administrative-note",
                    "valueString": "I am an administrative caption from a Create message"
                }
            ],
            "identifier":
            [
                {
                    "use": "usual",
                    "system": "HealthCo",
                    "value": "s07960990"
                }
            ],
            "active": True,
            "name":
            [
                {
                    "use": "official",
                    "family": "Jones",
                    "given":
                    [
                        "Samantha",
                        "Ann"
                    ],
                    "prefix": [
                        "Dr."
                    ],
                    "suffix": [
                        "Jr."
                    ]
                },
                {
                    "use": "nickname",
                    "given":
                    [
                        "Sammy"
                    ]
                }
            ],
            "telecom":
            [
                {
                    "system": "phone",
                    "value": "5554320555",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                }
            ],
            "gender": "female",
            "birthDate": "1980-11-13",
            "address":
            [
                {
                    "use": "home",
                    "type": "both",
                    "text": "1234 Main St., Los Angeles, CA 94107",
                    "line":
                    [
                        "1234 Main St."
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107"
                }
            ],
            "photo":
            [
                {
                    "data": "R0lGODlhEwARAPcAAAAAAAAA/+9aAO+1AP/WAP/eAP/eCP/eEP/eGP/nAP/nCP/nEP/nIf/nKf/nUv/nWv/vAP/vCP/vEP/vGP/vIf/vKf/vMf/vOf/vWv/vY//va//vjP/3c//3lP/3nP//tf//vf///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////yH5BAEAAAEALAAAAAATABEAAAi+AAMIDDCgYMGBCBMSvMCQ4QCFCQcwDBGCA4cLDyEGECDxAoAQHjxwyKhQAMeGIUOSJJjRpIAGDS5wCDly4AALFlYOgHlBwwOSNydM0AmzwYGjBi8IHWoTgQYORg8QIGDAwAKhESI8HIDgwQaRDI1WXXAhK9MBBzZ8/XDxQoUFZC9IiCBh6wEHGz6IbNuwQoSpWxEgyLCXL8O/gAnylNlW6AUEBRIL7Og3KwQIiCXb9HsZQoIEUzUjNEiaNMKAAAA7"
                }
            ],
            "contact":
            [
                {
                    "id": "1ba81cb4-7f97-429d-b0d8-4c4f067b11a5",
                    "name":
                    {
                        "text": "Dan Jones"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "SPS",
                                    "display": "spouse"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "ARI",
                                    "display": "Authorized for release of information"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "POA",
                                    "display": "Power of attorney"
                                },
                                {
                                    "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                    "code": "EMC",
                                    "display": "Emergency contact"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "danjones@example.com"
                        }
                    ]
                },
                {
                    "id": "f259a2b0-6bae-479b-8efe-f9436046cfb3",
                    "name":
                    {
                        "text": "Linda Stewart"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "MTH",
                                    "display": "mother"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "phone",
                            "value": "5557327068"
                        }
                    ]
                },
                {
                    "id": "30639a10-18c2-4222-8d26-32b2ca36a1bb",
                    "name":
                    {
                        "text": "Jimmy Stewart"
                    },
                    "relationship":
                    [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                    "code": "FTH",
                                    "display": "father"
                                }
                            ]
                        }
                    ],
                    "telecom":
                    [
                        {
                            "system": "email",
                            "value": "j.stewart@example.com"
                        }
                    ]
                }
            ],
            "communication":
            [
                {
                    "language":
                    {
                        "coding":
                        [
                            {
                                "system": "urn:ietf:bcp:47",
                                "code": "en",
                                "display": "English"
                            }
                        ],
                        "text": "English"
                    }
                }
            ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Patient resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Patient?family=Jones&gender=female' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Patient?family=Jones&gender=female"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link":
            [
                {
                    "relation": "self",
                    "url": "/Patient?family=Jones&gender=female&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Patient?family=Jones&gender=female&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Patient?family=Jones&gender=female&_count=10&_offset=0"
                }
            ],
            "entry":
            [
                {
                    "resource":
                    {
                        "resourceType": "Patient",
                        "id": "7162fd82487e4dc8aa2581ddbca91892",
                        "text":
                        {
                            "status": "generated",
                            "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><div class=\"hapiHeaderText\">Samantha<b>Jones</b></div><table class=\"hapiPropertyTable\"><tbody><tr><td>Identifier</td><td>963277285</td></tr><tr><td>Date of birth</td><td><span>1980-11-13</span></td></tr></tbody></table></div>"
                        },
                        "extension":
                        [
                            {
                                "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                                "valueCode": "F"
                            },
                            {
                                "url" : "http://hl7.org/fhir/us/core/StructureDefinition/us-core-sex",
                                "valueCode" : "248152002"
                            },
                            {
                                "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-genderIdentity",
                                "valueCodeableConcept":
                                {
                                    "coding":
                                    [
                                        {
                                            "system": "http://snomed.info/sct",
                                            "code": "446141000124107",
                                            "display": "Identifies as female gender (finding)"
                                        }
                                    ],
                                    "text": "Identifies as female gender (finding)"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/sexual-orientation",
                                "valueCode": "20430005"
                            },
                            {
                                "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
                                "extension":
                                [
                                    {
                                        "url": "ombCategory",
                                        "valueCoding":
                                        {
                                            "system": "urn:oid:2.16.840.1.113883.6.238",
                                            "code": "2131-1",
                                            "display": "Other Race"
                                        }
                                    },
                                    {
                                        "url": "text",
                                        "valueString": "Other Race"
                                    }
                                ]
                            },
                            {
                                "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
                                "extension":
                                [
                                    {
                                        "url": "ombCategory",
                                        "valueCoding":
                                        {
                                            "system": "urn:oid:2.16.840.1.113883.6.238",
                                            "code": "2186-5",
                                            "display": "Not Hispanic or Latino"
                                        }
                                    },
                                    {
                                        "url": "text",
                                        "valueString": "Not Hispanic or Latino"
                                    }
                                ]
                            },
                            {
                                "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation",
                                "extension":
                                [
                                    {
                                        "url": "tribalAffiliation",
                                        "valueCodeableConcept":
                                        {
                                            "coding":
                                            [
                                                {
                                                    "system": "http://terminology.hl7.org/CodeSystem/v3-TribalEntityUS",
                                                    "code": "187",
                                                    "display": "Paiute-Shoshone Tribe of the Fallon Reservation and Colony, Nevada"
                                                }
                                            ]
                                        }
                                    }
                                ]
                            },
                            {
                                "url": "http://hl7.org/fhir/StructureDefinition/tz-code",
                                "valueCode": "America/New_York"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/clinical-note",
                                "valueString": "I am a clinical caption from a Create message"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/administrative-note",
                                "valueString": "I am an administrative caption from a Create message"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/preferred-pharmacy",
                                "extension":
                                [
                                    {
                                        "url": "ncpdp-id",
                                        "valueIdentifier":
                                        {
                                            "system": "http://terminology.hl7.org/CodeSystem/NCPDPProviderIdentificationNumber",
                                            "value": "1123152"
                                        }
                                    },
                                    {
                                        "url": "specialty_type",
                                        "valueString": "Retail"
                                    },
                                    {
                                        "url": "default",
                                        "valueBoolean": false
                                    }
                                ]
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-provider",
                                "valueReference": {
                                    "reference": "Practitioner/55096fbcdfb240fd8c999c325304de03",
                                    "type": "Practitioner",
                                    "display": "Steven Magee"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/patient-default-location",
                                "valueReference": {
                                    "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                                    "type": "Location",
                                    "display": "Canvas Clinic San Francisco"
                                }
                            }
                        ],
                        "identifier":
                        [
                            {
                                "use": "usual",
                                "type":
                                {
                                    "coding":
                                    [
                                        {
                                            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                            "code": "MR"
                                        }
                                    ]
                                },
                                "system": "http://canvasmedical.com",
                                "value": "963277285",
                                "assigner":
                                {
                                    "display": "Canvas Medical"
                                }
                            },
                            {
                                "id": "1e628d77-5cdd-400f-a239-b24929d4a0aa",
                                "use": "usual",
                                "system": "HealthCo",
                                "value": "s07960990",
                                "period":
                                {
                                    "start": "1970-01-01",
                                    "end": "2100-12-31"
                                }
                            }
                        ],
                        "active": true,
                        "name":
                        [
                            {
                                "use": "official",
                                "family": "Jones",
                                "given":
                                [
                                    "Samantha",
                                    "Ann"
                                ],
                                "period":
                                {
                                    "start": "0001-01-01T00:00:00+00:00",
                                    "end": "9999-12-31T23:59:59.999999+00:00"
                                }
                            },
                            {
                                "use": "nickname",
                                "given":
                                [
                                    "Sammy"
                                ],
                                "period":
                                {
                                    "start": "0001-01-01T00:00:00+00:00",
                                    "end": "9999-12-31T23:59:59.999999+00:00"
                                }
                            }
                        ],
                        "telecom":
                        [
                            {
                                "id": "aa0d6ad0-0b69-4740-9c8c-759c769a63d1",
                                "extension":
                                [
                                    {
                                        "url": "http://schemas.canvasmedical.com/fhir/extensions/has-consent",
                                        "valueBoolean": false
                                    }
                                ],
                                "system": "phone",
                                "value": "5554320555",
                                "use": "mobile",
                                "rank": 1
                            },
                            {
                                "id": "49c0c29d-c56e-41bb-89ab-79562bb75afc",
                                "extension":
                                [
                                    {
                                        "url": "http://schemas.canvasmedical.com/fhir/extensions/has-consent",
                                        "valueBoolean": false
                                    }
                                ],
                                "system": "email",
                                "value": "samantha.jones@example.com",
                                "use": "work",
                                "rank": 1
                            }
                        ],
                        "gender": "female",
                        "birthDate": "1980-11-13",
                        "deceasedBoolean": false,
                        "address":
                        [
                            {
                                "id": "611aaf01-a515-4d55-b43d-88b8735359f7",
                                "use": "home",
                                "type": "both",
                                "line":
                                [
                                    "1234 Main St."
                                ],
                                "city": "Los Angeles",
                                "state": "CA",
                                "postalCode": "94107",
                                "country": "United States"
                            }
                        ],
                        "contact":
                        [
                            {
                                "id": "1ba81cb4-7f97-429d-b0d8-4c4f067b11a5",
                                "relationship":
                                [
                                    {
                                        "coding": [
                                            {
                                                "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                                "code": "SPS",
                                                "display": "spouse"
                                            },
                                            {
                                                "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                                "code": "ARI",
                                                "display": "Authorized for release of information"
                                            },
                                            {
                                                "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                                "code": "POA",
                                                "display": "Power of attorney"
                                            },
                                            {
                                                "system": "http://schemas.canvasmedical.com/fhir/contact-category",
                                                "code": "EMC",
                                                "display": "Emergency contact"
                                            }
                                        ]
                                    }
                                ],
                                "name":
                                {
                                    "text": "Dan Jones"
                                },
                                "telecom":
                                [
                                    {
                                        "system": "email",
                                        "value": "danjones@example.com"
                                    }
                                ]
                            },
                            {
                                "id": "f259a2b0-6bae-479b-8efe-f9436046cfb3",
                                "relationship":
                                [
                                    {
                                        "coding": [
                                            {
                                                "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                                "code": "MTH",
                                                "display": "mother"
                                            }
                                        ]
                                    }
                                ],
                                "name":
                                {
                                    "text": "Linda Stewart"
                                },
                                "telecom":
                                [
                                    {
                                        "system": "phone",
                                        "value": "5557327068"
                                    }
                                ]
                            },
                            {
                                "id": "30639a10-18c2-4222-8d26-32b2ca36a1bb",
                                "relationship":
                                [
                                    {
                                        "coding": [
                                            {
                                                "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                                "code": "FTH",
                                                "display": "father"
                                            }
                                        ]
                                    }
                                ],
                                "name":
                                {
                                    "text": "Jimmy Stewart"
                                },
                                "telecom":
                                [
                                    {
                                        "system": "email",
                                        "value": "j.stewart@example.com"
                                    }
                                ]
                            }
                        ],
                        "communication":
                        [
                            {
                                "language":
                                {
                                    "coding":
                                    [
                                        {
                                            "system": "urn:ietf:bcp:47",
                                            "code": "en",
                                            "display": "English"
                                        }
                                    ],
                                    "text": "English"
                                }
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# PaymentNotice

Source: https://docs.canvasmedical.com/api/paymentnotice/

### 
This resource provides the status of the payment for goods and services rendered, and the request and response resource references.  
<https://hl7.org/fhir/R4/paymentnotice.html>  
In Canvas, FHIR PaymentNotice records payments made toward a patient's balance.  
See this [Zendesk article](https://canvas-medical.help.usepylon.com/articles/3813109228-collect-payment) for information about how to collect payments.
### Endpoints
post/PaymentNotice get/PaymentNotice/{id} get/PaymentNotice
post
/PaymentNotice
#### PaymentNotice create
Create a PaymentNotice resource.  
This endpoint can be used to note a payment that has been collected from a patient and deduct the amount from their balance.  
Moreover, this endpoint can be used to denote copayments as well. For that purpose, use the valueReference extension to link the associated Claim for which the copayment is being processed. Adding that extension determines the purpose of action for this endpoint, meaning that it would be treated as a copayment transaction if the Claim reference extension is present.  
**Don't overpay!** Requests that would bring the account balance negative will be rejected. Example: If a patient owes $5, Canvas would reject a PaymentNotice with a value that is greater than $5. Balance can only go negative if performing copayments as customers could be charged prior to recieveing a medical service.  
A created payment notice can be found in Canvas by going to the patient's chart, and clicking the paper icon in the top right corner. The created payment notice will be displayed under receipts. The "Originator" will be automatically set to Canvas Bot.  
As payment notices are created, they will be applied to charges in chronological order of creation date, from oldest to newest.
### Attributes
id
string
The identifier of the payment notice.
extension
array[json]
Specific FHIR extensions on resources are supported to be able to map some Canvas specific attributes. The copayment extensions contains references to claims used for copayments.
If you are not denoting a copayment, then use PaymentNotice without the copayment extension for other type of payments.
Click to view child attributes
url
string required
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/copayment-claims
extension
array[json]
Use this extension to denote and reference a Claim targeted for a copayment. For producing copayments, only a single Claim is accepted.
Click to view child attributes
url
string required
Identifies the meaning of the extension.
**Value Options Supported:**
  - claim
valueReference
json required
Click to view child attributes
reference
string required
The reference string of the [Claim](/api/claim) used for copayments in the format of `"Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9"`.
status
string required
The status of the resource instance.
**Value Options Supported:**
  - active
request
json required
A reference to the patient whose balance this payment is being applied to.
Click to view child attributes
reference
string required
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
datetime required
Required by the FHIR spec. Canvas recommends sending the current date on create; however, the value returned by the search interaction will be the creation timestamp of the actual database record in Canvas.
payment
json required
The `payment` field is required by FHIR, but is not used by Canvas.
Canvas recommends sending an empty JSON object.
recipient
json required
The `recipient` field is required by FHIR, but is not used by Canvas.
Canvas recommends sending an empty JSON object.
amount
json required
The payment amount.
Click to view child attributes
value
decimal
The amount of USD to apply to the patient's balance.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/PaymentNotice/{id}
#### PaymentNotice read
Read a PaymentNotice resource.
### Path Parameters
id required
string
The unique identifier for the PaymentNotice   
### Response Payload Attributes
id
string
The identifier of the payment notice.
extension
array[json]
Specific FHIR extensions on resources are supported to be able to map some Canvas specific attributes. The copayment extensions contains references to claims used for copayments.
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/copayment-claims
extension
array[json]
A nested extension that contains references to Claims related to copayments.
Click to view child attributes
url
string
Identifies the meaning of the extension.
**Value Options Supported:**
  - claim
valueReference
json
Click to view child attributes
reference
string
The reference string of the [Claim](/api/claim) used for copayments in the format of `"Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9"`.
status
string
The status of the resource instance.
**Value Options Supported:**
  - active
request
json
A reference to the patient whose balance this payment is being applied to.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
datetime
Required by the FHIR spec. Canvas recommends sending the current date on create; however, the value returned by the search interaction will be the creation timestamp of the actual database record in Canvas.
payment
json
The `payment` field is required by FHIR, but is not used by Canvas.
Click to view child attributes
display
Text alternative for the resource.
**Value Options Supported:**
  - unused
recipient
json
The `recipient` field is required by FHIR, but is not used by Canvas.
Click to view child attributes
display
Text alternative for the resource.
**Value Options Supported:**
  - unused
amount
json
The payment amount.
Click to view child attributes
value
decimal
The amount of USD to apply to the patient's balance.
currency
code
ISO 4217 Currency Code. Only **USD** is supported, and **USD** will be used regardless of what is provided.
**Value Options Supported:**
  - USD
paymentStatus
json
Issued or cleared Status of the payment.
Click to view child attributes
coding
array[json]
Code defined by a terminology system. There will be a single coding of **paid**.
Click to view child attributes
system
string
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/paymentstatus
code
string
In search responses, the code of **paid** will be noted.
**Value Options Supported:**
  - paid
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/PaymentNotice
#### PaymentNotice search
Search for PaymentNotice resources.
### Query Parameters
****
_id
string
The Canvas-issued unique identifier of the PaymentNotice
request
string
The patient reference associated with the PaymentNotice in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
id
string
The identifier of the payment notice.
extension
array[json]
Specific FHIR extensions on resources are supported to be able to map some Canvas specific attributes. The copayment extensions contains references to claims used for copayments.
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/copayment-claims
extension
array[json]
A nested extension that contains references to Claims related to copayments.
Click to view child attributes
url
string
Identifies the meaning of the extension.
**Value Options Supported:**
  - claim
valueReference
json
Click to view child attributes
reference
string
The reference string of the [Claim](/api/claim) used for copayments in the format of `"Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9"`.
status
string
The status of the resource instance.
**Value Options Supported:**
  - active
request
json
A reference to the patient whose balance this payment is being applied to.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
created
datetime
Required by the FHIR spec. Canvas recommends sending the current date on create; however, the value returned by the search interaction will be the creation timestamp of the actual database record in Canvas.
payment
json
The `payment` field is required by FHIR, but is not used by Canvas.
Click to view child attributes
display
Text alternative for the resource.
**Value Options Supported:**
  - unused
recipient
json
The `recipient` field is required by FHIR, but is not used by Canvas.
Click to view child attributes
display
Text alternative for the resource.
**Value Options Supported:**
  - unused
amount
json
The payment amount.
Click to view child attributes
value
decimal
The amount of USD to apply to the patient's balance.
currency
code
ISO 4217 Currency Code. Only **USD** is supported, and **USD** will be used regardless of what is provided.
**Value Options Supported:**
  - USD
paymentStatus
json
Issued or cleared Status of the payment.
Click to view child attributes
coding
array[json]
Code defined by a terminology system. There will be a single coding of **paid**.
Click to view child attributes
system
string
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/paymentstatus
code
string
In search responses, the code of **paid** will be noted.
**Value Options Supported:**
  - paid
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```sh
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/PaymentNotice' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "PaymentNotice",
            "extension": [
                {
                    "extension": [
                        {
                            "url": "claim",
                            "valueReference": {
                                "reference": "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9"
                            }
                        }
                    ],
                    "url": "http://schemas.canvasmedical.com/fhir/copayment-claims"
                }
            ],
            "status": "active",
            "request": {
                "reference": "Patient/bc4ec998a49745b488f552bebddf7261"
            },
            "created": "2023-09-12",
            "payment": {},
            "recipient": {},
            "amount": {
                "value": 10.00,
                "currency": "USD"
            }
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/PaymentNotice"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "PaymentNotice",
            "extension": [
                {
                    "extension": [
                        {
                            "url": "claim",
                            "valueReference": {
                                "reference": "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9"
                            }
                        }
                    ],
                    "url": "http://schemas.canvasmedical.com/fhir/copayment-claims"
                }
            ],
            "status": "active",
            "request": {
                "reference": "Patient/bc4ec998a49745b488f552bebddf7261"
            },
            "created": "2023-09-12",
            "payment": {},
            "recipient": {},
            "amount": {
                "value": 10.00,
                "currency": "USD"
            }
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/PaymentNotice/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/PaymentNotice/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "PaymentNotice",
            "id": "297e160c-8246-4054-8023-554d8e14c8c8",
            "extension": [
                {
                    "extension": [
                        {
                            "url": "claim",
                            "valueReference": {
                                "reference": "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9"
                            }
                        }
                    ],
                    "url": "http://schemas.canvasmedical.com/fhir/copayment-claims"
                }
            ],
            "status": "active",
            "request": {
                "reference": "Patient/3f688bb915d04e168dbfa635da4ab259",
                "type": "Patient"
            },
            "created": "2023-10-17T18:27:59.232743+00:00",
            "payment": {
                "display": "Unused"
            },
            "recipient": {
                "display": "Unused"
            },
            "amount": {
                "value": 25.0,
                "currency": "USD"
            },
            "paymentStatus": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/paymentstatus",
                        "code": "paid"
                    }
                ]
            }
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown PaymentNotice resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/PaymentNotice?request=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/PaymentNotice?request=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/PaymentNotice?request=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/PaymentNotice?request=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/PaymentNotice?request=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "PaymentNotice",
                        "id": "777094d2-664c-49b9-8926-b17a1b3fff8d",
                        "status": "active",
                        "request": {
                            "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                            "type": "Patient"
                        },
                        "created": "2023-09-13T01:10:49.515238+00:00",
                        "payment": {
                            "display": "Unused"
                        },
                        "recipient": {
                            "display": "Unused"
                        },
                        "amount": {
                            "value": 10.0,
                            "currency": "USD"
                        },
                        "paymentStatus": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/paymentstatus",
                                    "code": "paid"
                                }
                            ]
                        }
                    }
                },
                {
                    "resource": {
                        "resourceType": "PaymentNotice",
                        "id": "3a2f4045-0591-460c-9bee-592ae7e8eef7",
                        "extension": [
                            {
                                "extension": [
                                    {
                                        "url": "claim",
                                        "valueReference": {
                                            "reference": "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9"
                                        }
                                    }
                                ],
                                "url": "http://schemas.canvasmedical.com/fhir/copayment-claims"
                            }
                        ],
                        "status": "active",
                        "request": {
                            "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                            "type": "Patient"
                        },
                        "created": "2023-09-13T01:11:22.767640+00:00",
                        "payment": {
                            "display": "Unused"
                        },
                        "recipient": {
                            "display": "Unused"
                        },
                        "amount": {
                            "value": 10.0,
                            "currency": "USD"
                        },
                        "paymentStatus": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/paymentstatus",
                                    "code": "paid"
                                }
                            ]
                        }
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Practitioner Operations

Source: https://docs.canvasmedical.com/api/practitioner-operations/

##  send-reset-password-email 
Send reset password email to Practitioner by the given ID.  
This endpoint is a [FHIR operation](https://hl7.org/fhir/R4/operations.html), so it accepts a [Parameters](https://hl7.org/fhir/R4/parameters.html) resource in the request body. It doesn't accept any specific parameters but requires a payload that states the resource type. See the request example for more detail.
The bearer token included in requests send to this endpoint must have one of the following scopes:
  - `system/Practitioner.send-reset-password-email`
  - `user/Practitioner.send-reset-password-email`
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Practitioner/<id>/$send-reset-password-email' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Parameters"
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Practitioner/<id>/$send-reset-password-email"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Parameters"
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```

---

# Practitioner

Source: https://docs.canvasmedical.com/api/practitioner/

### 
A person who is directly or indirectly involved in the provisioning of healthcare.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitioner.html>  
To create a new staff member manually in the Canvas UI, see this [article](https://canvas-medical.help.usepylon.com/articles/4283873790-add-a-new-staff-member).  
#### Additional information
  - Search returns only schedulable practitioners unless `include-non-schedulable-practitioners` is `true`. A practitioner is schedulable when at least one of their roles is in the organization's `SCHEDULABLE_STAFF_ROLES` setting; a practitioner with no such role (for example, a Medical Assistant) is left out of search results regardless of `active` or any other parameter.
**Related guides:**
  - [Testing Pharmacy Workflows in a Staging Environment](/guides/pharmacy-staging-testing/)
### Endpoints
post/Practitioner get/Practitioner/{id} put/Practitioner/{id} get/Practitioner
post
/Practitioner
#### Practitioner create
Create Practitioner with provided fields and values.
### Attributes
id
string
Unique Canvas identifier for this resource.
extension
array[json]
Canvas supports specific FHIR extensions on this resource. In order to identify which extension maps to specific fields in Canvas, the url field is used as an exact string match.
Click to view child attributes
url
string required
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature
  - http://schemas.canvasmedical.com/fhir/extensions/roles
valueString
string
Value of extension.  
The `valueString` attribute is needed for the role's extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username`.   
A username is a unique and often personalized identifier that an individual or entity uses to access a computer system, online platform, or any other service that requires user authentication
valueUrl
string
Value of extension.  
The `valueUrl` attribute is needed for the meeting link extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link`. This value will represent the url that will be associated to any telehealth notes in Canvas.
valueReference
json
Value of extension.  
The `valueReference` attribute is needed for the primary location extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location`. This attribute will be the reference the practitioner's primary location they practice at.
Click to view child attributes
reference
string required
The reference string of the location in the format of `"Location/95b9ac2d-e963-4d7a-b165-7901870f1663"`.
type
string
Type the reference refers to (e.g. "Location").
valueAttachment
json
Value of extension.  
The `valueAttachment` attribute is needed for the signature extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature`. This attribute represents the attachment of the practitioner's real handwritten signature file.
Click to view child attributes
data
string required
A base64-encoded file.
extension
array[json]
For the Role extensions where the url is `http://schemas.canvasmedical.com/fhir/extensions/roles`, the `extension` attribute is used to define the list of role's this practitioner has at the practice.
Click to view child attributes
url
string
Identifies the meaning of the extension.
**Value Options Supported:**
  - code
valueCoding
json required
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/roles
code
string required
The internal code. Examples of expected values include RN, CA, MA, etc. Some of these values are built in to each Canvas instance but are customizable. See this [article](https://canvas-medical.help.usepylon.com/articles/6649603926-staff-roles) for more information.
display
string
The display name of the coding.
identifier
array[json]
A secondary identifier for the Practitioner. This is the NPI number of the Practitioner in Canvas.
Click to view child attributes
system
string
The `system` attribute specifies the namespace in which the identifier value is unique.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/us-npi
value
string
Practitioner's NPI number. Its value must be a 10 digit number.
active
boolean
A boolean to specify if the practitioner is active in the healthcare system. If this value is not set, Canvas will default this to true.
name
array[json] required
The name associated with the practitioner.
Click to view child attributes
use
enum [ usual ] required
The 'use' attribute specifies the context in which the name is used. For this API, the only permitted value is 'usual,' which indicates that the name provided is the name typically used to identify the practitioner in daily practice.
family
string required
Practitioner's last name.
given
array[string] required
Practitioner's first name. Only one first name is allowed.
telecom
array[json] required
Practitioner contact point(s) (email / phone / fax).   
At least one contact point with the specifications `system`: **phone** and `use`: **work** is required and it is designated as the primary phone for the Practitioner.   
There must be exactly one contact point with the specifications `system`: **email** and `rank`: **1**. An error will be triggered if there is more than one `email` with `rank` set to **1** , however, multiple emails with other ranks (e.g., rank 2, 3, 4, etc.) are allowed.
Click to view child attributes
system
enum [ phone | fax | email | pager | other ] required
Telecommunications form for contact point - what communications system is required to make use of the contact.
value
string required
The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address). Values for phone numbers (where "system" is set to "phone") must be only digits, with no sign characters or spaces.
use
enum [ home | work | temp | old | mobile ] required
Identifies the purpose for the contact point.
rank
integer required
Specifies a preferred order in which to use a set of contacts. ContactPoints with lower rank values are more preferred than those with higher rank values.
address
array[json]
Address(es) of the practitioner entered in Canvas. No default values will be set.
Click to view child attributes
use
enum [ home | work | temp | old | billing ] required
Defines the purpose of this address.
type
enum [ both | physical | postal ] required
Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses). Most addresses are both.
line
array[string]
This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.  
The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.
city
string
The name of the city, town, suburb, village or other community or delivery center.
state
string
Two-letter state abbreviation of the address.
postalCode
string
The 5-digit postal code of the address.
country
string
Specifies the country in which the practitioner's address is located. This field typically contains the name of the country, following the ISO 3166 standard.
birthDate
date required
The date on which the practitioner was born, formatted as YYYY-MM-DD.
photo
array[json]
Practitioner photo(s).
Click to view child attributes
url
string required
Uri where the data can be found.
title
string
Label to display in place of the data.
qualification
array[json]
Practitioner license(s)
Click to view child attributes
identifier
array[json] required
This component identifies the issuing authority of the Practitioner's qualification (license).
Click to view child attributes
system
string
The `system` attribute specifies the namespace in which the identifier value is unique.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url
value
string
The `value` attribute contains the actual identifier assigned to the practitioner's qualification. This value is unique within the context defined by the `system` attribute. It can be any string that serves as a meaningful identifier, such as a license number, certification ID, or other relevant qualification identifiers.
code
json
License type coding object. Specifies the type of license that practitioner holds.
Click to view child attributes
text
string
The license type code. This field specifies the type of license that practitioner holds.
**Value Options Supported:**
  - CLIA
  - DEA
  - PTAN
  - SPI
  - STATE
  - TAXONOMY
  - OTHER
period
json required
A component of the Practitioner's license that defines validity period of the license with starting and the ending dates.
Click to view child attributes
start
string
Start date of the Practitioner's license. Expected date format is YYYY-MM-DD (Example - "2020-01-01")
end
string
End date of the Practitioner's license. Expected date format is YYYY-MM-DD (Example - "2020-01-01")
issuer
json
A component of the Practitioner's license object that defines the license issuing authority short name.
Click to view child attributes
display
string
The display text of the license's short name.
extension
array[json]
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state
  - http://schemas.canvasmedical.com/fhir/extensions/license-primary
valueString
string
The string value for the extension. Used for issuing authority short name and state extensions.
valueBoolean
boolean
The boolean value for the extension. Used for the license-primary extension to indicate if this is the practitioner's primary license.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Practitioner/{id}
#### Practitioner read
Read a Practitioner resource
### Path Parameters
id required
string
The unique identifier for the Practitioner   
### Response Payload Attributes
id
string
Unique Canvas identifier for this resource.
extension
array[json]
Canvas supports specific FHIR extensions on this resource.
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature
  - http://schemas.canvasmedical.com/fhir/extensions/roles
valueString
string
Value of extension.  
The `valueString` attribute is needed for the role's extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username`.   
A username is a unique and often personalized identifier that an individual or entity uses to access a computer system, online platform, or any other service that requires user authentication
valueUrl
string
Value of extension.  
The `valueUrl` attribute is needed for the meeting link extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link`. This value will represent the url that will be associated to any telehealth notes in Canvas.
valueReference
json
Value of extension.  
The `valueReference` attribute is needed for the primary location extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location`. This attribute will be the reference the practitioner's primary location they practice at.
Click to view child attributes
reference
string
The reference string of the location in the format of `"Location/95b9ac2d-e963-4d7a-b165-7901870f1663"`.
type
string
Type the reference refers to (e.g. "Location").
valueAttachment
json
Value of extension.  
The `valueAttachment` attribute is needed for the signature extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature`. This attribute represents the attachment of the practitioner's real handwritten signature file.
Click to view child attributes
extension
json
Extension for backward-compatible URLs
url
string
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
extension
array[json]
For the Role extensions where the url is `http://schemas.canvasmedical.com/fhir/extensions/roles`, the `extension` attribute is used to define the list of role's this practitioner has at the practice.
Click to view child attributes
url
string
Identifies the meaning of the extension.
**Value Options Supported:**
  - code
valueCoding
json
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/roles
code
string
The internal code. Examples of expected values include RN, CA, MA, etc. Some of these values are built in to each Canvas instance but are customizable. See this [article](https://canvas-medical.help.usepylon.com/articles/6649603926-staff-roles) for more information.
display
string
The display name of the coding.
identifier
array[json]
A secondary identifier for the Practitioner. This is the NPI number of the Practitioner in Canvas.
Click to view child attributes
system
string
The `system` attribute specifies the namespace in which the identifier value is unique.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/us-npi
value
string
Practitioner's NPI number. Its value must be a 10 digit number.
active
boolean
A boolean to specify if the practitioner is active in the healthcare system. If this value is not set, Canvas will default this to true.
name
array[json]
The name associated with the practitioner.
Click to view child attributes
use
enum [ usual ]
The 'use' attribute specifies the context in which the name is used. For this API, the only permitted value is 'usual,' which indicates that the name provided is the name typically used to identify the practitioner in daily practice.
text
string
Text representation of the full name.
family
string
Practitioner's last name.
given
array[string]
Practitioner's first name. Only one first name is allowed.
prefix
array[string]
Parts that come before the name.
suffix
array[string]
Parts that come after the name.
telecom
array[json]
Practitioner contact point(s) (email / phone / fax).
Click to view child attributes
id
string
The identifier (ID) of the telecom (contact point) record in Canvas.
system
enum [ phone | fax | email | pager | other ]
Telecommunications form for contact point - what communications system is required to make use of the contact.
value
string
The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address).
use
enum [ home | work | temp | old | mobile ]
Identifies the purpose for the contact point.
rank
integer
Specifies a preferred order in which to use a set of contacts. ContactPoints with lower rank values are more preferred than those with higher rank values.
address
array[json]
Address(es) of the practitioner entered in Canvas. No default values will be set.
Click to view child attributes
id
string
The identifier (ID) of the address record in Canvas.
use
enum [ home | work | temp | old | billing ]
Defines the purpose of this address.
type
enum [ both | physical | postal ]
Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses). Most addresses are both.
line
array[string]
This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.  
The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.
city
string
The name of the city, town, suburb, village or other community or delivery center.
state
string
Two-letter state abbreviation of the address.
postalCode
string
The 5-digit postal code of the address.
country
string
Specifies the country in which the practitioner's address is located. This field typically contains the name of the country, following the ISO 3166 standard.
birthDate
date
The date on which the practitioner was born, formatted as YYYY-MM-DD.
photo
array[json]
Practitioner photo(s).
Click to view child attributes
url
string
Uri where the data can be found.
title
string
Label to display in place of the data.
qualification
array[json]
Practitioner license(s)
Click to view child attributes
identifier
array[json]
This component identifies the issuing authority of the Practitioner's qualification (license).
Click to view child attributes
system
string
The `system` attribute specifies the namespace in which the identifier value is unique.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url
value
string
The `value` attribute contains the actual identifier assigned to the practitioner's qualification. This value is unique within the context defined by the `system` attribute. It can be any string that serves as a meaningful identifier, such as a license number, certification ID, or other relevant qualification identifiers.
code
json
License type coding object. Specifies the type of license that practitioner holds.
Click to view child attributes
text
string
The license type code. This field specifies the type of license that practitioner holds.
**Value Options Supported:**
  - CLIA
  - DEA
  - PTAN
  - SPI
  - STATE
  - TAXONOMY
  - OTHER
period
json
A component of the Practitioner's license that defines validity period of the license with starting and the ending dates.
Click to view child attributes
start
string
Start date of the Practitioner's license. Expected date format is YYYY-MM-DD (Example - "2020-01-01")
end
string
End date of the Practitioner's license. Expected date format is YYYY-MM-DD (Example - "2020-01-01")
issuer
json
A component of the Practitioner's license object that defines the license issuing authority short name.
Click to view child attributes
display
string
The display text of the license's short name.
extension
array[json]
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state
  - http://schemas.canvasmedical.com/fhir/extensions/license-primary
valueString
string
The string value for the extension. Used for issuing authority short name and state extensions.
valueBoolean
boolean
The boolean value for the extension. Used for the license-primary extension to indicate if this is the practitioner's primary license.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Practitioner/{id}
#### Practitioner update
Update Practitioner with provided fields and values.
### Attributes
id
string required
Unique Canvas identifier for this resource.
extension
array[json]
Canvas supports specific FHIR extensions on this resource. In order to identify which extension maps to specific fields in Canvas, the url field is used as an exact string match.  
During updates, When an extension is omitted from the payload request, it will be considered as an intention to remove the value stored associated to that field, thus their values will be deleted in Canvas. The only exception is the username extension, which remains unchanged and this API will return error if the update request is trying to change the Practitioner's (Staff) username.
Click to view child attributes
url
string required
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature
  - http://schemas.canvasmedical.com/fhir/extensions/roles
valueString
string
Value of extension.  
The `valueString` attribute is needed for the role's extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username`.   
A username is a unique and often personalized identifier that an individual or entity uses to access a computer system, online platform, or any other service that requires user authentication
valueUrl
string
Value of extension.  
The `valueUrl` attribute is needed for the meeting link extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link`. This value will represent the url that will be associated to any telehealth notes in Canvas.
valueReference
json
Value of extension.  
The `valueReference` attribute is needed for the primary location extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location`. This attribute will be the reference the practitioner's primary location they practice at.
Click to view child attributes
reference
string
The reference string of the location in the format of `"Location/95b9ac2d-e963-4d7a-b165-7901870f1663"`.
type
string
Type the reference refers to (e.g. "Location").
valueAttachment
json
Value of extension.  
The `valueAttachment` attribute is needed for the signature extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature`. This attribute represents the attachment of the practitioner's real handwritten signature file.
Click to view child attributes
data
string
A base64-encoded file.
extension
array[json]
For the Role extensions where the url is `http://schemas.canvasmedical.com/fhir/extensions/roles`, the `extension` attribute is used to define the list of role's this practitioner has at the practice.
Click to view child attributes
url
string
Identifies the meaning of the extension.
**Value Options Supported:**
  - code
valueCoding
json required
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/roles
code
string required
The internal code. Examples of expected values include RN, CA, MA, etc. Some of these values are built in to each Canvas instance but are customizable. See this [article](https://canvas-medical.help.usepylon.com/articles/6649603926-staff-roles) for more information.
display
string
The display name of the coding.
identifier
array[json]
A secondary identifier for the Practitioner. This is the NPI number of the Practitioner in Canvas.
Click to view child attributes
system
string
The `system` attribute specifies the namespace in which the identifier value is unique.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/us-npi
value
string
Practitioner's NPI number. Its value must be a 10 digit number.
active
boolean
A boolean to specify if the practitioner is active in the healthcare system. If this value is not set, Canvas will default this to true.
name
array[json] required
The name associated with the practitioner.
Click to view child attributes
use
enum [ usual ] required
The 'use' attribute specifies the context in which the name is used. For this API, the only permitted value is 'usual,' which indicates that the name provided is the name typically used to identify the practitioner in daily practice.
family
string required
Practitioner's last name.
given
array[string] required
Practitioner's first name. Only one first name is allowed.
telecom
array[json] required
Practitioner contact point(s) (email / phone / fax).   
At least one contact point with the specifications `system`: **phone** and `use`: **work** is required as the primary phone for the Practitioner.   
There must be exactly one contact point with the specifications `system`: **email** and `rank`: **1**. An error will be triggered if there is more than one `email` with `rank` set to **1** , however, multiple emails with other ranks (e.g., rank 2, 3, 4, etc.) are allowed.   
**IMPORTANT** : The rank **1** email is the practitioner's login email, where password reset links are sent, so an update can't set it to a new address: the rank **1** email must be one the practitioner already has. To add an email, give it a rank of **2** or higher and omit `id`. An email contact point that includes an `id` must keep its current value. A request that breaks either rule fails with the error `Updating email telecoms (email Contact Points) is not allowed at this moment. Emails must remain the same.`
Click to view child attributes
id
string
The identifier (ID) of the telecom (contact point) record in Canvas.   
If you want to update a specific telecom record in Canvas, use this property to target that record.   
If you omit "id" during update, a new telecom record will be created.
system
enum [ phone | fax | email | pager | other ] required
Telecommunications form for contact point - what communications system is required to make use of the contact.
value
string required
The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address). Values for phone numbers (where "system" is set to "phone") must be only digits, with no sign characters or spaces.
use
enum [ home | work | temp | old | mobile ] required
Identifies the purpose for the contact point.
rank
integer required
Specifies a preferred order in which to use a set of contacts. ContactPoints with lower rank values are more preferred than those with higher rank values.
address
array[json]
Address(es) of the practitioner entered in Canvas. No default values will be set.
Click to view child attributes
id
string
The identifier (ID) of the address record in Canvas.   
If you want to update a specific address record in Canvas, use this property to target that record.   
If you omit "id" during update, a new address record will be created.
use
enum [ home | work | temp | old | billing ] required
Defines the purpose of this address.
type
enum [ both | physical | postal ] required
Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses). Most addresses are both.
line
array[string]
This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.  
The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.
city
string
The name of the city, town, suburb, village or other community or delivery center.
state
string
Two-letter state abbreviation of the address.
postalCode
string
The 5-digit postal code of the address.
country
string
Specifies the country in which the practitioner's address is located. This field typically contains the name of the country, following the ISO 3166 standard.
birthDate
date required
The date on which the practitioner was born, formatted as YYYY-MM-DD.
photo
array[json]
Practitioner photo(s).
Click to view child attributes
url
string required
Uri where the data can be found.
title
string
Label to display in place of the data.
qualification
array[json]
Practitioner license(s)
Click to view child attributes
identifier
array[json] required
This component identifies the issuing authority of the Practitioner's qualification (license).
Click to view child attributes
system
string
The `system` attribute specifies the namespace in which the identifier value is unique.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url
value
string
The `value` attribute contains the actual identifier assigned to the practitioner's qualification. This value is unique within the context defined by the `system` attribute. It can be any string that serves as a meaningful identifier, such as a license number, certification ID, or other relevant qualification identifiers.
code
json
License type coding object. Specifies the type of license that practitioner holds.
Click to view child attributes
text
string
The license type code. This field specifies the type of license that practitioner holds.
**Value Options Supported:**
  - CLIA
  - DEA
  - PTAN
  - SPI
  - STATE
  - TAXONOMY
  - OTHER
period
json required
A component of the Practitioner's license that defines validity period of the license with starting and the ending dates.
Click to view child attributes
start
string
Start date of the Practitioner's license. Expected date format is YYYY-MM-DD (Example - "2020-01-01")
end
string
End date of the Practitioner's license. Expected date format is YYYY-MM-DD (Example - "2020-01-01")
issuer
json
A component of the Practitioner's license object that defines the license issuing authority short name.
Click to view child attributes
display
string
The display text of the license's short name.
extension
array[json]
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state
  - http://schemas.canvasmedical.com/fhir/extensions/license-primary
valueString
string
The string value for the extension. Used for issuing authority short name and state extensions.
valueBoolean
boolean
The boolean value for the extension. Used for the license-primary extension to indicate if this is the practitioner's primary license.
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Practitioner
#### Practitioner search
Search for Practitioner resources
### Query Parameters
****
_id
string
A Canvas-issued unique identifier
include-non-schedulable-practitioners
boolean
By default, only schedulable practitioners are displayed. Passing this parameter as "true" will return both schedulable and non-schedulable practitioners.
active
string
Search by `active` status ("true" or "false" - case insensitive). By default if this param is not present, it will return practitioners with `active` set to True ("true").
name
string
A search that may match any of the string fields in the name, including `family`, `given`, `prefix`, `suffix`, and/or `text`. Partial search is supported.
email
string
Practitioner user email.
npi-number
string
Practitioner NPI number.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
id
string
Unique Canvas identifier for this resource.
extension
array[json]
Canvas supports specific FHIR extensions on this resource.
Click to view child attributes
url
string
Identifies the meaning of the extension
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location
  - http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature
  - http://schemas.canvasmedical.com/fhir/extensions/roles
valueString
string
Value of extension.  
The `valueString` attribute is needed for the role's extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username`.   
A username is a unique and often personalized identifier that an individual or entity uses to access a computer system, online platform, or any other service that requires user authentication
valueUrl
string
Value of extension.  
The `valueUrl` attribute is needed for the meeting link extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link`. This value will represent the url that will be associated to any telehealth notes in Canvas.
valueReference
json
Value of extension.  
The `valueReference` attribute is needed for the primary location extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location`. This attribute will be the reference the practitioner's primary location they practice at.
Click to view child attributes
reference
string
The reference string of the location in the format of `"Location/95b9ac2d-e963-4d7a-b165-7901870f1663"`.
type
string
Type the reference refers to (e.g. "Location").
valueAttachment
json
Value of extension.  
The `valueAttachment` attribute is needed for the signature extension where the `url` is `http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature`. This attribute represents the attachment of the practitioner's real handwritten signature file.
Click to view child attributes
extension
json
Extension for backward-compatible URLs
url
string
URI where the data can be found. This URL requires a Bearer token and returns a redirect to a pre-signed S3 URL. See [Accessing Resource Attachment Files](/api/accessing-resource-attachment-files) for details on how to access the file.
extension
array[json]
For the Role extensions where the url is `http://schemas.canvasmedical.com/fhir/extensions/roles`, the `extension` attribute is used to define the list of role's this practitioner has at the practice.
Click to view child attributes
url
string
Identifies the meaning of the extension.
**Value Options Supported:**
  - code
valueCoding
json
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/roles
code
string
The internal code. Examples of expected values include RN, CA, MA, etc. Some of these values are built in to each Canvas instance but are customizable. See this [article](https://canvas-medical.help.usepylon.com/articles/6649603926-staff-roles) for more information.
display
string
The display name of the coding.
identifier
array[json]
A secondary identifier for the Practitioner. This is the NPI number of the Practitioner in Canvas.
Click to view child attributes
system
string
The `system` attribute specifies the namespace in which the identifier value is unique.
**Value Options Supported:**
  - http://hl7.org/fhir/sid/us-npi
value
string
Practitioner's NPI number. Its value must be a 10 digit number.
active
boolean
A boolean to specify if the practitioner is active in the healthcare system. If this value is not set, Canvas will default this to true.
name
array[json]
The name associated with the practitioner.
Click to view child attributes
use
enum [ usual ]
The 'use' attribute specifies the context in which the name is used. For this API, the only permitted value is 'usual,' which indicates that the name provided is the name typically used to identify the practitioner in daily practice.
text
string
Text representation of the full name.
family
string
Practitioner's last name.
given
array[string]
Practitioner's first name. Only one first name is allowed.
prefix
array[string]
Parts that come before the name.
suffix
array[string]
Parts that come after the name.
telecom
array[json]
Practitioner contact point(s) (email / phone / fax).
Click to view child attributes
id
string
The identifier (ID) of the telecom (contact point) record in Canvas.
system
enum [ phone | fax | email | pager | other ]
Telecommunications form for contact point - what communications system is required to make use of the contact.
value
string
The actual contact point details, in a form that is meaningful to the designated communication system (i.e. phone number or email address).
use
enum [ home | work | temp | old | mobile ]
Identifies the purpose for the contact point.
rank
integer
Specifies a preferred order in which to use a set of contacts. ContactPoints with lower rank values are more preferred than those with higher rank values.
address
array[json]
Address(es) of the practitioner entered in Canvas. No default values will be set.
Click to view child attributes
id
string
The identifier (ID) of the address record in Canvas.
use
enum [ home | work | temp | old | billing ]
Defines the purpose of this address.
type
enum [ both | physical | postal ]
Distinguishes between physical addresses (those you can visit) and mailing addresses (e.g. PO Boxes and care-of addresses). Most addresses are both.
line
array[string]
This component contains the house number, apartment number, street name, street direction, P.O. Box number, delivery hints, and similar address information.  
The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.
city
string
The name of the city, town, suburb, village or other community or delivery center.
state
string
Two-letter state abbreviation of the address.
postalCode
string
The 5-digit postal code of the address.
country
string
Specifies the country in which the practitioner's address is located. This field typically contains the name of the country, following the ISO 3166 standard.
birthDate
date
The date on which the practitioner was born, formatted as YYYY-MM-DD.
photo
array[json]
Practitioner photo(s).
Click to view child attributes
url
string
Uri where the data can be found.
title
string
Label to display in place of the data.
qualification
array[json]
Practitioner license(s)
Click to view child attributes
identifier
array[json]
This component identifies the issuing authority of the Practitioner's qualification (license).
Click to view child attributes
system
string
The `system` attribute specifies the namespace in which the identifier value is unique.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url
value
string
The `value` attribute contains the actual identifier assigned to the practitioner's qualification. This value is unique within the context defined by the `system` attribute. It can be any string that serves as a meaningful identifier, such as a license number, certification ID, or other relevant qualification identifiers.
code
json
License type coding object. Specifies the type of license that practitioner holds.
Click to view child attributes
text
string
The license type code. This field specifies the type of license that practitioner holds.
**Value Options Supported:**
  - CLIA
  - DEA
  - PTAN
  - SPI
  - STATE
  - TAXONOMY
  - OTHER
period
json
A component of the Practitioner's license that defines validity period of the license with starting and the ending dates.
Click to view child attributes
start
string
Start date of the Practitioner's license. Expected date format is YYYY-MM-DD (Example - "2020-01-01")
end
string
End date of the Practitioner's license. Expected date format is YYYY-MM-DD (Example - "2020-01-01")
issuer
json
A component of the Practitioner's license object that defines the license issuing authority short name.
Click to view child attributes
display
string
The display text of the license's short name.
extension
array[json]
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name
  - http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state
  - http://schemas.canvasmedical.com/fhir/extensions/license-primary
valueString
string
The string value for the extension. Used for issuing authority short name and state extensions.
valueBoolean
boolean
The boolean value for the extension. Used for the license-primary extension to indicate if this is the practitioner's primary license.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```sh
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Practitioner' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Practitioner",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username",
                    "valueString": "username123"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link",
                    "valueUrl": "https://meet.google.com/room-001"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature",
                    "valueAttachment": {
                        "data": "JVBERi0xLjIgCjkgMCBvYmoKPDwKPj4Kc3RyZWFtCkJULyAzMiBUZiggIFlPVVIgVEVYVCBIRVJFICAgKScgRVQKZW5kc3RyZWFtCmVuZG9iago0IDAgb2JqCjw8Ci9UeXBlIC9QYWdlCi9QYXJlbnQgNSAwIFIKL0NvbnRlbnRzIDkgMCBSCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9LaWRzIFs0IDAgUiBdCi9Db3VudCAxCi9UeXBlIC9QYWdlcwovTWVkaWFCb3ggWyAwIDAgMjUwIDUwIF0KPj4KZW5kb2JqCjMgMCBvYmoKPDwKL1BhZ2VzIDUgMCBSCi9UeXBlIC9DYXRhbG9nCj4+CmVuZG9iagp0cmFpbGVyCjw8Ci9Sb290IDMgMCBSCj4+CiUlRU9G"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/roles",
                    "extension": [
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "RN"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "MA"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "CC"
                            }
                        }
                    ]
                }
            ],
            "identifier": [
                {
                    "system": "http://hl7.org/fhir/sid/us-npi",
                    "value": "1920301155"
                }
            ],
            "active": true,
            "name": [
                {
                    "use": "usual",
                    "family": "Jones",
                    "given": [
                        "Samantha"
                    ]
                }
            ],
            "telecom": [
                {
                    "system": "phone",
                    "value": "5558675309",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "system": "phone",
                    "value": "5551234567",
                    "use": "work",
                    "rank": 1
                },
                {
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                }
            ],
            "address": [
                {
                    "use": "work",
                    "type": "both",
                    "line": [
                        "1234 Main St"
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107",
                    "country": "United States"
                },
                {
                    "use": "work",
                    "type": "both",
                    "line": [
                        "12 Cesar Chavez St"
                    ],
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94110",
                    "country": "United States"
                }
            ],
            "birthDate": "1988-10-10",
            "photo": [
                {
                    "url": "https://fastly.picsum.photos/id/1064/200/300.jpg?hmac=Joir_QEJYjd2_bmYco64ek_C2TSsfReMcWWcXYsObKI",
                    "title": "Profile photo 1 -- sample title"
                },
                {
                    "url": "https://fastly.picsum.photos/id/674/200/300.jpg?hmac=kS3VQkm7AuZdYJGUABZGmnNj_3KtZ6Twgb5Qb9ITssY"
                }
            ],
            "qualification": [
                {
                    "identifier": [
                        {
                            "system": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url",
                            "value": "PRT-01"
                        }
                    ],
                    "code": {
                        "text": "License"
                    },
                    "period": {
                        "start": "2020-01-01",
                        "end": "2024-05-05"
                    },
                    "issuer": {
                        "display": "MD University Los Angeles",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name",
                                "valueString": "MDU LA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state",
                                "valueString": "CA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/license-primary",
                                "valueBoolean": true
                            }
                        ]
                    }
                }
            ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Practitioner"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Practitioner",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username",
                    "valueString": "username123"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link",
                    "valueUrl": "https://meet.google.com/room-001"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature",
                    "valueAttachment": {
                        "data": "JVBERi0xLjIgCjkgMCBvYmoKPDwKPj4Kc3RyZWFtCkJULyAzMiBUZiggIFlPVVIgVEVYVCBIRVJFICAgKScgRVQKZW5kc3RyZWFtCmVuZG9iago0IDAgb2JqCjw8Ci9UeXBlIC9QYWdlCi9QYXJlbnQgNSAwIFIKL0NvbnRlbnRzIDkgMCBSCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9LaWRzIFs0IDAgUiBdCi9Db3VudCAxCi9UeXBlIC9QYWdlcwovTWVkaWFCb3ggWyAwIDAgMjUwIDUwIF0KPj4KZW5kb2JqCjMgMCBvYmoKPDwKL1BhZ2VzIDUgMCBSCi9UeXBlIC9DYXRhbG9nCj4+CmVuZG9iagp0cmFpbGVyCjw8Ci9Sb290IDMgMCBSCj4+CiUlRU9G"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/roles",
                    "extension": [
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "RN"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "MA"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "CC"
                            }
                        }
                    ]
                }
            ],
            "identifier": [
                {
                    "system": "http://hl7.org/fhir/sid/us-npi",
                    "value": "1920301155"
                }
            ],
            "active": True,
            "name": [
                {
                    "use": "usual",
                    "family": "Jones",
                    "given": [
                        "Samantha"
                    ]
                }
            ],
            "telecom": [
                {
                    "system": "phone",
                    "value": "5554320555",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "system": "phone",
                    "value": "333555",
                    "use": "work",
                    "rank": 1
                },
                {
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                },
                {
                    "system": "email",
                    "value": "samantha.jones2@example.com",
                    "use": "work",
                    "rank": 2
                }
            ],
            "address": [
                {
                    "use": "work",
                    "line": [
                        "1234 Main St"
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107",
                    "country": "United States"
                },
                {
                    "use": "work",
                    "line": [
                        "12 Cesar Chavez St"
                    ],
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94110",
                    "country": "United States"
                }
            ],
            "birthDate": "1988-10-10",
            "photo": [
                {
                    "url": "https://fastly.picsum.photos/id/1064/200/300.jpg?hmac=Joir_QEJYjd2_bmYco64ek_C2TSsfReMcWWcXYsObKI",
                    "title": "Profile photo 1 -- sample title"
                },
                {
                    "url": "https://fastly.picsum.photos/id/674/200/300.jpg?hmac=kS3VQkm7AuZdYJGUABZGmnNj_3KtZ6Twgb5Qb9ITssY"
                }
            ],
            "qualification": [
                {
                    "identifier": [
                        {
                            "system": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url",
                            "value": "PRT-01"
                        }
                    ],
                    "code": {
                        "text": "License"
                    },
                    "period": {
                        "start": "2020-01-01",
                        "end": "2024-05-05"
                    },
                    "issuer": {
                        "display": "MD University Los Angeles",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name",
                                "valueString": "MDU LA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state",
                                "valueString": "CA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/license-primary",
                                "valueBoolean": True
                            }
                        ]
                    }
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Practitioner/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Practitioner/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Practitioner",
            "id": "55096fbcdfb240fd8c999c325304de03",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username",
                    "valueString": "username123"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link",
                    "valueUrl": "https://meet.google.com/room-001"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location",
                        "display": "Canvas Clinic San Francisco"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature",
                    "valueAttachment": {
                        "url": "https://fumage-example.canvasmedical.com/Practitioner/55096fbcdfb240fd8c999c325304de03/files/signature"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/roles",
                    "extension": [
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "RN"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "MA"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "CC"
                            }
                        }
                    ]
                }
            ],
            "identifier": [
                {
                    "system": "http://hl7.org/fhir/sid/us-npi",
                    "value": "1920301155"
                }
            ],
            "active": true,
            "name": [
                {
                    "use": "usual",
                    "text": "Samantha Jones",
                    "family": "Jones",
                    "given": [
                        "Samantha"
                    ]
                }
            ],
            "telecom": [
                {
                    "id": "4fb49223-3d48-4bd6-8125-2ac62208efd6",
                    "system": "phone",
                    "value": "5554320555",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "id": "1a7f5403-2d9e-4156-a6e0-16c816e873fd",
                    "system": "phone",
                    "value": "333555",
                    "use": "work",
                    "rank": 1
                },
                {
                    "id": "2d9490aa-ed57-46ef-8eec-ed5f22c38844",
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                },
                {
                    "id": "4b8369cf-67e7-404d-8abe-51ff6e9ac835",
                    "system": "email",
                    "value": "samantha.jones2@example.com",
                    "use": "work",
                    "rank": 2
                }
            ],
            "address": [
                {
                    "id": "5e76df8f-36c1-489a-8034-0916c7e8829f",
                    "use": "work",
                    "line": [
                        "1234 Main St"
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107",
                    "country": "United States"
                },
                {
                    "id": "33fe0a8f-1140-4ee3-b703-1afe42e8a3d6",
                    "use": "work",
                    "line": [
                        "12 Cesar Chavez St"
                    ],
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94110",
                    "country": "United States"
                }
            ],
            "birthDate": "1988-10-10",
            "photo": [
                {
                    "url": "https://fastly.picsum.photos/id/1064/200/300.jpg?hmac=Joir_QEJYjd2_bmYco64ek_C2TSsfReMcWWcXYsObKI",
                    "title": "Profile photo 1 -- sample title"
                },
                {
                    "url": "https://fastly.picsum.photos/id/674/200/300.jpg?hmac=kS3VQkm7AuZdYJGUABZGmnNj_3KtZ6Twgb5Qb9ITssY"
                }
            ],
            "qualification": [
                {
                    "identifier": [
                        {
                            "system": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url",
                            "value": "PRT-01"
                        }
                    ],
                    "code": {
                        "text": "License"
                    },
                    "period": {
                        "start": "2020-01-01",
                        "end": "2024-05-05"
                    },
                    "issuer": {
                        "display": "MD University Los Angeles",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name",
                                "valueString": "MDU LA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state",
                                "valueString": "CA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/license-primary",
                                "valueBoolean": true
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
            "resourceType": "OperationOutcome",
            "issue": [
                {
                    "severity": "error",
                    "code": "not-found",
                    "details": {
                        "text": "Unknown Practitioner resource '7d1ce256fcd7408193b0459650937a07'"
                    }
                }
            ]
        }
        ```
  - **curl**
        ```sh
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/Practitioner/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Practitioner",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link",
                    "valueUrl": "https://meet.google.com/room-001"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature",
                    "valueAttachment": {
                        "url": "https://canvas-client-media.s3.amazonaws.com/local/signature-cdfkizrj.pdf?AWSAccessKeyId=AKIA5KJ2QWTAU572JXPZ&Signature=ljyujvD4fkgOG7b3SxlIokdDIlQ%3D&Expires=1703596102"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/roles",
                    "extension": [
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "RN"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "MA"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "CC"
                            }
                        }
                    ]
                }
            ],
            "identifier": [
                {
                    "system": "http://hl7.org/fhir/sid/us-npi",
                    "value": "1920301155"
                }
            ],
            "active": true,
            "name": [
                {
                    "use": "usual",
                    "text": "Samantha Jones",
                    "family": "Jones",
                    "given": [
                        "Samantha"
                    ]
                }
            ],
            "telecom": [
                {
                    "id": "4fb49223-3d48-4bd6-8125-2ac62208efd6",
                    "system": "phone",
                    "value": "5554320555",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "id": "1a7f5403-2d9e-4156-a6e0-16c816e873fd",
                    "system": "phone",
                    "value": "333555",
                    "use": "work",
                    "rank": 1
                },
                {
                    "id": "2d9490aa-ed57-46ef-8eec-ed5f22c38844",
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                },
                {
                    "id": "4b8369cf-67e7-404d-8abe-51ff6e9ac835",
                    "system": "email",
                    "value": "samantha.jones2@example.com",
                    "use": "work",
                    "rank": 2
                }
            ],
            "address": [
                {
                    "id": "5e76df8f-36c1-489a-8034-0916c7e8829f",
                    "use": "work",
                    "line": [
                        "1234 Main St"
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107",
                    "country": "United States"
                },
                {
                    "id": "33fe0a8f-1140-4ee3-b703-1afe42e8a3d6",
                    "use": "work",
                    "line": [
                        "12 Cesar Chavez St"
                    ],
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94110",
                    "country": "United States"
                }
            ],
            "birthDate": "1988-10-10",
            "photo": [
                {
                    "url": "https://fastly.picsum.photos/id/1064/200/300.jpg?hmac=Joir_QEJYjd2_bmYco64ek_C2TSsfReMcWWcXYsObKI",
                    "title": "Profile photo 1 -- sample title"
                },
                {
                    "url": "https://fastly.picsum.photos/id/674/200/300.jpg?hmac=kS3VQkm7AuZdYJGUABZGmnNj_3KtZ6Twgb5Qb9ITssY"
                }
            ],
            "qualification": [
                {
                    "identifier": [
                        {
                            "system": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url",
                            "value": "PRT-01"
                        }
                    ],
                    "code": {
                        "text": "License"
                    },
                    "period": {
                        "start": "2020-01-01",
                        "end": "2024-05-05"
                    },
                    "issuer": {
                        "display": "MD University Los Angeles",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name",
                                "valueString": "MDU LA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state",
                                "valueString": "CA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/license-primary",
                                "valueBoolean": true
                            }
                        ]
                    }
                }
            ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Practitioner/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "Practitioner",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link",
                    "valueUrl": "https://meet.google.com/room-001"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location",
                    "valueReference": {
                        "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                        "type": "Location"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature",
                    "valueAttachment": {
                        "url": "https://canvas-client-media.s3.amazonaws.com/local/signature-cdfkizrj.pdf?AWSAccessKeyId=AKIA5KJ2QWTAU572JXPZ&Signature=ljyujvD4fkgOG7b3SxlIokdDIlQ%3D&Expires=1703596102"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/roles",
                    "extension": [
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "RN"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "MA"
                            }
                        },
                        {
                            "url": "code",
                            "valueCoding": {
                                "system": "http://schemas.canvasmedical.com/fhir/roles",
                                "code": "CC"
                            }
                        }
                    ]
                }
            ],
            "identifier": [
                {
                    "system": "http://hl7.org/fhir/sid/us-npi",
                    "value": "1920301155"
                }
            ],
            "active": True,
            "name": [
                {
                    "use": "usual",
                    "family": "Jones",
                    "given": [
                        "Samantha"
                    ]
                }
            ],
            "telecom": [
                {
                    "id": "4fb49223-3d48-4bd6-8125-2ac62208efd6",
                    "system": "phone",
                    "value": "5554320555",
                    "use": "mobile",
                    "rank": 1
                },
                {
                    "id": "1a7f5403-2d9e-4156-a6e0-16c816e873fd",
                    "system": "phone",
                    "value": "333555",
                    "use": "work",
                    "rank": 1
                },
                {
                    "id": "2d9490aa-ed57-46ef-8eec-ed5f22c38844",
                    "system": "email",
                    "value": "samantha.jones@example.com",
                    "use": "work",
                    "rank": 1
                },
                {
                    "id": "4b8369cf-67e7-404d-8abe-51ff6e9ac835",
                    "system": "email",
                    "value": "samantha.jones2@example.com",
                    "use": "work",
                    "rank": 2
                }
            ],
            "address": [
                {
                    "id": "5e76df8f-36c1-489a-8034-0916c7e8829f",
                    "use": "work",
                    "line": [
                        "1234 Main St"
                    ],
                    "city": "Los Angeles",
                    "state": "CA",
                    "postalCode": "94107",
                    "country": "United States"
                },
                {
                    "id": "33fe0a8f-1140-4ee3-b703-1afe42e8a3d6",
                    "use": "work",
                    "line": [
                        "12 Cesar Chavez St"
                    ],
                    "city": "San Francisco",
                    "state": "CA",
                    "postalCode": "94110",
                    "country": "United States"
                }
            ],
            "birthDate": "1988-10-10",
            "photo": [
                {
                    "url": "https://fastly.picsum.photos/id/1064/200/300.jpg?hmac=Joir_QEJYjd2_bmYco64ek_C2TSsfReMcWWcXYsObKI",
                    "title": "Profile photo 1 -- sample title"
                },
                {
                    "url": "https://fastly.picsum.photos/id/674/200/300.jpg?hmac=kS3VQkm7AuZdYJGUABZGmnNj_3KtZ6Twgb5Qb9ITssY"
                }
            ],
            "qualification": [
                {
                    "identifier": [
                        {
                            "system": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url",
                            "value": "PRT-01"
                        }
                    ],
                    "code": {
                        "text": "License"
                    },
                    "period": {
                        "start": "2020-01-01",
                        "end": "2024-05-05"
                    },
                    "issuer": {
                        "display": "MD University Los Angeles",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name",
                                "valueString": "MDU LA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state",
                                "valueString": "CA"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/license-primary",
                                "valueBoolean": True
                            }
                        ]
                    }
                }
            ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown  resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Practitioner?name=Samantha' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Practitioner?name=Samantha"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Practitioner?_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Practitioner?_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Practitioner?_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Practitioner",
                        "id": "55096fbcdfb240fd8c999c325304de03",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username",
                                "valueString": "username123"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-personal-meeting-room-link",
                                "valueUrl": "https://meet.google.com/room-001"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-primary-practice-location",
                                "valueReference": {
                                    "reference": "Location/95b9ac2d-e963-4d7a-b165-7901870f1663",
                                    "type": "Location",
                                    "display": "Canvas Clinic San Francisco"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-signature",
                                "valueAttachment": {
                                    "url": "https://fumage-example.canvasmedical.com/Practitioner/55096fbcdfb240fd8c999c325304de03/files/signature"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/roles",
                                "extension": [
                                    {
                                        "url": "code",
                                        "valueCoding": {
                                            "system": "http://schemas.canvasmedical.com/fhir/roles",
                                            "code": "RN"
                                        }
                                    },
                                    {
                                        "url": "code",
                                        "valueCoding": {
                                            "system": "http://schemas.canvasmedical.com/fhir/roles",
                                            "code": "MA"
                                        }
                                    },
                                    {
                                        "url": "code",
                                        "valueCoding": {
                                            "system": "http://schemas.canvasmedical.com/fhir/roles",
                                            "code": "CC"
                                        }
                                    }
                                ]
                            }
                        ],
                        "identifier": [
                            {
                                "system": "http://hl7.org/fhir/sid/us-npi",
                                "value": "1920301155"
                            }
                        ],
                        "active": true,
                        "name": [
                            {
                                "use": "usual",
                                "text": "Samantha Jones",
                                "family": "Jones",
                                "given": [
                                    "Samantha"
                                ]
                            }
                        ],
                        "telecom": [
                            {
                                "id": "4fb49223-3d48-4bd6-8125-2ac62208efd6",
                                "system": "phone",
                                "value": "5554320555",
                                "use": "mobile",
                                "rank": 1
                            },
                            {
                                "id": "1a7f5403-2d9e-4156-a6e0-16c816e873fd",
                                "system": "phone",
                                "value": "333555",
                                "use": "work",
                                "rank": 1
                            },
                            {
                                "id": "2d9490aa-ed57-46ef-8eec-ed5f22c38844",
                                "system": "email",
                                "value": "samantha.jones@example.com",
                                "use": "work",
                                "rank": 1
                            },
                            {
                                "id": "4b8369cf-67e7-404d-8abe-51ff6e9ac835",
                                "system": "email",
                                "value": "samantha.jones2@example.com",
                                "use": "work",
                                "rank": 2
                            }
                        ],
                        "address": [
                            {
                                "id": "5e76df8f-36c1-489a-8034-0916c7e8829f",
                                "use": "work",
                                "line": [
                                    "1234 Main St"
                                ],
                                "city": "Los Angeles",
                                "state": "CA",
                                "postalCode": "94107",
                                "country": "United States"
                            },
                            {
                                "id": "33fe0a8f-1140-4ee3-b703-1afe42e8a3d6",
                                "use": "work",
                                "line": [
                                    "12 Cesar Chavez St"
                                ],
                                "city": "San Francisco",
                                "state": "CA",
                                "postalCode": "94110",
                                "country": "United States"
                            }
                        ],
                        "birthDate": "1988-10-10",
                        "photo": [
                            {
                                "url": "https://fastly.picsum.photos/id/1064/200/300.jpg?hmac=Joir_QEJYjd2_bmYco64ek_C2TSsfReMcWWcXYsObKI",
                                "title": "Profile photo 1 -- sample title"
                            },
                            {
                                "url": "https://fastly.picsum.photos/id/674/200/300.jpg?hmac=kS3VQkm7AuZdYJGUABZGmnNj_3KtZ6Twgb5Qb9ITssY"
                            }
                        ],
                        "qualification": [
                            {
                                "identifier": [
                                    {
                                        "system": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url",
                                        "value": "PRT-01"
                                    }
                                ],
                                "code": {
                                    "text": "License"
                                },
                                "period": {
                                    "start": "2020-01-01",
                                    "end": "2024-05-05"
                                },
                                "issuer": {
                                    "display": "MD University Los Angeles",
                                    "extension": [
                                        {
                                            "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name",
                                            "valueString": "MDU LA"
                                        },
                                        {
                                            "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state",
                                            "valueString": "CA"
                                        },
                                        {
                                            "url": "http://schemas.canvasmedical.com/fhir/extensions/license-primary",
                                            "valueBoolean": true
                                        }
                                    ]
                                }
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Procedure

Source: https://docs.canvasmedical.com/api/procedure/

### 
An action that is or was performed on or for a patient. This can be a physical intervention like an operation, or less invasive like long term services, counseling, or hypnotherapy.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-procedure.html>  
See this [Zendesk article](https://canvas-medical.help.usepylon.com/articles/5988007695-command-perform) for information on creating procedures with the `Perform` command.
### Endpoints
get/Procedure/{id} get/Procedure
get
/Procedure/{id}
#### Procedure read
Read an Procedure resource.
### Path Parameters
id required
string
The unique identifier for the Procedure   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Procedure.
basedOn
array[json]
A reference to a resource that contains details of the request for this procedure.
Click to view child attributes
reference
string
The reference string of the ServiceRequest in the format of `"ServiceRequest/a47c7b0e-bbb4-42cd-bc4a-df259d148ea1"`.
type
string
Type the reference refers to (e.g. "ServiceRequest").
status
enum [ in-progress | stopped | completed | unknown | entered-in-error ]
A code specifying the state of the procedure.
code
json
Identification of the procedure.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.ama-assn.org/go/cpt
  - unstructured
code
string
The code of the procedure.
display
string
The display name of the coding.
subject
json
Who the procedure was performed on
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
performedDateTime
datetime
When the procedure was performed.   
In Canvas, this will be the datetime of service of the note the Perform command is committed to.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Procedure
#### Procedure search
Search for Procedure resources.
### Query Parameters
****
_id
string
The identifier of the Procedure.
patient
string
The patient reference of whom the procedure was performed on in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Procedure.
basedOn
array[json]
A reference to a resource that contains details of the request for this procedure.
Click to view child attributes
reference
string
The reference string of the ServiceRequest in the format of `"ServiceRequest/a47c7b0e-bbb4-42cd-bc4a-df259d148ea1"`.
type
string
Type the reference refers to (e.g. "ServiceRequest").
status
enum [ in-progress | stopped | completed | unknown | entered-in-error ]
A code specifying the state of the procedure.
code
json
Identification of the procedure.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://www.ama-assn.org/go/cpt
  - unstructured
code
string
The code of the procedure.
display
string
The display name of the coding.
subject
json
Who the procedure was performed on
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
performedDateTime
datetime
When the procedure was performed.   
In Canvas, this will be the datetime of service of the note the Perform command is committed to.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Procedure/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Procedure/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Procedure",
            "id": "2dd9a3bc-a3bb-472b-aaef-c57be394de39",
            "basedOn": [
                {
                    "reference": "ServiceRequest/18b3d94d-70fa-4387-817c-9b8811e52d73",
                    "type": "ServiceRequest"
                }
            ],
            "status": "unknown",
            "code": {
                "coding": [
                    {
                        "system": "http://www.ama-assn.org/go/cpt",
                        "code": "23066",
                        "display": "Biopsy soft tissue shoulder deep"
                    }
                ]
            },
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                "type": "Patient"
            },
            "performedDateTime": "2023-09-20T21:18:54.263690+00:00"
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Procedure resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Procedure?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Procedure?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Procedure?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Procedure?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Procedure?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Procedure",
                        "id": "2dd9a3bc-a3bb-472b-aaef-c57be394de39",
                        "basedOn": [
                            {
                                "reference": "ServiceRequest/18b3d94d-70fa-4387-817c-9b8811e52d73",
                                "type": "ServiceRequest"
                            }
                        ],
                        "status": "unknown",
                        "code": {
                            "coding": [
                                {
                                    "system": "http://www.ama-assn.org/go/cpt",
                                    "code": "23066",
                                    "display": "Biopsy soft tissue shoulder deep"
                                }
                            ]
                        },
                        "subject": {
                            "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                            "type": "Patient"
                        },
                        "performedDateTime": "2023-09-20T21:18:54.263690+00:00"
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Provenance

Source: https://docs.canvasmedical.com/api/provenance/

### 
Provenance of a resource is a record that describes entities and processes involved in producing and delivering or otherwise influencing that resource. Provenance provides a critical foundation for assessing authenticity, enabling trust, and allowing reproducibility. Provenance assertions are a form of contextual metadata and can themselves become important records with their own provenance. Provenance statement indicates clinical significance in terms of confidence in authenticity, reliability, and trustworthiness, integrity, and stage in lifecycle (e.g. Document Completion - has the artifact been legally authenticated), all of which may impact security, privacy, and trust policies.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-provenance.html>   
In Canvas a Provenance record is created each time the following data types are created or updated in the Canvas database:
  - AllergyIntolerance
  - CarePlan
  - CareTeamMembership
  - Condition
  - ConsolidatedImmunization
  - Coverage
  - Device
  - DiagnosticReport
  - DocumentReference
  - Encounter
  - Goal
  - Observation
  - Patient
  - Prescription
  - Procedure
  - ServiceRequest
  - UpdateGoal
### Endpoints
get/Provenance/{id} get/Provenance
get
/Provenance/{id}
#### Provenance read
Read a Provenance resource.
### Path Parameters
id required
string
The unique identifier for the Provenance   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Provenance.
target
array[json]
Target Reference(s)
Click to view child attributes
reference
string
The reference string of the target in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
**Value Options Supported:**
  - AllergyIntolerance
  - CarePlan
  - CareTeam
  - Condition
  - Coverage
  - Device
  - DiagnosticReport
  - DocumentReference
  - Encounter
  - Goal
  - Immunization
  - MedicationRequest
  - Observation
  - Patient
  - Procedure
  - ServiceRequest
display
string
Text alternative for the resource.
recorded
datetime
When the activity was recorded / updated.
location
json
Where the activity occurred, if relevant. Currently, this will always appear as absent data.
Click to view child attributes
extension
array[json]
Click to view child attributes
url
string
**Value Options Supported:**
  - http://hl7.org/fhir/StructureDefinition/data-absent-reason
valueCode
string
**Value Options Supported:**
  - unsupported
activity
json
Activity that occurred. Canvas supports a provenance of the record being either created or updated.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-DataOperation
code
string
The code of the activity.
**Value Options Supported:**
  - CREATE
  - UPDATE
agent
array[json]
Actor involved.   
The agent will be populated by the committer or originator in Canvas as the auther. If neither is found, it will default to the Canvas Organization as the composer.
Click to view child attributes
type
json
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/provenance-participant-type
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-provenance-participant-type
code
string
The code.
**Value Options Supported:**
  - enterer
  - performer
  - author
  - verifier
  - legal
  - attester
  - informant
  - custodian
  - assembler
  - composer
  - transmitter
display
string
The display name of the coding.
**Value Options Supported:**
  - Enterer
  - Performer
  - Author
  - Verifier
  - Legal
  - Attester
  - Informant
  - Custodian
  - Assembler
  - Composer
  - Transmitter
who
json
Click to view child attributes
reference
string
The reference string of who the agent is in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`. If the reference is `Organization/00000000-0000-0000-0002-000000000000`, a committer or originator couldn't be found in Canvas as the agent, so Canvas Medical is the default agent.
type
string
Type the reference refers to (e.g. "Practitioner", "Organization").
display
string
Text alternative for the resource.
onBehalfOf
json
Who the agent is representing. This will always be the Canvas Medical Organization.
Click to view child attributes
reference
string
The reference string of who the organization is in the format of `"Organization/00000000-0000-0000-0002-000000000000"`.
type
string
Type the reference refers to (e.g. "Organization").
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Provenance
#### Provenance search
Search for Provenance resources.
### Query Parameters
****
_id
string
The identifier of the Provenance.
agent
string
Search by the agent of the Provenance record in the format `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"` or `Organization/00000000-0000-0000-0002-000000000000`.
patient
string
Search by provenance records associated to a specific patient in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
target
string
Search by records where the target is a specific patient or observation in the format `Patient/a39cafb9d1b445be95a2e2548e12a787` or `"Observation/920807d3-034b-4423-a65b-980068cb4bd1"`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Provenance.
target
array[json]
Target Reference(s)
Click to view child attributes
reference
string
The reference string of the target in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
**Value Options Supported:**
  - AllergyIntolerance
  - CarePlan
  - CareTeam
  - Condition
  - Coverage
  - Device
  - DiagnosticReport
  - DocumentReference
  - Encounter
  - Goal
  - Immunization
  - MedicationRequest
  - Observation
  - Patient
  - Procedure
  - ServiceRequest
display
string
Text alternative for the resource.
recorded
datetime
When the activity was recorded / updated.
location
json
Where the activity occurred, if relevant. Currently, this will always appear as absent data.
Click to view child attributes
extension
array[json]
Click to view child attributes
url
string
**Value Options Supported:**
  - http://hl7.org/fhir/StructureDefinition/data-absent-reason
valueCode
string
**Value Options Supported:**
  - unsupported
activity
json
Activity that occurred. Canvas supports a provenance of the record being either created or updated.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-DataOperation
code
string
The code of the activity.
**Value Options Supported:**
  - CREATE
  - UPDATE
agent
array[json]
Actor involved.   
The agent will be populated by the committer or originator in Canvas as the auther. If neither is found, it will default to the Canvas Organization as the composer.
Click to view child attributes
type
json
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/provenance-participant-type
  - http://hl7.org/fhir/us/core/CodeSystem/us-core-provenance-participant-type
code
string
The code.
**Value Options Supported:**
  - enterer
  - performer
  - author
  - verifier
  - legal
  - attester
  - informant
  - custodian
  - assembler
  - composer
  - transmitter
display
string
The display name of the coding.
**Value Options Supported:**
  - Enterer
  - Performer
  - Author
  - Verifier
  - Legal
  - Attester
  - Informant
  - Custodian
  - Assembler
  - Composer
  - Transmitter
who
json
Click to view child attributes
reference
string
The reference string of who the agent is in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`. If the reference is `Organization/00000000-0000-0000-0002-000000000000`, a committer or originator couldn't be found in Canvas as the agent, so Canvas Medical is the default agent.
type
string
Type the reference refers to (e.g. "Practitioner", "Organization").
display
string
Text alternative for the resource.
onBehalfOf
json
Who the agent is representing. This will always be the Canvas Medical Organization.
Click to view child attributes
reference
string
The reference string of who the organization is in the format of `"Organization/00000000-0000-0000-0002-000000000000"`.
type
string
Type the reference refers to (e.g. "Organization").
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Provenance/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Provenance/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Provenance",
            "id": "db1631ed-bcd3-4e43-84a1-7e507e8aa44c",
            "target": [
                {
                    "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                    "type": "Patient"
                }
            ],
            "recorded": "2023-09-18T14:42:14.981528+00:00",
            "activity": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
                        "code": "CREATE"
                    }
                ]
            },
            "agent": [
                {
                    "type": {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
                                "code": "composer",
                                "display": "Composer"
                            }
                        ]
                    },
                    "who": {
                        "reference": "Organization/00000000-0000-0000-0002-000000000000",
                        "type": "Organization",
                        "display": "Canvas Medical"
                    },
                    "onBehalfOf": {
                        "reference": "Organization/00000000-0000-0000-0002-000000000000",
                        "type": "Organization"
                    }
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Provenance resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Provenance?target=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Provenance?target=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Provenance?target=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Provenance?target=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Provenance?target=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Provenance",
                        "id": "db1631ed-bcd3-4e43-84a1-7e507e8aa44c",
                        "target": [
                            {
                                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                                "type": "Patient"
                            }
                        ],
                        "recorded": "2023-09-18T14:42:14.981528+00:00",
                        "activity": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
                                    "code": "CREATE"
                                }
                            ]
                        },
                        "agent": [
                            {
                                "type": {
                                    "coding": [
                                        {
                                            "system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
                                            "code": "composer",
                                            "display": "Composer"
                                        }
                                    ]
                                },
                                "who": {
                                    "reference": "Organization/00000000-0000-0000-0002-000000000000",
                                    "type": "Organization",
                                    "display": "Canvas Medical"
                                },
                                "onBehalfOf": {
                                    "reference": "Organization/00000000-0000-0000-0002-000000000000",
                                    "type": "Organization"
                                }
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Questionnaire

Source: https://docs.canvasmedical.com/api/questionnaire/

### 
A structured set of questions intended to guide the collection of answers from end-users. Questionnaires provide detailed control over order, presentation, phraseology and grouping to allow coherent, consistent data collection.  
<https://hl7.org/fhir/R4/questionnaire.html>  
See our [article](https://canvas-medical.help.usepylon.com/articles/7017593857-creating-questionnaires) for information about how to create and upload a questionnaire in Canvas.  
**Understanding Canvas Questionnaires**  
_Codings_  
All questionnaires must have coding, and all response options within a question on a questionnaire must have codings.  
_Question Types_  
Canvas supports 4 different type of questions:  
1\. Multi select response questions are denoted with:  
`"type": "choice", "repeats": true`  
2\. Single select response questions are denoted with:  
`"type": "choice", "repeats": false`  
3\. Free text response questions are denoted with:  
`"type": "text", "repeats": false`  
4\. Date response questions are denoted with:  
`"type": "date", "repeats": false`  
Questions can be reused in multiple questionnaires, but any given question code should only appear once within a particular questionnaire.
### Endpoints
get/Questionnaire/{id} get/Questionnaire
get
/Questionnaire/{id}
#### Questionnaire read
Read an Questionnaire resource.
### Path Parameters
id required
string
The unique identifier for the Questionnaire   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Questionnaire.
name
string
Name for this questionnaire (computer friendly).  
Canvas automatically versions questionnaires based on the name. Once a questionnaire is retired, you will see a version number next to the name (e.g `PHQ-9 (v7)`)
status
enum [ active | retired ]
The status of this questionnaire. Enables tracking the life-cycle of the content.
description
string
Natural language description of the questionnaire. May contain markdown syntax.
code
array[json]
Concept that represents the overall questionnaire.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the questionnaire.
item
array[json]
Questions and sections within the Questionnaire.
Click to view child attributes
linkId
string
Unique id for item in questionnaire.
code
array[json]
Corresponding concept for this item in a terminology.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the question.
text
string
Primary text for the item.
type
string
The type of questionnaire item this is.
**Value Options Supported:**
  - group (for nested groups of items)
  - choice (for multiple or single choice questions)
  - text (for free text questions)
  - decimal (for decimal numeric questions)
  - date (for date questions)
repeats
boolean
Whether the item may repeat. This value will be true for multiple choice questions and false for single select questions.
enableWhen
array[json]
Conditions under which this question is enabled (displayed). Corresponds to FHIR `enableWhen`.
Click to view child attributes
question
string
The linkId of the question whose answer is evaluated.
operator
string
The comparison operator.
**Value Options Supported:**
  - =
  - !=
  - exists
  - not_exists
answerCoding
json
Value for comparison when the condition references a choice question.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the answer option to match.
display
string
The display name of the answer option.
answerString
string
Value for comparison when the condition references a free text question.
answerBoolean
boolean
Used with the `exists` operator to indicate whether the referenced question must be answered (`true`) or unanswered (`false`).
enableBehavior
string
Controls whether `all` or `any` of the `enableWhen` conditions must be met. Only present when there are multiple `enableWhen` conditions.
**Value Options Supported:**
  - all
  - any
answerOption
array[json]
Permitted answers
Click to view child attributes
valueCoding
json
Answer value.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the answer.
display
string
The display name of the coding.
item
array[json]
Nested questionnaire items. A nested `item` attribute can represent questions nested under other questions, or groups of nested items. The attributes for nested items are the same as the attributes for items at the root level.  
If `item` is nested under an `item` of type **group** , then it represents a member of a group. If `item` is nested under an `item` of any type other than **group** or **display** , then it represents an item nested under a question.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Questionnaire
#### Questionnaire search
Search for Questionnaire resources.
### Query Parameters
****
_id
string
The identifier of the Questionnaire.
code
string
A code that corresponds to one of its items in the questionnaire.  
A Questionnaire search of the form `/Questionnaire?code=456789` will return Questionnaire resources uploaded to Canvas that have a question with the code **456789**.
name
string
Computationally friendly name of the questionnaire
questionnaire-code
string
A code that matches the Questionnaire's own `code` value.  
A Questionnaire search of the form `/Questionnaire?questionnaire-code=711013002` will return Questionnaire resources uploaded to Canvas that have the code **711013002**.
status
string
The current status of the questionnaire  
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the Questionnaire.
name
string
Name for this questionnaire (computer friendly).  
Canvas automatically versions questionnaires based on the name. Once a questionnaire is retired, you will see a version number next to the name (e.g `PHQ-9 (v7)`)
status
enum [ active | retired ]
The status of this questionnaire. Enables tracking the life-cycle of the content.
description
string
Natural language description of the questionnaire. May contain markdown syntax.
code
array[json]
Concept that represents the overall questionnaire.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the questionnaire.
item
array[json]
Questions and sections within the Questionnaire.
Click to view child attributes
linkId
string
Unique id for item in questionnaire.
code
array[json]
Corresponding concept for this item in a terminology.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the question.
text
string
Primary text for the item.
type
string
The type of questionnaire item this is.
**Value Options Supported:**
  - group (for nested groups of items)
  - choice (for multiple or single choice questions)
  - text (for free text questions)
  - decimal (for decimal numeric questions)
  - date (for date questions)
repeats
boolean
Whether the item may repeat. This value will be true for multiple choice questions and false for single select questions.
enableWhen
array[json]
Conditions under which this question is enabled (displayed). Corresponds to FHIR `enableWhen`.
Click to view child attributes
question
string
The linkId of the question whose answer is evaluated.
operator
string
The comparison operator.
**Value Options Supported:**
  - =
  - !=
  - exists
  - not_exists
answerCoding
json
Value for comparison when the condition references a choice question.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the answer option to match.
display
string
The display name of the answer option.
answerString
string
Value for comparison when the condition references a free text question.
answerBoolean
boolean
Used with the `exists` operator to indicate whether the referenced question must be answered (`true`) or unanswered (`false`).
enableBehavior
string
Controls whether `all` or `any` of the `enableWhen` conditions must be met. Only present when there are multiple `enableWhen` conditions.
**Value Options Supported:**
  - all
  - any
answerOption
array[json]
Permitted answers
Click to view child attributes
valueCoding
json
Answer value.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the answer.
display
string
The display name of the coding.
item
array[json]
Nested questionnaire items. A nested `item` attribute can represent questions nested under other questions, or groups of nested items. The attributes for nested items are the same as the attributes for items at the root level.  
If `item` is nested under an `item` of type **group** , then it represents a member of a group. If `item` is nested under an `item` of any type other than **group** or **display** , then it represents an item nested under a question.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Questionnaire/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Questionnaire/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Questionnaire",
            "id": "47a408d7-9f1d-4cfd-97c7-aa810df9ed39",
            "name": "Exercise",
            "status": "active",
            "description": "No Description Provided",
            "code": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "404684003"
                }
            ],
            "item": [
                {
                    "linkId": "d82e29db-0cac-4b97-a5aa-9e81749686e2",
                    "code": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "228448000"
                        }
                    ],
                    "text": "Do you exercise on a regular basis?",
                    "type": "choice",
                    "repeats": false,
                    "answerOption": [
                        {
                            "valueCoding": {
                                "system": "http://loinc.org",
                                "code": "LA33-6",
                                "display": "Yes"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://loinc.org",
                                "code": "LA32-8",
                                "display": "No"
                            }
                        }
                    ]
                },
                {
                    "linkId": "f2419de1-a208-4a3f-9d55-ba9bd5ed4ec2",
                    "code": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "228449008"
                        }
                    ],
                    "text": "In an average week, how many days do you exercise?",
                    "type": "choice",
                    "enableWhen": [
                        {
                            "question": "d82e29db-0cac-4b97-a5aa-9e81749686e2",
                            "operator": "=",
                            "answerCoding": {
                                "code": "LA33-6",
                                "display": "Yes"
                            }
                        }
                    ],
                    "repeats": false,
                    "answerOption": [
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q2_A1",
                                "display": "0"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q2_A2",
                                "display": "1"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q2_A3",
                                "display": "2"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q2_A4",
                                "display": "3"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q2_A5",
                                "display": "4"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q2_A6",
                                "display": "5"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q2_A7",
                                "display": "6"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q2_A8",
                                "display": "7"
                            }
                        }
                    ]
                },
                {
                    "linkId": "93137723-295f-4b28-9f97-fb58825b2cda",
                    "code": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "255257008"
                        }
                    ],
                    "text": "On the days when you exercised, for how long did you exercise?",
                    "type": "choice",
                    "enableWhen": [
                        {
                            "question": "d82e29db-0cac-4b97-a5aa-9e81749686e2",
                            "operator": "=",
                            "answerCoding": {
                                "code": "LA33-6",
                                "display": "Yes"
                            }
                        },
                        {
                            "question": "f2419de1-a208-4a3f-9d55-ba9bd5ed4ec2",
                            "operator": "exists",
                            "answerBoolean": true
                        }
                    ],
                    "enableBehavior": "all",
                    "repeats": false,
                    "answerOption": [
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q3_A1",
                                "display": "10-20 min"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q3_A2",
                                "display": "20-40 min"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q3_A3",
                                "display": "40-60 min"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q3_A4",
                                "display": "> 1 hr"
                            }
                        }
                    ]
                },
                {
                    "linkId": "7eb053cd-cb2d-435f-8f55-f154645b55c4",
                    "code": [
                        {
                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                            "code": "QUES_EXERCISE_Q4"
                        }
                    ],
                    "text": "What type of exercise do you do?",
                    "type": "text",
                    "enableWhen": [
                        {
                            "question": "93137723-295f-4b28-9f97-fb58825b2cda",
                            "operator": "=",
                            "answerCoding": {
                                "code": "QUES_EXERCISE_Q3_A3",
                                "display": "40-60 min"
                            }
                        }
                    ],
                    "repeats": false,
                    "answerOption": [
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q4_A1",
                                "display": "TXT"
                            }
                        }
                    ]
                },
                {
                    "linkId": "c47a9e05-2b8d-4f31-9a6e-1d5b3c8f7e20",
                    "code": [
                        {
                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                            "code": "QUES_EXERCISE_Q5"
                        }
                    ],
                    "text": "When did you last exercise?",
                    "type": "date",
                    "repeats": false,
                    "answerOption": [
                        {
                            "valueCoding": {
                                "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                "code": "QUES_EXERCISE_Q5_A1",
                                "display": "DATE"
                            }
                        }
                    ]
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Questionnaire resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Questionnaire?name=exercise' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Questionnaire?name=exercise"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/Questionnaire?name=exercise&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Questionnaire?name=exercise&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Questionnaire?name=exercise&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "Questionnaire",
                        "id": "47a408d7-9f1d-4cfd-97c7-aa810df9ed39",
                        "name": "Exercise",
                        "status": "active",
                        "description": "No Description Provided",
                        "code": [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "404684003"
                            }
                        ],
                        "item": [
                            {
                                "linkId": "d82e29db-0cac-4b97-a5aa-9e81749686e2",
                                "code": [
                                    {
                                        "system": "http://snomed.info/sct",
                                        "code": "228448000"
                                    }
                                ],
                                "text": "Do you exercise on a regular basis?",
                                "type": "choice",
                                "repeats": false,
                                "answerOption": [
                                    {
                                        "valueCoding": {
                                            "system": "http://loinc.org",
                                            "code": "LA33-6",
                                            "display": "Yes"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://loinc.org",
                                            "code": "LA32-8",
                                            "display": "No"
                                        }
                                    }
                                ]
                            },
                            {
                                "linkId": "f2419de1-a208-4a3f-9d55-ba9bd5ed4ec2",
                                "code": [
                                    {
                                        "system": "http://snomed.info/sct",
                                        "code": "228449008"
                                    }
                                ],
                                "text": "In an average week, how many days do you exercise?",
                                "type": "choice",
                                "enableWhen": [
                                    {
                                        "question": "d82e29db-0cac-4b97-a5aa-9e81749686e2",
                                        "operator": "=",
                                        "answerCoding": {
                                            "code": "LA33-6",
                                            "display": "Yes"
                                        }
                                    }
                                ],
                                "repeats": false,
                                "answerOption": [
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q2_A1",
                                            "display": "0"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q2_A2",
                                            "display": "1"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q2_A3",
                                            "display": "2"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q2_A4",
                                            "display": "3"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q2_A5",
                                            "display": "4"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q2_A6",
                                            "display": "5"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q2_A7",
                                            "display": "6"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q2_A8",
                                            "display": "7"
                                        }
                                    }
                                ]
                            },
                            {
                                "linkId": "93137723-295f-4b28-9f97-fb58825b2cda",
                                "code": [
                                    {
                                        "system": "http://snomed.info/sct",
                                        "code": "255257008"
                                    }
                                ],
                                "text": "On the days when you exercised, for how long did you exercise?",
                                "type": "choice",
                                "enableWhen": [
                                    {
                                        "question": "d82e29db-0cac-4b97-a5aa-9e81749686e2",
                                        "operator": "=",
                                        "answerCoding": {
                                            "code": "LA33-6",
                                            "display": "Yes"
                                        }
                                    },
                                    {
                                        "question": "f2419de1-a208-4a3f-9d55-ba9bd5ed4ec2",
                                        "operator": "exists",
                                        "answerBoolean": true
                                    }
                                ],
                                "enableBehavior": "all",
                                "repeats": false,
                                "answerOption": [
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q3_A1",
                                            "display": "10-20 min"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q3_A2",
                                            "display": "20-40 min"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q3_A3",
                                            "display": "40-60 min"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q3_A4",
                                            "display": "> 1 hr"
                                        }
                                    }
                                ]
                            },
                            {
                                "linkId": "7eb053cd-cb2d-435f-8f55-f154645b55c4",
                                "code": [
                                    {
                                        "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                        "code": "QUES_EXERCISE_Q4"
                                    }
                                ],
                                "text": "What type of exercise do you do?",
                                "type": "text",
                                "enableWhen": [
                                    {
                                        "question": "93137723-295f-4b28-9f97-fb58825b2cda",
                                        "operator": "=",
                                        "answerCoding": {
                                            "code": "QUES_EXERCISE_Q3_A3",
                                            "display": "40-60 min"
                                        }
                                    }
                                ],
                                "repeats": false,
                                "answerOption": [
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q4_A1",
                                            "display": "TXT"
                                        }
                                    }
                                ]
                            },
                            {
                                "linkId": "c47a9e05-2b8d-4f31-9a6e-1d5b3c8f7e20",
                                "code": [
                                    {
                                        "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                        "code": "QUES_EXERCISE_Q5"
                                    }
                                ],
                                "text": "When did you last exercise?",
                                "type": "date",
                                "repeats": false,
                                "answerOption": [
                                    {
                                        "valueCoding": {
                                            "system": "http://schemas.example.canvasmedical.com/fhir/systems/internal",
                                            "code": "QUES_EXERCISE_Q5_A1",
                                            "display": "DATE"
                                        }
                                    }
                                ]
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# QuestionnaireResponse

Source: https://docs.canvasmedical.com/api/questionnaireresponse/

### 
A structured set of questions and their answers. The questions are ordered and grouped into coherent subsets, corresponding to the structure of the grouping of the questionnaire being responded to.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-questionnaireresponse.html>  
See this [article](https://help.canvasmedical.com/articles/7017593857-creating-questionnaires) for information about how to build questionnaires in Canvas.  
Questionnaires can map to four different commands in the Canvas UI depending on what the use case in charting is set to:
  - [Questionnaire](https://canvas-medical.help.usepylon.com/articles/5651999344-command-questionnaire)
  - [Structured Assessment](https://canvas-medical.help.usepylon.com/articles/8805008571-command-structured-assessment)
  - [Review of Systems](https://canvas-medical.help.usepylon.com/articles/9046024531-command-review-of-systems)
  - [Physical Exam](https://canvas-medical.help.usepylon.com/articles/1745103290-command-physical-exam)
QuestionnaireResponse resources contain answers to questions in a Questionnaire resource. Use the [Questionnaire search endpoint](/api/questionnaire/#search) to find Questionnaire resources.
#### Additional information
  - For responses collected outside Canvas, set `authored` to the time the answers were actually collected. When the request references no existing note or encounter, Canvas creates a new data note for the response and uses `authored` as that note's date of service. When it references one, the response is added to that note and the note's date of service is unchanged.
### Endpoints
post/QuestionnaireResponse get/QuestionnaireResponse/{id} put/QuestionnaireResponse/{id} get/QuestionnaireResponse
post
/QuestionnaireResponse
#### QuestionnaireResponse create
Create an QuestionnaireResponse resource.
### Attributes
resourceType
string
The FHIR Resource name.
extension
array[json]
Additional content defined by implementations  
Canvas supports a note identifier extension on this resource for create, read, update, and search interactions. The note identifier can be used with the [Canvas Note API](/api/note).  
**Important:** For create interactions, Canvas recommends sending the note identifier extension or the Encounter reference, but not both. If both are supplied, they must both refer to the same note.  
Click to view child attributes
url
string required
Reference that defines the content of this object.
**Value Options Supported:**
  - For note identifier we have a url of `http://schemas.canvasmedical.com/fhir/extensions/note-id`
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier
questionnaire
string
Form being answered.  
The `questionnaire` field contains an absolute URL to a Questionnaire, e.g. `https://fumage-example.canvasmedical.com/Questionnaire/ac1da1a4-ccc4-492e-a9e0-7f70a58c2129`. Questionnaire IDs can be obtained using the [Questionnaire search endpoint](/api/questionnaire/#search). Either the `questionnaire` attribute or the URL extension under `_questionnaire` must be provided.
_questionnaire
json
This attribute contains the extensions for the `questionnaire` attribute.
Click to view child attributes
extension
array[json]
Extensions on the `questionnaire` attribute. Supported extensions include questionnaire name and URL.
To create a QuestionnaireResponse that responds to a non-FHIR questionnaire, like an external PDF file, the URL extension must be provided, and the `questionnaire` attribute must be omitted. In this scenario, there is no `Questionnaire` resource referenced by the `questionnaire` attribute. Question text must be provided for each `item`, and only `valueString` answers are permitted.  
When a QuestionnaireResponse is created in this manner, it does **not** result in the insertion of a command into a note.
Click to view child attributes
url
string
Source of the definition of the extension code.
**Value Options Supported:**
  - http://hl7.org/fhir/StructureDefinition/display
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-extension-questionnaire-uri
valueString
string
Display name for the Questionnaire referenced by `questionnaire`
valueUri
string
The location where a non-FHIR questionnaire/survey form can be found.
status
string required
The position of the questionnaire response within its overall lifecycle.
**Value Options Supported:**
  - completed
subject
json required
The subject of the questions.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`
type
string
Type the reference refers to (e.g. "Patient")
encounter
json
Encounter created as part of.  
If `encounter` is provided, the QuestionnaireResponse will be added to the existing encounter (note). If it is not provided, a new data import note will be created. It will be inserted into the timeline using the timestamp passed in `authored`.  
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string required
The reference string of the encounter in the format of `"Encounter/cdbd6534-ba0d-4917-a5a6-6a2d46dcf0f7"`
type
string
Type the reference refers to (e.g. "Encounter")
authored
datetime
Note datetime of service where the answers are associated with in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.  
If omitted, the current timestamp will be used.
author
json
Person who received and recorded the answers.  
If omitted, then the built-in automation user **Canvas Bot** will be set as the author.  
Supported reference types for create operations are: **Patient** , **Practitioner**
Click to view child attributes
reference
string required
The reference string of the author in the format of `"Practitioner/cdbd6534-ba0d-4917-a5a6-6a2d46dcf0f7"`
type
string
Type the reference refers to (e.g. "Patient", "Practitioner")
item
array[json]
Groups and questions  
The `item` attribute contains the answers to the questions in the Questionnaire. The `item` attribute in QuestionnaireResponse corresponds to the `item` attribute in Questionnaire payload, and are related via the `linkId` attribute. If a question's answer is omitted, it will be left unanswered in Canvas. However, if it is a questionnaire tied to a scoring function, Canvas requires all questions to be answered in order to accurately score the Questionnaire.  
Each `item` must contain a `linkId` and `answer` attributes. The `answer` attribute is a list of answers for the question referred to by the `linkId`.  
Canvas supports the following question formats:  
• Free text  
• Single choice  
• Multiple choice  
• Date  
Answers to free text questions are provided as a `valueString`. Answers to decimal questions are provided as a `valueDecimal`. Answers to single and multiple choice questions are provided as a `valueCoding`. Answers to date questions are provided as a `valueDate`, an ISO 8601 calendar date (`YYYY-MM-DD`). See the request and response examples for more information.  
The following mappings show how the FHIR system URI is mapped to the Canvas system (FHIR -> Canvas):  
FHIR system uri| Canvas system value  
---|---  
http://loinc.org| LOINC  
http://snomed.info/sct| SNOMED  
http://canvasmedical.com| CANVAS  
http://www.ama-assn.org/go/cpt| CPT  
http://hl7.org/fhir/sid/icd-10| ICD-10  
http://schemas.{instance-name}.canvasmedical.com/fhir/systems/internal| INTERNAL  
Click to view child attributes
linkId
string required
A Canvas assigned identifier that uniquely identifies this question in Canvas. This linkId must only occur at most once in the payload. You can retrieve this from FHIR Questionnaire Search/Read
text
string
Human readable text of the question. This value is not stored for QuestionnaireResponse resources that respond to FHIR questionnaires (i.e. QuestionnaireResponse resources that have a value for `questionnaire`), but it is stored for (and is required by) QuestionnaireResponse resources that respond to questionnaires that are not represented by a FHIR resource, such as a PDF containing a set of questions. Required for QuestionnaireResponses that target an external questionnaire URL.
answer
array[json] required
A list of one or more answers to this question.
Click to view child attributes
valueString
string
For question where the answer is a free-text field (i.e. Questionnaire item type = "text"), then the list will contain a single object containing a valueString field with the response text.
valueDecimal
decimal
For question where the answer is a decimal (i.e. Questionnaire item type = "decimal"), then the list will contain a single object containing a valueDecimal field with the response value.
valueDate
date
For a question where the answer is a date (i.e. Questionnaire item type = "date"), then the list will contain a single object containing a valueDate field with the response date, as an ISO 8601 calendar date (YYYY-MM-DD).
valueCoding
json
For a question where the answer is a single or multiple choice selection (i.e. Questionnaire item `type` = "choice" and `repeats` is "false" for single or "true" for multiple), then the list will have one or more ValueCoding objects. You can retrieve these coding options in the Questionnaire Read/Search endpoint.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string required
The code of the answer.
display
string required
The display name of the coding.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
**Validation Errors**  
_Beware of ambiguous choices!_  
If the questionnaire contains a question with identical codings for different choices, Canvas will not know which of the choices were selected. In this case, Canvas will reject the request. For the request to succeed, each question must have a uniquely coded set of choices. Choice codings can be reused across questions, but not within them.If this scenario occurs, you will get the error message: `Question received a response option code: {code} that belongs to more than one option response`  
_More Coding Validation_  
The system is the `valueCoding` answer needs to match the system that the question specified in the Questionnaire Search Response. If it does not, you will get the error: `Question expects answer of code system {system} but {system} was given`  
If a code is passed that does not exist for that question in Canvas, you will get the error: `Question received an invalid response option code: {code}`  
_Answer Validation_  
For single or free text questions, if more than one answer is provided, you will get the error: `Question of type {type} is expecting at most one answer`  
For free text questions, the answer object must include a `valueString` or you will get the error: `Question of type TXT expects a valueString answer`  
For single or multiple choice questions, the answer objects must include a `valueCoding` or you will see one of these errors:  
`Question of type SING expects a valueCoding answer`  
`Question of type MULT expects a valueCoding answer`  
For date questions, the answer object must include a `valueDate` or you will get the error: `Question of type DATE expects a valueDate answer`
get
/QuestionnaireResponse/{id}
#### QuestionnaireResponse read
Read an QuestionnaireResponse resource.
### Path Parameters
id required
string
The unique identifier for the QuestionnaireResponse   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the QuestionnaireResponse.
extension
array[json]
Additional content defined by implementations  
Canvas supports a note identifier extension on this resource for create, read, update, and search interactions. The note identifier can be used with the [Canvas Note API](/api/note).  
**Important:** For create interactions, Canvas recommends sending the note identifier extension or the Encounter reference, but not both. If both are supplied, they must both refer to the same note.  
The Questionnaire permalink is included in the `extension` attribute. This will take you directly to the command in the patient's chart.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - For permalinks which have a url of `http://schemas.canvasmedical.com/fhir/extensions/questionnaire-permalink`
  - For note identifier we have a url of `http://schemas.canvasmedical.com/fhir/extensions/note-id`
valueString
string
The permalink extension will have a `valueString` returned that represents a url. This url will take you to the exact command in the Canvas UI the response is captured. It will look like `https://<customer-identifier>.canvasmedical.com/permalinks/v1/SW50ZXJ2aWV3OjUxOjc1NTU=`
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier
identifier
json
Unique id for this set of answers
Click to view child attributes
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/questionnaireresponse-identifier
value
string
The identifier value that is unique.
questionnaire
string
Form being answered.  
The `questionnaire` field contains an absolute URL to a Questionnaire, e.g. `https://fumage-example.canvasmedical.com/Questionnaire/ac1da1a4-ccc4-492e-a9e0-7f70a58c2129`. Questionnaire IDs can be obtained using the [Questionnaire search endpoint](/api/questionnaire/#search). Either the `questionnaire` attribute or the URL extension under `_questionnaire` must be provided.
_questionnaire
json
This attribute contains the extensions for the `questionnaire` attribute.
Click to view child attributes
extension
array[json]
Extensions on the `questionnaire` attribute. Supported extensions include questionnaire name and URL.
Click to view child attributes
url
string
Source of the definition of the extension code.
**Value Options Supported:**
  - http://hl7.org/fhir/StructureDefinition/display
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-extension-questionnaire-uri
valueString
string
Display name for the Questionnaire referenced by `questionnaire`
valueUri
string
The location where a non-FHIR questionnaire/survey form can be found.
status
string
The position of the questionnaire response within its overall lifecycle.
**Value Options Supported:**
  - completed
  - entered-in-error
  - in-progress
subject
json
The subject of the questions.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`
type
string
Type the reference refers to (e.g. "Patient")
encounter
json
Encounter created as part of.  
If `encounter` is provided, the QuestionnaireResponse will be added to the existing encounter (note). If it is not provided, a new data import note will be created. It will be inserted into the timeline using the timestamp passed in `authored`.  
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/cdbd6534-ba0d-4917-a5a6-6a2d46dcf0f7"`
type
string
Type the reference refers to (e.g. "Encounter")
authored
datetime
Note datetime of service where the answers are associated with in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.  
author
json
Person who received and recorded the answers.  
If omitted, then the built-in automation user **Canvas Bot** will be set as the author.  
Supported reference types for create operations are: **Patient** , **Practitioner**
Click to view child attributes
reference
string
The reference string of the author in the format of `"Practitioner/cdbd6534-ba0d-4917-a5a6-6a2d46dcf0f7"`
type
string
Type the reference refers to (e.g. "Patient", "Practitioner")
item
array[json]
Groups and questions  
The `item` attribute contains the answers to the questions in the Questionnaire. The `item` attribute in QuestionnaireResponse corresponds to the `item` attribute in Questionnaire payload, and are related via the `linkId` attribute. If a question's answer is omitted, it will be left unanswered in Canvas. However, if it is a questionnaire tied to a scoring function, Canvas requires all questions to be answered in order to accurately score the Questionnaire.  
Each `item` must contain a `linkId` and `answer` attributes. The `answer` attribute is a list of answers for the question referred to by the `linkId`.  
Canvas supports the following question formats:  
• Free text  
• Single choice  
• Multiple choice  
• Date  
Answers to free text questions are provided as a `valueString`. Answers to decimal questions are provided as a `valueDecimal`. Answers to single and multiple choice questions are provided as a `valueCoding`. Answers to date questions are provided as a `valueDate`, an ISO 8601 calendar date (`YYYY-MM-DD`). See the request and response examples for more information.  
The following mappings show how the FHIR system URI is mapped to the Canvas system (FHIR -> Canvas):  
FHIR system uri| Canvas system value  
---|---  
http://loinc.org| LOINC  
http://snomed.info/sct| SNOMED  
http://canvasmedical.com| CANVAS  
http://www.ama-assn.org/go/cpt| CPT  
http://hl7.org/fhir/sid/icd-10| ICD-10  
http://schemas.{instance-name}.canvasmedical.com/fhir/systems/internal| INTERNAL  
Click to view child attributes
linkId
string
A Canvas assigned identifier that uniquely identifies this question in Canvas. This linkId must only occur at most once in the payload. You can retrieve this from FHIR Questionnaire Search/Read
text
string
Human readable text of the question. This value is not stored for QuestionnaireResponse resources that respond to FHIR questionnaires (i.e. QuestionnaireResponse resources that have a value for `questionnaire`), but it is stored for (and is required by) QuestionnaireResponse resources that respond to questionnaires that are not represented by a FHIR resource, such as a PDF containing a set of questions. Required for QuestionnaireResponses that target an external questionnaire URL.
answer
array[json]
A list of one or more answers to this question.
Click to view child attributes
valueString
string
For question where the answer is a free-text field (i.e. Questionnaire item type = "text"), then the list will contain a single object containing a valueString field with the response text.
valueDecimal
decimal
For question where the answer is a decimal (i.e. Questionnaire item type = "decimal"), then the list will contain a single object containing a valueDecimal field with the response value.
valueDate
date
For a question where the answer is a date (i.e. Questionnaire item type = "date"), then the list will contain a single object containing a valueDate field with the response date, as an ISO 8601 calendar date (YYYY-MM-DD).
valueCoding
json
For a question where the answer is a single or multiple choice selection (i.e. Questionnaire item `type` = "choice" and `repeats` is "false" for single or "true" for multiple), then the list will have one or more ValueCoding objects. You can retrieve these coding options in the Questionnaire Read/Search endpoint.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the answer.
display
string
The display name of the coding.
item
array[json]
Nested questionnaire response items. This `item` attribute is nested underneath an `answer`, which means it contains response items to questions or groups that are nested under a question.
item
array[json]
Nested questionnaire response items. This `item` attribute is nested underneath another `item` attribute, meaning that the containing `item` represents a group. The attributes for nested items are the same as the attributes for items at the root level.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/QuestionnaireResponse/{id}
#### QuestionnaireResponse update
Update a QuestionnaireResponse resource.  
The only type of QuestionnaireResponse update interaction that is supported by Canvas is to mark an existing QuestionnaireResponse as **entered-in-error**. No changes to other fields will be processed.
### Attributes
resourceType
string
The FHIR Resource name.
id
string required
The identifier of the QuestionnaireResponse.
extension
array[json]
Additional content defined by implementations  
Canvas supports a note identifier extension on this resource for create, read, update, and search interactions. The note identifier can be used with the [Canvas Note API](/api/note).  
**Important:** For create interactions, Canvas recommends sending the note identifier extension or the Encounter reference, but not both. If both are supplied, they must both refer to the same note.  
Click to view child attributes
url
string required
Reference that defines the content of this object.
**Value Options Supported:**
  - For note identifier we have a url of `http://schemas.canvasmedical.com/fhir/extensions/note-id`
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier
questionnaire
string
Form being answered.  
The `questionnaire` field contains an absolute URL to a Questionnaire, e.g. `https://fumage-example.canvasmedical.com/Questionnaire/ac1da1a4-ccc4-492e-a9e0-7f70a58c2129`. Questionnaire IDs can be obtained using the [Questionnaire search endpoint](/api/questionnaire/#search). Either the `questionnaire` attribute or the URL extension under `_questionnaire` must be provided.
_questionnaire
json
This attribute contains the extensions for the `questionnaire` attribute.
Click to view child attributes
extension
array[json]
Extensions on the `questionnaire` attribute. Supported extensions include questionnaire name and URL.
Click to view child attributes
url
string
Source of the definition of the extension code.
**Value Options Supported:**
  - http://hl7.org/fhir/StructureDefinition/display
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-extension-questionnaire-uri
valueString
string
Display name for the Questionnaire referenced by `questionnaire`
valueUri
string
The location where a non-FHIR questionnaire/survey form can be found.
status
string required
The position of the questionnaire response within its overall lifecycle.
**Value Options Supported:**
  - entered-in-error
subject
json required
The subject of the questions.
Click to view child attributes
reference
string required
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`
type
string
Type the reference refers to (e.g. "Patient")
encounter
json
Encounter created as part of.  
If `encounter` is provided, the QuestionnaireResponse will be added to the existing encounter (note). If it is not provided, a new data import note will be created. It will be inserted into the timeline using the timestamp passed in `authored`.  
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string required
The reference string of the encounter in the format of `"Encounter/cdbd6534-ba0d-4917-a5a6-6a2d46dcf0f7"`
type
string
Type the reference refers to (e.g. "Encounter")
authored
datetime
Note datetime of service where the answers are associated with in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.  
author
json
Person who received and recorded the answers.  
If omitted, then the built-in automation user **Canvas Bot** will be set as the author.  
Supported reference types for create operations are: **Patient** , **Practitioner**
Click to view child attributes
reference
string required
The reference string of the author in the format of `"Practitioner/cdbd6534-ba0d-4917-a5a6-6a2d46dcf0f7"`
type
string
Type the reference refers to (e.g. "Patient", "Practitioner")
item
array[json]
Groups and questions  
The `item` attribute contains the answers to the questions in the Questionnaire. The `item` attribute in QuestionnaireResponse corresponds to the `item` attribute in Questionnaire payload, and are related via the `linkId` attribute. If a question's answer is omitted, it will be left unanswered in Canvas. However, if it is a questionnaire tied to a scoring function, Canvas requires all questions to be answered in order to accurately score the Questionnaire.  
Each `item` must contain a `linkId` and `answer` attributes. The `answer` attribute is a list of answers for the question referred to by the `linkId`.  
Canvas supports the following question formats:  
• Free text  
• Single choice  
• Multiple choice  
• Date  
Answers to free text questions are provided as a `valueString`. Answers to decimal questions are provided as a `valueDecimal`. Answers to single and multiple choice questions are provided as a `valueCoding`. Answers to date questions are provided as a `valueDate`, an ISO 8601 calendar date (`YYYY-MM-DD`). See the request and response examples for more information.  
The following mappings show how the FHIR system URI is mapped to the Canvas system (FHIR -> Canvas):  
FHIR system uri| Canvas system value  
---|---  
http://loinc.org| LOINC  
http://snomed.info/sct| SNOMED  
http://canvasmedical.com| CANVAS  
http://www.ama-assn.org/go/cpt| CPT  
http://hl7.org/fhir/sid/icd-10| ICD-10  
http://schemas.{instance-name}.canvasmedical.com/fhir/systems/internal| INTERNAL  
Click to view child attributes
linkId
string required
A Canvas assigned identifier that uniquely identifies this question in Canvas. This linkId must only occur at most once in the payload. You can retrieve this from FHIR Questionnaire Search/Read
text
string
Human readable text of the question. This value is not stored for QuestionnaireResponse resources that respond to FHIR questionnaires (i.e. QuestionnaireResponse resources that have a value for `questionnaire`), but it is stored for (and is required by) QuestionnaireResponse resources that respond to questionnaires that are not represented by a FHIR resource, such as a PDF containing a set of questions. Required for QuestionnaireResponses that target an external questionnaire URL.
answer
array[json] required
A list of one or more answers to this question.
Click to view child attributes
valueString
string
For question where the answer is a free-text field (i.e. Questionnaire item type = "text"), then the list will contain a single object containing a valueString field with the response text.
valueDecimal
decimal
For question where the answer is a decimal (i.e. Questionnaire item type = "decimal"), then the list will contain a single object containing a valueDecimal field with the response value.
valueDate
date
For a question where the answer is a date (i.e. Questionnaire item type = "date"), then the list will contain a single object containing a valueDate field with the response date, as an ISO 8601 calendar date (YYYY-MM-DD).
valueCoding
json
For a question where the answer is a single or multiple choice selection (i.e. Questionnaire item `type` = "choice" and `repeats` is "false" for single or "true" for multiple), then the list will have one or more ValueCoding objects. You can retrieve these coding options in the Questionnaire Read/Search endpoint.
Click to view child attributes
system
string required
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string required
The code of the answer.
display
string required
The display name of the coding.
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/QuestionnaireResponse
#### QuestionnaireResponse search
Search for QuestionnaireResponse resources.
### Query Parameters
****
_id
string
The identifier of the QuestionnaireResponse.
authored
datetime
Filter by the `authored` attribute. See [Date Filtering](/api/date-filtering) for more information.
patient
string
The patient that is the subject of the questionnaire response in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
questionnaire
string
The questionnaire the answers are provided for in the format "https://fumage-example.canvasmedical.com/Questionnaire/7eefd6fc-0000-44c2-8224-d95f0ceaa2fd".
questionnaire.code
string
Filters by the code and/or system of the associated questionnaire. You can search by just the code value or you can search by the system and code in the format `system|code` (e.g `http://snomed.info/sct|404684003`).
questionnaire.item.code
string
Filters by the code and/or system of questions in the questionnaire. You can search by just the code value or you can search by the system and code in the format `system|code` (e.g `http://snomed.info/sct|404684003`).
_sort
string
Triggers sorting of the results by a specific criteria. The results will be in ascending order unless you add a `-` in front to sort in descending order.
**Search Values Supported:**
  - _id
  - authored
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the QuestionnaireResponse.
extension
array[json]
Additional content defined by implementations  
Canvas supports a note identifier extension on this resource for create, read, update, and search interactions. The note identifier can be used with the [Canvas Note API](/api/note).  
**Important:** For create interactions, Canvas recommends sending the note identifier extension or the Encounter reference, but not both. If both are supplied, they must both refer to the same note.  
The Questionnaire permalink is included in the `extension` attribute. This will take you directly to the command in the patient's chart.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - For permalinks which have a url of `http://schemas.canvasmedical.com/fhir/extensions/questionnaire-permalink`
  - For note identifier we have a url of `http://schemas.canvasmedical.com/fhir/extensions/note-id`
valueString
string
The permalink extension will have a `valueString` returned that represents a url. This url will take you to the exact command in the Canvas UI the response is captured. It will look like `https://<customer-identifier>.canvasmedical.com/permalinks/v1/SW50ZXJ2aWV3OjUxOjc1NTU=`
valueId
string
The valueId field is used for the Note extension and will be the note's unique identifier
identifier
json
Unique id for this set of answers
Click to view child attributes
system
string
The namespace for the identifier value.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/questionnaireresponse-identifier
value
string
The identifier value that is unique.
questionnaire
string
Form being answered.  
The `questionnaire` field contains an absolute URL to a Questionnaire, e.g. `https://fumage-example.canvasmedical.com/Questionnaire/ac1da1a4-ccc4-492e-a9e0-7f70a58c2129`. Questionnaire IDs can be obtained using the [Questionnaire search endpoint](/api/questionnaire/#search). Either the `questionnaire` attribute or the URL extension under `_questionnaire` must be provided.
_questionnaire
json
This attribute contains the extensions for the `questionnaire` attribute.
Click to view child attributes
extension
array[json]
Extensions on the `questionnaire` attribute. Supported extensions include questionnaire name and URL.
Click to view child attributes
url
string
Source of the definition of the extension code.
**Value Options Supported:**
  - http://hl7.org/fhir/StructureDefinition/display
  - http://hl7.org/fhir/us/core/StructureDefinition/us-core-extension-questionnaire-uri
valueString
string
Display name for the Questionnaire referenced by `questionnaire`
valueUri
string
The location where a non-FHIR questionnaire/survey form can be found.
status
string
The position of the questionnaire response within its overall lifecycle.
**Value Options Supported:**
  - completed
  - entered-in-error
  - in-progress
subject
json
The subject of the questions.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`
type
string
Type the reference refers to (e.g. "Patient")
encounter
json
Encounter created as part of.  
If `encounter` is provided, the QuestionnaireResponse will be added to the existing encounter (note). If it is not provided, a new data import note will be created. It will be inserted into the timeline using the timestamp passed in `authored`.  
**Canvas does not currently support concurrent creation of resources on the same encounter.** Please avoid issuing concurrent requests that reference the same encounter to this endpoint, or to any other endpoints that reference encounters. It is OK to issue concurrent requests to these endpoints as long as the requests reference different encounters.
Click to view child attributes
reference
string
The reference string of the encounter in the format of `"Encounter/cdbd6534-ba0d-4917-a5a6-6a2d46dcf0f7"`
type
string
Type the reference refers to (e.g. "Encounter")
authored
datetime
Note datetime of service where the answers are associated with in ISO 8601 format like `"2022-03-19T14:54:12.194952+00:00"`.  
author
json
Person who received and recorded the answers.  
If omitted, then the built-in automation user **Canvas Bot** will be set as the author.  
Supported reference types for create operations are: **Patient** , **Practitioner**
Click to view child attributes
reference
string
The reference string of the author in the format of `"Practitioner/cdbd6534-ba0d-4917-a5a6-6a2d46dcf0f7"`
type
string
Type the reference refers to (e.g. "Patient", "Practitioner")
item
array[json]
Groups and questions  
The `item` attribute contains the answers to the questions in the Questionnaire. The `item` attribute in QuestionnaireResponse corresponds to the `item` attribute in Questionnaire payload, and are related via the `linkId` attribute. If a question's answer is omitted, it will be left unanswered in Canvas. However, if it is a questionnaire tied to a scoring function, Canvas requires all questions to be answered in order to accurately score the Questionnaire.  
Each `item` must contain a `linkId` and `answer` attributes. The `answer` attribute is a list of answers for the question referred to by the `linkId`.  
Canvas supports the following question formats:  
• Free text  
• Single choice  
• Multiple choice  
• Date  
Answers to free text questions are provided as a `valueString`. Answers to decimal questions are provided as a `valueDecimal`. Answers to single and multiple choice questions are provided as a `valueCoding`. Answers to date questions are provided as a `valueDate`, an ISO 8601 calendar date (`YYYY-MM-DD`). See the request and response examples for more information.  
The following mappings show how the FHIR system URI is mapped to the Canvas system (FHIR -> Canvas):  
FHIR system uri| Canvas system value  
---|---  
http://loinc.org| LOINC  
http://snomed.info/sct| SNOMED  
http://canvasmedical.com| CANVAS  
http://www.ama-assn.org/go/cpt| CPT  
http://hl7.org/fhir/sid/icd-10| ICD-10  
http://schemas.{instance-name}.canvasmedical.com/fhir/systems/internal| INTERNAL  
Click to view child attributes
linkId
string
A Canvas assigned identifier that uniquely identifies this question in Canvas. This linkId must only occur at most once in the payload. You can retrieve this from FHIR Questionnaire Search/Read
text
string
Human readable text of the question. This value is not stored for QuestionnaireResponse resources that respond to FHIR questionnaires (i.e. QuestionnaireResponse resources that have a value for `questionnaire`), but it is stored for (and is required by) QuestionnaireResponse resources that respond to questionnaires that are not represented by a FHIR resource, such as a PDF containing a set of questions. Required for QuestionnaireResponses that target an external questionnaire URL.
answer
array[json]
A list of one or more answers to this question.
Click to view child attributes
valueString
string
For question where the answer is a free-text field (i.e. Questionnaire item type = "text"), then the list will contain a single object containing a valueString field with the response text.
valueDecimal
decimal
For question where the answer is a decimal (i.e. Questionnaire item type = "decimal"), then the list will contain a single object containing a valueDecimal field with the response value.
valueDate
date
For a question where the answer is a date (i.e. Questionnaire item type = "date"), then the list will contain a single object containing a valueDate field with the response date, as an ISO 8601 calendar date (YYYY-MM-DD).
valueCoding
json
For a question where the answer is a single or multiple choice selection (i.e. Questionnaire item `type` = "choice" and `repeats` is "false" for single or "true" for multiple), then the list will have one or more ValueCoding objects. You can retrieve these coding options in the Questionnaire Read/Search endpoint.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://loinc.org
  - http://snomed.info/sct
  - http://canvasmedical.com
  - http://www.ama-assn.org/go/cpt
  - http://hl7.org/fhir/sid/icd-10
  - http://schemas.{customer_identifier}.canvasmedical.com/fhir/systems/internal
code
string
The code of the answer.
display
string
The display name of the coding.
item
array[json]
Nested questionnaire response items. This `item` attribute is nested underneath an `answer`, which means it contains response items to questions or groups that are nested under a question.
item
array[json]
Nested questionnaire response items. This `item` attribute is nested underneath another `item` attribute, meaning that the containing `item` represents a group. The attributes for nested items are the same as the attributes for items at the root level.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/QuestionnaireResponse' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "QuestionnaireResponse",
            "id": "e76e44b4-4e68-4f72-b1c3-1de528a3bb2a",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "questionnaire": "https://fumage-example.canvasmedical.com/Questionnaire/7eefd6fc-0000-44c2-8224-d95f0ceaa2fd",
            "status": "completed",
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/ffa0bd44-997f-4ad4-8782-1a6c0ef01f1c",
                "type": "Encounter"
            },
            "authored": "2022-12-19T18:11:20.914260+00:00",
            "author": {
                "reference": "Practitioner/9cdb7a92d6614dcfa7948f2143a9f8e8",
                "type": "Practitioner"
            },
            "item": [
                {
                    "linkId": "e2e5ddc3-a0ec-4a1b-9c53-bf2e2e990fe1",
                    "text": "Tobacco status",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "8517006",
                                "display": "Former user"
                            }
                        }
                    ]
                },
                {
                    "linkId": "d210dc3a-3427-4f58-8707-3f38393a8416",
                    "text": "Tobacco type",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722496004",
                                "display": "Cigarettes"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722498003",
                                "display": "eCigarette"
                            }
                        }
                    ]
                },
                {
                    "linkId": "a656c6c8-ecea-403f-a430-f80899f26914",
                    "text": "Tobacco comment",
                    "answer": [
                        {
                            "valueString": "Yep"
                        }
                    ]
                },
                {
                    "linkId": "b3f7c21d-5e48-4a9c-9d16-7a0c4e83f1b2",
                    "text": "If you quit smoking, what day?",
                    "answer": [
                        {
                            "valueDate": "2026-07-14"
                        }
                    ]
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/QuestionnaireResponse"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "QuestionnaireResponse",
            "id": "e76e44b4-4e68-4f72-b1c3-1de528a3bb2a",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "questionnaire": "https://fumage-example.canvasmedical.com/Questionnaire/7eefd6fc-0000-44c2-8224-d95f0ceaa2fd",
            "status": "completed",
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/ffa0bd44-997f-4ad4-8782-1a6c0ef01f1c",
                "type": "Encounter"
            },
            "authored": "2022-12-19T18:11:20.914260+00:00",
            "author": {
                "reference": "Practitioner/9cdb7a92d6614dcfa7948f2143a9f8e8",
                "type": "Practitioner"
            },
            "item": [
                {
                    "linkId": "e2e5ddc3-a0ec-4a1b-9c53-bf2e2e990fe1",
                    "text": "Tobacco status",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "8517006",
                                "display": "Former user"
                            }
                        }
                    ]
                },
                {
                    "linkId": "d210dc3a-3427-4f58-8707-3f38393a8416",
                    "text": "Tobacco type",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722496004",
                                "display": "Cigarettes"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722498003",
                                "display": "eCigarette"
                            }
                        }
                    ]
                },
                {
                    "linkId": "a656c6c8-ecea-403f-a430-f80899f26914",
                    "text": "Tobacco comment",
                    "answer": [
                        {
                            "valueString": "Yep"
                        }
                    ]
                },
                {
                    "linkId": "b3f7c21d-5e48-4a9c-9d16-7a0c4e83f1b2",
                    "text": "If you quit smoking, what day?",
                    "answer": [
                        {
                            "valueDate": "2026-07-14"
                        }
                    ]
                }
            ]
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/QuestionnaireResponse/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/QuestionnaireResponse/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "QuestionnaireResponse",
            "id": "e76e44b4-4e68-4f72-b1c3-1de528a3bb2a",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/questionnaire-permalink",
                    "valueString": "https://example.canvasmedical.com/permalinks/v1/YWJjZGVmZ2hpamtsbW5vcHFycwo"
                }
            ],
            "questionnaire": "https://fumage-example.canvasmedical.com/Questionnaire/7eefd6fc-0000-44c2-8224-d95f0ceaa2fd",
            "status": "completed",
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/ffa0bd44-997f-4ad4-8782-1a6c0ef01f1c",
                "type": "Encounter"
            },
            "authored": "2022-12-19T18:11:20.914260+00:00",
            "author": {
                "reference": "Practitioner/9cdb7a92d6614dcfa7948f2143a9f8e8",
                "type": "Practitioner"
            },
            "item": [
                {
                    "linkId": "e2e5ddc3-a0ec-4a1b-9c53-bf2e2e990fe1",
                    "text": "Tobacco status",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "8517006",
                                "display": "Former user"
                            }
                        }
                    ]
                },
                {
                    "linkId": "d210dc3a-3427-4f58-8707-3f38393a8416",
                    "text": "Tobacco type",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722496004",
                                "display": "Cigarettes"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722498003",
                                "display": "eCigarette"
                            }
                        }
                    ]
                },
                {
                    "linkId": "a656c6c8-ecea-403f-a430-f80899f26914",
                    "text": "Tobacco comment",
                    "answer": [
                        {
                            "valueString": "Yep"
                        }
                    ]
                },
                {
                    "linkId": "b3f7c21d-5e48-4a9c-9d16-7a0c4e83f1b2",
                    "text": "If you quit smoking, what day?",
                    "answer": [
                        {
                            "valueDate": "2026-07-14"
                        }
                    ]
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown QuestionnaireResponse resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/QuestionnaireResponse/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "QuestionnaireResponse",
            "id": "e76e44b4-4e68-4f72-b1c3-1de528a3bb2a",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "questionnaire": "https://fumage-example.canvasmedical.com/Questionnaire/7eefd6fc-0000-44c2-8224-d95f0ceaa2fd",
            "status": "entered-in-error",
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/ffa0bd44-997f-4ad4-8782-1a6c0ef01f1c",
                "type": "Encounter"
            },
            "authored": "2022-12-19T18:11:20.914260+00:00",
            "author": {
                "reference": "Practitioner/9cdb7a92d6614dcfa7948f2143a9f8e8",
                "type": "Practitioner"
            },
            "item": [
                {
                    "linkId": "e2e5ddc3-a0ec-4a1b-9c53-bf2e2e990fe1",
                    "text": "Tobacco status",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "8517006",
                                "display": "Former user"
                            }
                        }
                    ]
                },
                {
                    "linkId": "d210dc3a-3427-4f58-8707-3f38393a8416",
                    "text": "Tobacco type",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722496004",
                                "display": "Cigarettes"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722498003",
                                "display": "eCigarette"
                            }
                        }
                    ]
                },
                {
                    "linkId": "a656c6c8-ecea-403f-a430-f80899f26914",
                    "text": "Tobacco comment",
                    "answer": [
                        {
                            "valueString": "Yep"
                        }
                    ]
                },
                {
                    "linkId": "b3f7c21d-5e48-4a9c-9d16-7a0c4e83f1b2",
                    "text": "If you quit smoking, what day?",
                    "answer": [
                        {
                            "valueDate": "2026-07-14"
                        }
                    ]
                }
            ]
        }'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/QuestionnaireResponse/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        payload = {
            "resourceType": "QuestionnaireResponse",
            "id": "e76e44b4-4e68-4f72-b1c3-1de528a3bb2a",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                    "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                }
            ],
            "questionnaire": "https://fumage-example.canvasmedical.com/Questionnaire/7eefd6fc-0000-44c2-8224-d95f0ceaa2fd",
            "status": "entered-in-error",
            "subject": {
                "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                "type": "Patient"
            },
            "encounter": {
                "reference": "Encounter/ffa0bd44-997f-4ad4-8782-1a6c0ef01f1c",
                "type": "Encounter"
            },
            "authored": "2022-12-19T18:11:20.914260+00:00",
            "author": {
                "reference": "Practitioner/9cdb7a92d6614dcfa7948f2143a9f8e8",
                "type": "Practitioner"
            },
            "item": [
                {
                    "linkId": "e2e5ddc3-a0ec-4a1b-9c53-bf2e2e990fe1",
                    "text": "Tobacco status",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "8517006",
                                "display": "Former user"
                            }
                        }
                    ]
                },
                {
                    "linkId": "d210dc3a-3427-4f58-8707-3f38393a8416",
                    "text": "Tobacco type",
                    "answer": [
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722496004",
                                "display": "Cigarettes"
                            }
                        },
                        {
                            "valueCoding": {
                                "system": "http://snomed.info/sct",
                                "code": "722498003",
                                "display": "eCigarette"
                            }
                        }
                    ]
                },
                {
                    "linkId": "a656c6c8-ecea-403f-a430-f80899f26914",
                    "text": "Tobacco comment",
                    "answer": [
                        {
                            "valueString": "Yep"
                        }
                    ]
                },
                {
                    "linkId": "b3f7c21d-5e48-4a9c-9d16-7a0c4e83f1b2",
                    "text": "If you quit smoking, what day?",
                    "answer": [
                        {
                            "valueDate": "2026-07-14"
                        }
                    ]
                }
            ]
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown QuestionnaireResponse resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/QuestionnaireResponse?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/QuestionnaireResponse?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link": [
                {
                    "relation": "self",
                    "url": "/QuestionnaireResponse?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/QuestionnaireResponse?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/QuestionnaireResponse?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
                }
            ],
            "entry": [
                {
                    "resource": {
                        "resourceType": "QuestionnaireResponse",
                        "id": "e76e44b4-4e68-4f72-b1c3-1de528a3bb2a",
                        "extension": [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                                "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5"
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/questionnaire-permalink",
                                "valueString": "https://example.canvasmedical.com/permalinks/v1/YWJjZGVmZ2hpamtsbW5vcHFycwo"
                            }
                        ],
                        "questionnaire": "https://fumage-example.canvasmedical.com/Questionnaire/7eefd6fc-0000-44c2-8224-d95f0ceaa2fd",
                        "status": "completed",
                        "subject": {
                            "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0",
                            "type": "Patient"
                        },
                        "encounter": {
                            "reference": "Encounter/ffa0bd44-997f-4ad4-8782-1a6c0ef01f1c",
                            "type": "Encounter"
                        },
                        "authored": "2022-12-19T18:11:20.914260+00:00",
                        "author": {
                            "reference": "Practitioner/9cdb7a92d6614dcfa7948f2143a9f8e8",
                            "type": "Practitioner"
                        },
                        "item": [
                            {
                                "linkId": "e2e5ddc3-a0ec-4a1b-9c53-bf2e2e990fe1",
                                "text": "Tobacco status",
                                "answer": [
                                    {
                                        "valueCoding": {
                                            "system": "http://snomed.info/sct",
                                            "code": "8517006",
                                            "display": "Former user"
                                        }
                                    }
                                ]
                            },
                            {
                                "linkId": "d210dc3a-3427-4f58-8707-3f38393a8416",
                                "text": "Tobacco type",
                                "answer": [
                                    {
                                        "valueCoding": {
                                            "system": "http://snomed.info/sct",
                                            "code": "722496004",
                                            "display": "Cigarettes"
                                        }
                                    },
                                    {
                                        "valueCoding": {
                                            "system": "http://snomed.info/sct",
                                            "code": "722498003",
                                            "display": "eCigarette"
                                        }
                                    }
                                ]
                            },
                            {
                                "linkId": "a656c6c8-ecea-403f-a430-f80899f26914",
                                "text": "Tobacco comment",
                                "answer": [
                                    {
                                        "valueString": "Yep"
                                    }
                                ]
                            },
                            {
                                "linkId": "b3f7c21d-5e48-4a9c-9d16-7a0c4e83f1b2",
                                "text": "If you quit smoking, what day?",
                                "answer": [
                                    {
                                        "valueDate": "2026-07-14"
                                    }
                                ]
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Quickstart

Source: https://docs.canvasmedical.com/api/quickstart/

##  Base URL and finding your sandbox name 
FHIR API requests must be made against the `fumage-` subdomain for your instance, using the pattern `https://fumage-<sandbox-name>.canvasmedical.com`. The `<sandbox-name>` is the same name that appears in the URL when you log in to your Canvas instance (e.g. for `https://example-dev.canvasmedical.com` the sandbox name is `example-dev`, and the FHIR base URL is `https://fumage-example-dev.canvasmedical.com`).
Always send requests over `https`, including requests to the OAuth token endpoint. An `http` request is answered with a `301` redirect to `https`, and most HTTP clients resend a redirected `POST` as a `GET` without its body. A create request sent over `http` therefore comes back as a search instead of creating the resource, and a token request sent over `http` does not return a token.
The regular instance subdomain (`https://<sandbox-name>.canvasmedical.com`) does not serve FHIR endpoints — requests there return HTML 404 pages rather than FHIR responses. The FHIR API is available on development environments as well, with no additional provisioning required beyond OAuth client credentials.
##  Authentication 
To access our FHIR API, you will need to request an access token and refresh it periodically. You can refer to our [Authentication Documentation](/api/customer-authentication) and [Authentication Best Practices](/api/authentication-best-practices) to get you set up. Access tokens expire 10 hours after they are created. You can and should reuse access tokens to reduce the number of tokens that are valid at any given time.
> **Info:** The OAuth token endpoint (`/auth/token/`) lives on the regular instance host, not the fumage- FHIR host. Request tokens from `https://<sandbox-name>.canvasmedical.com/auth/token/` — requesting them against the fumage- subdomain returns a `Not Found` error.
> **Info:** There are currently no fixed rate limits on the FHIR API or on SDK SimpleAPI endpoints. However, because FHIR requests are served by your underlying Canvas instance, very high-volume polling can affect the stability of that instance. Caching access tokens and using webhooks instead of polling are recommended to keep request volume manageable.
##  Data written through the FHIR API is committed 
Every create and update through the FHIR API records its data in a committed state, the same as data a provider has committed in a note. The FHIR API has no way to stage data for review first, such as a questionnaire whose answers are pre-filled but still editable.
To originate or stage data that a provider reviews and commits later, use the Plugin SDK instead: originate [commands](/sdk/commands/) in a note. If an external system needs an HTTP entry point for this, expose one with a [SimpleAPI](/sdk/handlers-simple-api-http/) endpoint in your plugin that originates the commands.
##  Create a patient 
Let's start by creating a patient. we've gone ahead and generated some boilerplate Patient info that includes all of the minimum required parameters for a Create a Patient request.
    ```shell
    curl -i --location 'https://fumage-<sandbox-name>.canvasmedical.com/Patient' \
         --header 'Authorization: Bearer <bearer-token>' \
         --header 'Content-Type: application/json' \
         --data '{
            "resourceType": "Patient",
            "extension": [
                {
                    "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                    "valueCode": "F"
                }
            ],
            "gender": "female",
            "active": true,
            "name": [
                {
                    "use": "official",
                    "family": "Mitko",
                    "given": [
                        "Salina"
                    ]
                }
            ],
            "birthDate": "1949-11-13"
        }'
    ```
To execute this command, first:
Replace  with your sandbox name Replace  with your Bearer token you learned about above in the Authentication Section Hit enter and your first patient, Salina Mitko, is created!
Navigate to the Canvas UI (sandbox or production instance) and log in using the credentials provided, search for Salina in the top-left search box and visit the first search result to find her chart.
For more detail about making Patient Create requests, check out the API documentation for Patient Create.
> **Info:** As part of the request's response, you will see a patient ID within the location: header. Copy the ID value between Patient/ and / history - you will need it to create an appointment in the next step.  
>   
>  Also to note that ID will match the ID you will find in your browser when you navigate to the patient's chart: https://{customer}.canvasmedical.com/patient/{patientID}
##  Create an Appointment 
We have our first patient and now want to book their first appointment. But before we can book their appointment we will need to find a practitioner.
If you are using one of our canvas sandboxes, there will already be a demo staff member loaded in the instance.
Run the following request to find the list of Practitioners in your organization. Again you will need to replace the  and  with the same values you used to create your patient above.
    ```shell
    curl --location 'https://fumage-<sandbox-name>.canvasmedical.com/Practitioner' \
    --header 'Content-Type: application/fhir+json' \
    --header 'Authorization: Bearer <bearer-token>' | jq
    ```
You will then get a response similar to:
    ```shell
    {
      "resourceType" : "Bundle",
      "type" : "searchset",
      "total" : 1,
      "entry" : [
        {
          "resource" : {
            "resourceType" : "Practitioner",
            "id" : "e766816672f34a5b866771c773e38f3c",
            "identifier" : [
              {
                "system" : "http://hl7.org/fhir/sid/us-npi",
                "value" : "1834494258"
              }
            ],
            "name" : [
              {
                "use" : "usual",
                "text" : "Youta Priti MD",
                "family" : "Priti",
                "given" : [
                  "Youta"
                ]
              }
            ]
          }
        }
      ]
    }
    ```
Copy down the value for "id". This is the Practitioner ID you will need to create your first appointment.
Now we have our Patient ID and Practitioner ID. We're ready to create our first appointment.
Now lets set up the cURL command to create the appointment. Again you will need to replace the  and . Then replace  and  with the values copied in the last two requests. This appointment will create a Telehealth Appointment. You might want to update the start and end dates to be today's date for easy find-ability on the calendar view.
    ```shell
    curl -i --location 'https://fumage-<sandbox-name>.canvasmedical.com/Appointment' \
      --header 'Authorization: Bearer <bearer-token>' \
      --header 'Content-Type: application/json' \
      --data '{
        "resourceType": "Appointment",
        "status": "booked",
        "appointmentType": {
            "coding": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "448337001",
                    "display": "Telemedicine consultation with patient (procedure)"
                }
            ]
        },
        "description": "Weekly check-in.",
        "supportingInformation" : [
          {
            "reference" : "Location/1"
          }
        ],
        "start": "2022-02-19T13:30:00.000Z",
        "end": "2022-02-19T14:00:00.000Z",
        "participant": [
            {
                "actor": {
                    "reference": "Practitioner/<practitioner-id>"
                },
                "status": "accepted"
            },
            {
                "actor": {
                    "reference": "Patient/<patient-id>"
                },
                "status": "accepted"
            }
        ]
    }'
    ```
If you navigate to the correct date you used for start and end in the request above on the Schedule of your Canvas home page, you will see your first appointment. You should also be able to see the appointment when navigating to the patient's chart.
For more detail about making Appointment Create requests, check out the API documentation for [Appointment Create](ref:create) .

---

# RelatedPerson

Source: https://docs.canvasmedical.com/api/relatedperson/

### 
Information about a person that is involved in the care for a patient, but who is not the target of healthcare, nor has a formal responsibility in the care process.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-relatedperson.html>
### Endpoints
get/RelatedPerson/{id} get/RelatedPerson
get
/RelatedPerson/{id}
#### RelatedPerson read
Read a RelatedPerson resource.
### Path Parameters
id required
string
The unique identifier for the RelatedPerson   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the RelatedPerson.
active
boolean
Whether this related person's record is in active use.
patient
json
The patient this person is related to.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
relationship
array[json]
The nature of the relationship.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-RoleCode
  - Empty string
code
string
The code of the relationship.  
Values are nominally from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html), but custom contact categories can be used as well.
display
string
The display name of the coding.  
Values are nominally from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html), but custom contact categories can be used as well.
name
array[json]
A name associated with the person.
Click to view child attributes
text
string
Text representation of the full name.  
If the RelatedPerson is a patient contact but not a Patient on Canvas, this attribute will be populated.  
If the RelatedPerson is a Patient on Canvas, this attribute will not be populated; instead the `family`, `given`, `prefix`, and `suffix` attributes will be provided.
family
string
Family name (often called 'Surname').
given
array[string]
Given names (not always 'first'). Includes middle names.  
This repeating element order: Given Names appear in the correct order for presenting the name.
prefix
array[string]
Parts that come before the name.
suffix
array[string]
Parts that come after the name.
telecom
array[json]
Contact details for the individual.
Click to view child attributes
system
string
Supported values are **phone** , **fax** , **email** , **pager** , **url** , **sms** , and **other**.
value
string
Free text string of the value for this contact point.
use
string
Supported values are **home** , **work** , **temp** , **old** and **mobile**.
address
array[json]
Address where the related person can be contacted or visited
Click to view child attributes
use
string
Supported values are **home** , **work** , **temp** and **old**.
type
string
Supported values are **both** , **physical** and **postal**.
line
array[string]
List of strings. The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.
city
string
String representing the city of the address.
district
string
District (e.g., county) of the address.
state
string
2 letter state abbreviation of the address.
postalCode
string
The 5 digit postal code of the address.
country
string
The ISO 3166 2 letter country code.
period
json
Click to view child attributes
start
date
Starting date with inclusive boundary
end
date
End date with inclusive boundary, if not ongoing
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/RelatedPerson
#### RelatedPerson search
Search for RelatedPerson resources.
### Query Parameters
****
_id
string
The identifier of the RelatedPerson.
patient
string
The patient reference associated with the RelatedPerson in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the RelatedPerson.
active
boolean
Whether this related person's record is in active use.
patient
json
The patient this person is related to.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Patient").
relationship
array[json]
The nature of the relationship.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system url of the coding.
**Value Options Supported:**
  - http://terminology.hl7.org/CodeSystem/v3-RoleCode
  - Empty string
code
string
The code of the relationship.  
Values are nominally from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html), but custom contact categories can be used as well.
display
string
The display name of the coding.  
Values are nominally from the [PatientRelationshipType ValueSet](https://hl7.org/fhir/R4/valueset-relatedperson-relationshiptype.html), but custom contact categories can be used as well.
name
array[json]
A name associated with the person.
Click to view child attributes
text
string
Text representation of the full name.  
If the RelatedPerson is a patient contact but not a Patient on Canvas, this attribute will be populated.  
If the RelatedPerson is a Patient on Canvas, this attribute will not be populated; instead the `family`, `given`, `prefix`, and `suffix` attributes will be provided.
family
string
Family name (often called 'Surname').
given
array[string]
Given names (not always 'first'). Includes middle names.  
This repeating element order: Given Names appear in the correct order for presenting the name.
prefix
array[string]
Parts that come before the name.
suffix
array[string]
Parts that come after the name.
telecom
array[json]
Contact details for the individual.
Click to view child attributes
system
string
Supported values are **phone** , **fax** , **email** , **pager** , **url** , **sms** , and **other**.
value
string
Free text string of the value for this contact point.
use
string
Supported values are **home** , **work** , **temp** , **old** and **mobile**.
address
array[json]
Address where the related person can be contacted or visited
Click to view child attributes
use
string
Supported values are **home** , **work** , **temp** and **old**.
type
string
Supported values are **both** , **physical** and **postal**.
line
array[string]
List of strings. The first item in the list will be address line 1 in Canvas. The rest of the items in the list will be concatenated to be address line 2.
city
string
String representing the city of the address.
district
string
District (e.g., county) of the address.
state
string
2 letter state abbreviation of the address.
postalCode
string
The 5 digit postal code of the address.
country
string
The ISO 3166 2 letter country code.
period
json
Click to view child attributes
start
date
Starting date with inclusive boundary
end
date
End date with inclusive boundary, if not ongoing
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/RelatedPerson/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/RelatedPerson/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "RelatedPerson",
          "id": "3fcea5ee-8961-43b4-9d47-3e8a2a625e95",
          "active": true,
          "patient": {
            "reference": "Patient/7982b53c2c35427fbb70afceb83145f8",
            "type": "Patient"
          },
          "relationship": [
            {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                  "code": "ITWINSIS",
                  "display": "identical twin sister"
                }
              ]
            }
          ],
          "name": [
            {
              "family": "Solis",
              "given": [
                "Terry"
              ]
            }
          ],
          "telecom": [
            {
              "system": "phone",
              "value": "5555555555",
              "use": "home"
            },
            {
              "system": "email",
              "value": "solisterry@example.net",
              "use": "home"
            }
          ],
          "address": [
            {
              "use": "home",
              "type": "both",
              "line": [
                "498 Frank Fields Suite 770"
              ],
              "city": "Taylorbury",
              "state": "RI",
              "postalCode": "90298",
              "country": "us"
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown RelatedPerson resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/RelatedPerson?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/RelatedPerson?patient=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Bundle",
          "type": "searchset",
          "total": 1,
          "link": [
            {
              "relation": "self",
              "url": "/RelatedPerson?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
            },
            {
              "relation": "first",
              "url": "/RelatedPerson?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
            },
            {
              "relation": "last",
              "url": "/RelatedPerson?patient=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0"
            }
          ],
          "entry": [
            {
              "resource": {
                "resourceType": "RelatedPerson",
                "id": "3fcea5ee-8961-43b4-9d47-3e8a2a625e95",
                "active": true,
                "patient": {
                  "reference": "Patient/7982b53c2c35427fbb70afceb83145f8",
                  "type": "Patient"
                },
                "relationship": [
                  {
                    "coding": [
                      {
                        "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                        "code": "ITWINSIS",
                        "display": "identical twin sister"
                      }
                    ]
                  }
                ],
                "name": [
                  {
                    "family": "Solis",
                    "given": [
                      "Terry"
                    ]
                  }
                ],
                "telecom": [
                  {
                    "system": "phone",
                    "value": "5555555555",
                    "use": "home"
                  },
                  {
                    "system": "email",
                    "value": "solisterry@example.net",
                    "use": "home"
                  }
                ],
                "address": [
                  {
                    "use": "home",
                    "type": "both",
                    "line": [
                      "498 Frank Fields Suite 770"
                    ],
                    "city": "Taylorbury",
                    "state": "RI",
                    "postalCode": "90298",
                    "country": "us"
                  }
                ]
              }
            }
          ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Schedule

Source: https://docs.canvasmedical.com/api/schedule/

### 
A container for slots of time that may be available for booking appointments  
<http://hl7.org/fhir/R4/schedule.html>  
Staff availability is denoted separately at each practice location associated with the organization record. The schedule **id** obtained from a Schedule search is used to search for bookable time slots for appointments.
### Endpoints
get/Schedule
get
/Schedule
#### Schedule search
Returns a list of location/practitioner combinations that is necessary for identifying open slots when booking appointments. This endpoint does not include any parameters.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the schedule.
text
json
Text summary of the resource, for human interpretation.
Click to view child attributes
status
The status of the narrative.
**Value Options Supported:**
  - generated
div
Limited xhtml content that contains the human readable text of the Schedule.
actor
array[json]
Resource(s) that availability information is being provided for.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/a39cafb9d1b445be95a2e2548e12a787"`.
type
string
Type the reference refers to (e.g. "Practitioner").
comment
string
Comments on availability. Currently the format for this comment will be `Schedule for <practitioner credentialed name> at <location>`
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Schedule' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Schedule"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
          {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 8,
            "entry": [
                {
                    "resource": {
                        "resourceType": "Schedule",
                        "id": "Location.1-Staff.e766816672f34a5b866771c773e38f3c",
                        "text": {
                            "status": "generated",
                            "div": "<div>Schedule for Youta Priti MD at California</div>"
                        },
                        "actor": [
                            {
                                "reference": "Practitioner/e766816672f34a5b866771c773e38f3c",
                                "type": "Practitioner"
                            }
                        ],
                        "comment": "Schedule for Youta Priti MD at California"
                    }
                },
                {
                    "resource": {
                        "resourceType": "Schedule",
                        "id": "Location.1-Staff.77bd177f81b14c9f943e1e30ed3dd989",
                        "text": {
                            "status": "generated",
                            "div": "<div>Schedule for Breanna Heller LMFT at California</div>"
                        },
                        "actor": [
                            {
                                "reference": "Practitioner/77bd177f81b14c9f943e1e30ed3dd989",
                                "type": "Practitioner"
                            }
                        ],
                        "comment": "Schedule for Breanna Heller LMFT at California"
                    }
                },
                {
                    "resource": {
                        "resourceType": "Schedule",
                        "id": "Location.1-Staff.f65c2bed0d8643cc808e25d5cfcf5070",
                        "text": {
                            "status": "generated",
                            "div": "<div>Schedule for Patrick van Nieuwenhuizen MD at California</div>"
                        },
                        "actor": [
                            {
                                "reference": "Practitioner/f65c2bed0d8643cc808e25d5cfcf5070",
                                "type": "Practitioner"
                            }
                        ],
                        "comment": "Schedule for Patrick van Nieuwenhuizen MD at California"
                    }
                },
                {
                    "resource": {
                        "resourceType": "Schedule",
                        "id": "Location.2-Staff.e766816672f34a5b866771c773e38f3c",
                        "text": {
                            "status": "generated",
                            "div": "<div>Schedule for Youta Priti MD at Tennessee</div>"
                        },
                        "actor": [
                            {
                                "reference": "Practitioner/e766816672f34a5b866771c773e38f3c",
                                "type": "Practitioner"
                            }
                        ],
                        "comment": "Schedule for Youta Priti MD at Tennessee"
                    }
                },
                {
                    "resource": {
                        "resourceType": "Schedule",
                        "id": "Location.2-Staff.3a182f42885645e0bc3d608e7c02aad8",
                        "text": {
                            "status": "generated",
                            "div": "<div>Schedule for Nikhil Krishnan MD at Tennessee</div>"
                        },
                        "actor": [
                            {
                                "reference": "Practitioner/3a182f42885645e0bc3d608e7c02aad8",
                                "type": "Practitioner"
                            }
                        ],
                        "comment": "Schedule for Nikhil Krishnan MD at Tennessee"
                    }
                },
                {
                    "resource": {
                        "resourceType": "Schedule",
                        "id": "Location.2-Staff.77bd177f81b14c9f943e1e30ed3dd989",
                        "text": {
                            "status": "generated",
                            "div": "<div>Schedule for Breanna Heller LMFT at Tennessee</div>"
                        },
                        "actor": [
                            {
                                "reference": "Practitioner/77bd177f81b14c9f943e1e30ed3dd989",
                                "type": "Practitioner"
                            }
                        ],
                        "comment": "Schedule for Breanna Heller LMFT at Tennessee"
                    }
                },
                {
                    "resource": {
                        "resourceType": "Schedule",
                        "id": "Location.2-Staff.f65c2bed0d8643cc808e25d5cfcf5070",
                        "text": {
                            "status": "generated",
                            "div": "<div>Schedule for Patrick van Nieuwenhuizen MD at Tennessee</div>"
                        },
                        "actor": [
                            {
                                "reference": "Practitioner/f65c2bed0d8643cc808e25d5cfcf5070",
                                "type": "Practitioner"
                            }
                        ],
                        "comment": "Schedule for Patrick van Nieuwenhuizen MD at Tennessee"
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Service Base URLs

Source: https://docs.canvasmedical.com/api/service-base-urls/

##  FHIR Base URLs 
We leverage the following format.
Customer Subdomain| FHIR Base URL  
---|---  
modernfamilypractice| `https://fumage-modernfamilypractice.canvasmedical.com`  
modernfamilypractice-dev| `https://fumage-modernfamilypractice-dev.canvasmedical.com`  
modernfamilypractice-staging| `https://fumage-modernfamilypractice-staging.canvasmedical.com`  
The global base URLs for our supported Canvas environments can be found using the links below. They are in FHIR R4 Bundle format conformant to the requirements specified in ASTP/ONC's HTI-1 Final Rule (g)(10) criterion.
**Non Production:** [https://docs.canvasmedical.com/assets/static/fhir-service-base-urls-nonproduction.json](/assets/static/fhir-service-base-urls-nonproduction.json)  
**Production:** [https://docs.canvasmedical.com/assets/static/fhir-service-base-urls-production.json](/assets/static/fhir-service-base-urls-production.json)

---

# ServiceRequest

Source: https://docs.canvasmedical.com/api/servicerequest/

### 
A request for a service to be performed for a patient, such as imaging, laboratory testing, or referral.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-servicerequest.html>  
ServiceRequest represents multiple Canvas services:
  - Imaging orders (e.g., CT, MRI, X-ray) - [Ordering imaging study](https://canvas-medical.help.usepylon.com/articles/2615916315-image-command) \- Laboratory orders (e.g., hemoglobin/hematocrit) - [Placing a lab order](https://canvas-medical.help.usepylon.com/articles/3065191197-placing-a-lab-order) \- Referrals (e.g., patient referral to specialist) - [Referring a patient](https://canvas-medical.help.usepylon.com/articles/8339414277-command-referrals) The ServiceRequest surface reflects these orders via standardized coding:
  - `category` uses SNOMED CT to represent the order category (e.g., Imaging, Laboratory procedure, Referral/Evaluation procedure) - `code` uses LOINC to represent the requested test/procedure
### Endpoints
get/ServiceRequest/{id} get/ServiceRequest
get
/ServiceRequest/{id}
#### ServiceRequest read
Read a ServiceRequest resource.
### Path Parameters
id required
string
The unique identifier for the ServiceRequest   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the ServiceRequest.
status
string
A code specifying the state of the ServiceRequest.
**Value Options Supported:**
  - active
  - completed
  - draft
  - entered-in-error
intent
string
Indicates the level of authorization/intent for the request. Canvas supports `order` for orders placed by a practitioner.
**Value Options Supported:**
  - order
category
array[json]
Categorical classification of the requested service (SNOMED CT). Common examples include Imaging, Laboratory procedure, and Referral/Evaluation procedure.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system URL of the coding.
**Value Options Supported:**
  - http://snomed.info/sct
code
string
The code value.
**Value Options Supported:**
  - 363679005
  - 108252007
  - 386053000
display
string
The display name of the coding.
**Value Options Supported:**
  - Imaging
  - Laboratory procedure
  - Evaluation procedure (procedure)
code
json
What service is being requested in a coded form (typically LOINC).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system URL of the coding.
**Value Options Supported:**
  - http://loinc.org
code
string
The code value that represents the respective Canvas service/order.
display
string
The display name of the coding.
subject
json
Who/what the service request is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/c4ff2ee2e41b4636b7d37ac7f9297d95"`.
type
string
Type the reference refers to (e.g. "Patient").
occurrencePeriod
json
The time window during which the service is to occur.
Click to view child attributes
start
datetime
Starting time with inclusive boundary of the requested service period.
end
datetime
End time with inclusive boundary of the requested service period.
authoredOn
datetime
When the request was authored in Canvas.
requester
json
Who/what is requesting the service (a Practitioner reference).
Click to view child attributes
reference
string
The reference string of the requester in the format of `"Practitioner/5eede137ecfe4124b8b773040e33be14"`.
type
string
Type the reference refers to (e.g. "Practitioner").
reasonReference
array[json]
Reason for the request. References Conditions from Canvas.
Click to view child attributes
reference
string
The reference string of the reason in the format of `"Condition/6700a428-6387-458d-8134-0702851da23c"`.
type
string
Type the reference refers to (e.g. "Condition").
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/ServiceRequest
#### ServiceRequest search
Search for ServiceRequest resources.
### Query Parameters
****
_id
string
The identifier of the ServiceRequest.
patient
string
The patient reference associated to the Service Request in the format `Patient/c4ff2ee2e41b4636b7d37ac7f9297d95`.
authored
date
Filter by **authoredOn**. See [Date Filtering](/api/date-filtering) for more information.
category
string
Categorization of the request (SNOMED CT). Filters by `category.coding` code and/or system. You can search by code alone or `system|code`.
**Search Values Supported:**
  - http://snomed.info/sct|363679005
  - http://snomed.info/sct|108252007
  - http://snomed.info/sct|386053000
code
string
What is being requested (typically LOINC). Filters by `code.coding` code and/or system. You can search by code alone or `system|code`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
The identifier of the ServiceRequest.
status
string
A code specifying the state of the ServiceRequest.
**Value Options Supported:**
  - active
  - completed
  - draft
  - entered-in-error
intent
string
Indicates the level of authorization/intent for the request. Canvas supports `order` for orders placed by a practitioner.
**Value Options Supported:**
  - order
category
array[json]
Categorical classification of the requested service (SNOMED CT). Common examples include Imaging, Laboratory procedure, and Referral/Evaluation procedure.
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system URL of the coding.
**Value Options Supported:**
  - http://snomed.info/sct
code
string
The code value.
**Value Options Supported:**
  - 363679005
  - 108252007
  - 386053000
display
string
The display name of the coding.
**Value Options Supported:**
  - Imaging
  - Laboratory procedure
  - Evaluation procedure (procedure)
code
json
What service is being requested in a coded form (typically LOINC).
Click to view child attributes
coding
array[json]
Code defined by a terminology system.
Click to view child attributes
system
string
The system URL of the coding.
**Value Options Supported:**
  - http://loinc.org
code
string
The code value that represents the respective Canvas service/order.
display
string
The display name of the coding.
subject
json
Who/what the service request is for.
Click to view child attributes
reference
string
The reference string of the subject in the format of `"Patient/c4ff2ee2e41b4636b7d37ac7f9297d95"`.
type
string
Type the reference refers to (e.g. "Patient").
occurrencePeriod
json
The time window during which the service is to occur.
Click to view child attributes
start
datetime
Starting time with inclusive boundary of the requested service period.
end
datetime
End time with inclusive boundary of the requested service period.
authoredOn
datetime
When the request was authored in Canvas.
requester
json
Who/what is requesting the service (a Practitioner reference).
Click to view child attributes
reference
string
The reference string of the requester in the format of `"Practitioner/5eede137ecfe4124b8b773040e33be14"`.
type
string
Type the reference refers to (e.g. "Practitioner").
reasonReference
array[json]
Reason for the request. References Conditions from Canvas.
Click to view child attributes
reference
string
The reference string of the reason in the format of `"Condition/6700a428-6387-458d-8134-0702851da23c"`.
type
string
Type the reference refers to (e.g. "Condition").
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/ServiceRequest/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/ServiceRequest/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "ServiceRequest",
            "id": "a47c7b0e-bbb4-42cd-bc4a-df259d148ea1",
            "status": "active",
            "intent": "order",
            "category": [
              {
                "coding": [
                  {
                    "system": "http://snomed.info/sct",
                    "code": "363679005",
                    "display": "Imaging"
                  }
                ]
              }
            ],
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "24627-2",
                  "display": "CT Chest"
                }
              ]
            },
            "subject": {
              "reference": "Patient/c4ff2ee2e41b4636b7d37ac7f9297d95",
              "type": "Patient"
            },
            "occurrencePeriod": {
              "start": "2025-10-01T09:00:00+00:00",
              "end": "2025-10-01T09:30:00+00:00"
            },
            "authoredOn": "2025-09-30T19:12:25.073749+00:00",
            "requester": {
              "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
              "type": "Practitioner"
            },
            "reasonReference": [
              {
                "reference": "Condition/6700a428-6387-458d-8134-0702851da23c"
              }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown ServiceRequest resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/ServiceRequest?patient=Patient/c4ff2ee2e41b4636b7d37ac7f9297d95' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/ServiceRequest?patient=Patient/c4ff2ee2e41b4636b7d37ac7f9297d95"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Bundle",
          "type": "searchset",
          "total": 3,
          "link": [
            {
              "relation": "self",
              "url": "/ServiceRequest?patient=Patient%2Fc4ff2ee2e41b4636b7d37ac7f9297d95&_count=10&_offset=0"
            },
            {
              "relation": "first",
              "url": "/ServiceRequest?patient=Patient%2Fc4ff2ee2e41b4636b7d37ac7f9297d95&_count=10&_offset=0"
            },
            {
              "relation": "last",
              "url": "/ServiceRequest?patient=Patient%2Fc4ff2ee2e41b4636b7d37ac7f9297d95&_count=10&_offset=0"
            }
          ],
          "entry": [
            {
              "resource": {
                "resourceType": "ServiceRequest",
                "id": "bef0e33b-5008-489b-aa32-873b99e1e523",
                "status": "active",
                "intent": "order",
                "category": [
                  {
                    "coding": [
                      {
                        "system": "http://snomed.info/sct",
                        "code": "363679005",
                        "display": "Imaging"
                      }
                    ]
                  }
                ],
                "code": {
                  "coding": [
                    {
                      "system": "http://loinc.org",
                      "code": "24627-2",
                      "display": "CT Chest"
                    }
                  ]
                },
                "subject": {
                  "reference": "Patient/c4ff2ee2e41b4636b7d37ac7f9297d95",
                  "type": "Patient"
                },
                "occurrencePeriod": {
                  "start": "2025-10-01T09:00:00+00:00",
                  "end": "2025-10-01T09:30:00+00:00"
                },
                "authoredOn": "2025-09-30T19:12:25.073749+00:00",
                "requester": {
                  "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
                  "type": "Practitioner"
                },
                "reasonReference": [
                  {
                    "reference": "Condition/6700a428-6387-458d-8134-0702851da23c"
                  }
                ]
              }
            },
            {
              "resource": {
                "resourceType": "ServiceRequest",
                "id": "5938a56b-0239-47c5-ad31-703ca5104bb5",
                "status": "draft",
                "intent": "order",
                "category": [
                  {
                    "coding": [
                      {
                        "system": "http://snomed.info/sct",
                        "code": "108252007",
                        "display": "Laboratory procedure"
                      }
                    ]
                  }
                ],
                "code": {
                  "coding": [
                    {
                      "system": "http://loinc.org",
                      "code": "4544-3",
                      "display": "Hematocrit"
                    },
                    {
                      "system": "http://loinc.org",
                      "code": "718-7",
                      "display": "Hemoglobin"
                    }
                  ]
                },
                "subject": {
                  "reference": "Patient/c4ff2ee2e41b4636b7d37ac7f9297d95",
                  "type": "Patient"
                },
                "occurrencePeriod": {
                  "start": "2025-10-01T09:00:00+00:00",
                  "end": "2025-10-01T09:30:00+00:00"
                },
                "authoredOn": "2025-09-30T19:12:25.100394+00:00",
                "requester": {
                  "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
                  "type": "Practitioner"
                },
                "reasonReference": [
                  {
                    "reference": "Condition/2db04232-de4f-4d59-8066-2e5cee1c2a1d"
                  }
                ]
              }
            },
            {
              "resource": {
                "resourceType": "ServiceRequest",
                "id": "db35b108-a9f3-4d70-bc76-4c4800bce005",
                "status": "completed",
                "intent": "order",
                "category": [
                  {
                    "coding": [
                      {
                        "system": "http://snomed.info/sct",
                        "code": "386053000",
                        "display": "Evaluation procedure (procedure)"
                      }
                    ]
                  }
                ],
                "code": {
                  "coding": [
                    {
                      "system": "http://loinc.org",
                      "code": "103696004",
                      "display": "Patient referral to specialist"
                    }
                  ]
                },
                "subject": {
                  "reference": "Patient/c4ff2ee2e41b4636b7d37ac7f9297d95",
                  "type": "Patient"
                },
                "occurrencePeriod": {
                  "start": "2025-10-01T09:00:00+00:00",
                  "end": "2025-10-01T09:30:00+00:00"
                },
                "authoredOn": "2025-09-30T19:12:25.121629+00:00",
                "requester": {
                  "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14",
                  "type": "Practitioner"
                },
                "reasonReference": [
                  {
                    "reference": "Condition/691a6afa-a450-425e-a151-26b20f595efb"
                  }
                ]
              }
            }
          ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Slot

Source: https://docs.canvasmedical.com/api/slot/

### 
A slot of time on a schedule that may be available for booking appointments.  
<http://hl7.org/fhir/R4/slot.html>  
All slots are determined through our Google Calendar integration. Find out how to set this up [here](https://help.canvasmedical.com/articles/6105998178-managing-provider-availability). On instances in the [Google Calendar Sync beta](/product-updates/google-calendar-sync/), busy time from the Google calendars a provider connects is left out of their slots, the same way booked appointments are.
### Endpoints
get/Slot
get
/Slot
#### Slot search
Search for available appointment slots
### Query Parameters
**A Slot Search requires a schedule search parameter.**
duration
integer
If included, the request will search for available appointment slots with the given duration value in minutes. If not provided, a duration of 20 minutes will be used.
end
date
If included, the request will search for available appointment slots up until this date. If not included, a week will be used as default (7 days from the start date).
schedule
string
The Schedule Resource that we are seeking a slot within. The [Schedule](/api/schedule) resource can be used to retrieve a list of Schedule ids.
start
date
If included, the request will search for available appointment slots on or after this date. If not included, the current UTC date will be used.
appointment-type
string
Filters by the code and system of the allowed appointment type (if specificied in admin). Use the format `system|code` (e.g `http://snomed.info/sct|185418009`).
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
schedule
json
The [Schedule](/api/schedule) resource that this slot belongs to.
Click to view child attributes
reference
string
The reference string of the schedule in the format of `"Schedule/Location.<location_id>-Staff.<staff_id>"`.
type
string
Type the reference refers to (e.g. "Schedule").
status
string
The status of the available slot. Canvas only returns slots that are available for booking, so this field will always be returned as **free**.
**Value Options Supported:**
  - free
start
datetime
Date/Time that the slot is to begin.
end
datetime
Date/Time that the slot is to conclude
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Slot?schedule=Location.2-Staff.3640cd20de8a470aa570a852859ac87e&start=2023-09-21&end=2023-09-23&duration=20' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Slot?schedule=Location.2-Staff.3640cd20de8a470aa570a852859ac87e&start=2023-09-21&end=2023-09-23&duration=20"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 3,
            "entry":
            [
                {
                    "resource":
                    {
                        "resourceType": "Slot",
                        "schedule":
                        {
                            "reference": "Schedule/Location.2-Staff.3640cd20de8a470aa570a852859ac87e",
                            "type": "Schedule"
                        },
                        "status": "free",
                        "start": "2023-09-21T08:45:00-07:00",
                        "end": "2023-09-21T09:05:00-07:00"
                    }
                },
                {
                    "resource":
                    {
                        "resourceType": "Slot",
                        "schedule":
                        {
                            "reference": "Schedule/Location.2-Staff.3640cd20de8a470aa570a852859ac87e",
                            "type": "Schedule"
                        },
                        "status": "free",
                        "start": "2023-09-21T13:45:00-07:00",
                        "end": "2023-09-21T14:05:00-07:00"
                    }
                },
                {
                    "resource":
                    {
                        "resourceType": "Slot",
                        "schedule":
                        {
                            "reference": "Schedule/Location.2-Staff.3640cd20de8a470aa570a852859ac87e",
                            "type": "Schedule"
                        },
                        "status": "free",
                        "start": "2023-09-22T09:15:00-07:00",
                        "end": "2023-09-22T09:35:00-07:00"
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Software Requirements

Source: https://docs.canvasmedical.com/api/software-requirements/

###  Mandatory Software Components 
In order to access the FHIR API, a REST client such as [Bruno](https://www.usebruno.com/), or a high-level language (Java, Python, etc) that can be used to make HTTP requests, is needed.
###  Mandatory Software Configuration 
In order to use the API, an application needs to be created in your Canvas instance as described in ["Customer Authentication".](/api/customer-authentication)
###  All Technical Requirements and Attributes Necessary for Registration 
See above ("Mandatory Software Configuration").

---

# Specimen

Source: https://docs.canvasmedical.com/api/specimen/

### 
A sample to be used for analysis.  
<https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-specimen.html>
### Endpoints
get/Specimen/{id} get/Specimen
get
/Specimen/{id}
#### Specimen read
Read a Specimen resource.
### Path Parameters
id required
string
The unique identifier for the Specimen   
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
id
string
Unique Canvas identifier for this resource.
type
json
Kind of material that forms the specimen.
Click to view child attributes
text
string
Free-text description of the specimen type (e.g. "Serum").
subject
json
The patient from whom the specimen was collected.
Click to view child attributes
reference
string
The patient reference in the format `Patient/<patient_id>`.
type
string
Type the reference refers to (e.g. `Patient`).
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Specimen
#### Specimen search
Search for Specimen resources.
### Query Parameters
****
_id
string
A Canvas-issued unique identifier for a specific Specimen.
patient
string
The patient reference associated to the Specimen using the format `Patient/<patient_id>`.
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
resourceType
string
The FHIR Resource name.
id
string
Unique Canvas identifier for this resource.
type
json
Kind of material that forms the specimen.
Click to view child attributes
text
string
Free-text description of the specimen type (e.g. "Serum").
subject
json
The patient from whom the specimen was collected.
Click to view child attributes
reference
string
The patient reference in the format `Patient/<patient_id>`.
type
string
Type the reference refers to (e.g. `Patient`).
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Specimen/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Specimen/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Specimen",
          "id": "0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d",
          "type": {
            "text": "Serum"
          },
          "subject": {
            "reference": "Patient/1c8c6f27551d4d01aa3bf2477a4d5259",
            "type": "Patient"
          }
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Specimen resource 'SPM-unknown'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Specimen?_id=0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d&patient=Patient/1c8c6f27551d4d01aa3bf2477a4d5259' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Specimen?_id=0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d&patient=Patient/1c8c6f27551d4d01aa3bf2477a4d5259"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
          "resourceType": "Bundle",
          "type": "searchset",
          "total": 1,
          "link": [
            {
              "relation": "self",
              "url": "/Specimen?_id=0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d&patient=Patient/1c8c6f27551d4d01aa3bf2477a4d5259&_count=10&_offset=0"
            },
            {
              "relation": "first",
              "url": "/Specimen?_id=0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d&patient=Patient/1c8c6f27551d4d01aa3bf2477a4d5259&_count=10&_offset=0"
            },
            {
              "relation": "last",
              "url": "/Specimen?_id=0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d&patient=Patient/1c8c6f27551d4d01aa3bf2477a4d5259&_count=10&_offset=0"
            }
          ],
          "entry": [
            {
              "resource": {
                "resourceType": "Specimen",
                "id": "0a5d9e1f-1c64-4d04-a2bb-2a58e34f9f6d",
                "type": {
                  "text": "Serum"
                },
                "subject": {
                  "reference": "Patient/1c8c6f27551d4d01aa3bf2477a4d5259",
                  "type": "Patient"
                }
              }
            }
          ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Task

Source: https://docs.canvasmedical.com/api/task/

### 
A task to be performed.  
<http://hl7.org/fhir/R4/task.html>   
To read more about tasks in Canvas see [this article](https://canvas-medical.help.usepylon.com/articles/8460447495-task-management).
### Endpoints
post/Task get/Task/{id} put/Task/{id} get/Task
post
/Task
#### Task create
Create a task.  
Tasks created through this FHIR Endpoint will display in the [patient chart via the tasks icon](https://canvas-medical.help.usepylon.com/articles/8460447495-task-management#tasks-in-the-patient-chart-12). Open tasks will also display in the [Task Panel](https://canvas-medical.help.usepylon.com/articles/8460447495-task-management#task-list-16).
### Attributes
extension
array[json]
Additional content defined by implementations  
  - Canvas supports assigning a task to a group/team. This optional field requires a reference to the team from the [FHIR Group](/api/group) endpoint. In the Canvas UI, this will display under the field **team** in the task card.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/task-group (This url will have an associated valueReference for the FHIR Group that this task is assigned to.)
valueReference
json
A reference to a FHIR Group resource that represents the canvas team assigned to the task.
Click to view child attributes
reference
string required
The reference string of the group in the format of `"Group/13f3941f-0b51-4409-9a2f-e2f0353b324e"`.
status
string required
The current status of the task.
**Value Options Supported:**
  - requested (In canvas this maps to a status of open.)
  - completed
  - cancelled (In canvas this maps to a status of closed.)
priority
string
The priority level of the task.
**Value Options Supported:**
  - stat
  - urgent
  - routine
description
string required
Human-readable explanation of task.
for
json
Beneficiary of the Task. This must be a [Patient](/api/patient) reference. If this attribute is supplied, the task will be visible on the patient's chart.
Click to view child attributes
reference
string required
The reference string of the patient in the format of `"Patient/cfd91cd3bd9046db81199aa8ee4afd7f"`.
authoredOn
datetime
Task Creation Date. If omitted from the message, it will default to the current timestamp at the time of ingestion.
requester
json required
Who is asking for task to be done. This must be a [Practitioner](/api/practitioner) reference.
Click to view child attributes
reference
string required
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
owner
json
Responsible individual. If supplied, this must be a [Practitioner](/api/practitioner) reference. In canvas this practitioner will become the staff member assignee.
Click to view child attributes
reference
string required
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
intent
enum [unknown] required
Distinguishes whether the task is a proposal, plan or full order. Canvas does not have a mapping for this field, so it should always be set to **unknown**.
restriction
json
Constraints on fulfillment tasks. In Canvas, this field is used to represent the due date for a task.
Click to view child attributes
period
json
When fulfillment sought.
Click to view child attributes
end
datetime
Due date for the task to be performed by.
note
array[json]
Comments made about the task.
For each comment, the following values can be specified:
  - The comment's text
  - Timestamp the comment was left. If omitted, this will default to current timestamp at data ingestion.
  - Reference to the practitioner that left the specific comment
Click to view child attributes
text
string required
The text of the task comment.
time
datetime
The timestamp the comment was left on the task. If omitted, this will default to current timestamp at data ingestion.
authorReference
json required
A reference to the Canvas Practitioner who authored the task comment.
Click to view child attributes
reference
string required
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
input
array[json]
Information used to perform the task. In Canvas this translates to added labels on a Task.
If the label doesn't exist in Canvas already, it will be created.   
When labels are created or updated through the Task endpoint, Canvas automatically scopes them to the Tasks module. If you reference an existing label that does not yet include the Tasks module, Canvas adds it during ingestion. Labels with an empty `modules` array remain global and continue to work across every module.
Click to view child attributes
type
json required
Label for the input.
Click to view child attributes
text
string required
**Value Options Supported:**
  - label
valueString
string required
Name of the label. If the label doesn't exist in Canvas already, it will be created.
### Responses
201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.  
Canvas returns the created resource's id as a UUID within the `location` header and a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Task/{id}
#### Task read
Read a Task resource.
### Path Parameters
id required
string
The unique identifier for the Task   
### Response Payload Attributes
id
string
The identifier of the task.
extension
array[json]
Additional content defined by implementations  
  - Canvas supports assigning a task to a group/team. This optional field requires a reference to the team from the [FHIR Group](/api/group) endpoint. In the Canvas UI, this will display under the field **team** in the task card.
  - When reading our a FHIR Task objects, a permalink URL to the task may be supplied. This link will take you directly to the task in the Canvas UI.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/task-permalink (This url will have an associated valueString with a url that will directly link to the task in the Canvas UI.)
  - http://schemas.canvasmedical.com/fhir/extensions/task-group (This url will have an associated valueReference for the FHIR Group that this task is assigned to.)
valueString
string
Supplied in the extensions associated to the permalink. This string will represent a URL to the task in the Canvas UI.
valueReference
json
A reference to a FHIR Group resource that represents the canvas team assigned to the task.
Click to view child attributes
reference
string
The reference string of the group in the format of `"Group/13f3941f-0b51-4409-9a2f-e2f0353b324e"`.
type
string
Type the reference refers to (e.g. "Group").
display
string
Display name of the FHIR Group.
status
string
The current status of the task.
**Value Options Supported:**
  - requested (In canvas this maps to a status of open.)
  - completed
  - cancelled (In canvas this maps to a status of closed.)
priority
string
The priority level of the task.
**Value Options Supported:**
  - stat
  - urgent
  - routine
description
string
Human-readable explanation of task.
for
json
Beneficiary of the Task. This must be a [Patient](/api/patient) reference. If this attribute is supplied, the task will be visible on the patient's chart.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/cfd91cd3bd9046db81199aa8ee4afd7f"`.
type
string
Type the reference refers to (e.g. "Patient").
authoredOn
datetime
Task Creation Date. If omitted from the message, it will default to the current timestamp at the time of ingestion.
lastModified
datetime
Task Update Date. Whenever the task receieves any updates, including comments, this field will be updated accordingly.
requester
json
Who is asking for task to be done. This must be a [Practitioner](/api/practitioner) reference.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
type
string
Type the reference refers to (e.g. "Practitioner").
owner
json
Responsible individual. If supplied, this must be a [Practitioner](/api/practitioner) reference. In canvas this practitioner will become the staff member assignee.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
type
string
Type the reference refers to (e.g. "Practitioner").
intent
enum [unknown]
Distinguishes whether the task is a proposal, plan or full order. Canvas does not have a mapping for this field, so it should always be set to **unknown**.
restriction
json
Constraints on fulfillment tasks. In Canvas, this field is used to represent the due date for a task.
Click to view child attributes
period
json
When fulfillment sought.
Click to view child attributes
end
datetime
Due date for the task to be performed by.
note
array[json]
Comments made about the task.
Click to view child attributes
text
string
The text of the task comment.
time
datetime
The timestamp the comment was left on the task. If omitted, this will default to current timestamp at data ingestion.
authorReference
json
A reference to the Canvas Practitioner who authored the task comment.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
type
string
Type the reference refers to (e.g. "Practitioner").
input
array[json]
Information used to perform the task. In Canvas this translates to added labels on a Task.
Click to view child attributes
type
json
Label for the input.
Click to view child attributes
text
string
**Value Options Supported:**
  - label
valueString
string
Name of the label. If the label doesn't exist in Canvas already, it will be created.
### Responses
200 OK
Request was successful.
### Errors
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Task/{id}
#### Task update
Update a task.  
Omitting the group `extension` and `authoredOn` fields in an update body does not delete the contents of that field. They will remain set to the last value they were assigned.  
Omitting the `description`, `owner`, `restriction` and `input` attributes will delete the contents of the field in the Canvas database. In order to have a Task keep the values in these fields after an update, they must be included.
### Attributes
id
string required
The identifier of the task.
extension
array[json]
Additional content defined by implementations  
  - Canvas supports assigning a task to a group/team. This optional field requires a reference to the team from the [FHIR Group](/api/group) endpoint. In the Canvas UI, this will display under the field **team** in the task card.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/task-group (This url will have an associated valueReference for the FHIR Group that this task is assigned to.)
valueReference
json
A reference to a FHIR Group resource that represents the canvas team assigned to the task.
Click to view child attributes
reference
string required
The reference string of the group in the format of `"Group/13f3941f-0b51-4409-9a2f-e2f0353b324e"`.
status
string required
The current status of the task.
**Value Options Supported:**
  - requested (In canvas this maps to a status of open.)
  - completed
  - cancelled (In canvas this maps to a status of closed.)
priority
string
The priority level of the task.
**Value Options Supported:**
  - stat
  - urgent
  - routine
description
string required
Human-readable explanation of task.
for
json
Beneficiary of the Task. This must be a [Patient](/api/patient) reference. If this attribute is supplied, the task will be visible on the patient's chart.
Click to view child attributes
reference
string required
The reference string of the patient in the format of `"Patient/cfd91cd3bd9046db81199aa8ee4afd7f"`.
authoredOn
datetime
Task Creation Date. If omitted from the message, it will default to the current timestamp at the time of ingestion.
requester
json required
Who is asking for task to be done. This must be a [Practitioner](/api/practitioner) reference.
Click to view child attributes
reference
string required
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
owner
json
Responsible individual. If supplied, this must be a [Practitioner](/api/practitioner) reference. In canvas this practitioner will become the staff member assignee.
Click to view child attributes
reference
string required
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
intent
enum [unknown] required
Distinguishes whether the task is a proposal, plan or full order. Canvas does not have a mapping for this field, so it should always be set to **unknown**.
restriction
json
Constraints on fulfillment tasks. In Canvas, this field is used to represent the due date for a task.
Click to view child attributes
period
json
When fulfillment sought.
Click to view child attributes
end
datetime
Due date for the task to be performed by.
note
array[json]
Comments made about the task.
For each comment, the following values can be specified:
  - The comment's text
  - Timestamp the comment was left. If omitted, this will default to current timestamp at data ingestion.
  - Reference to the practitioner that left the specific comment
Click to view child attributes
text
string required
The text of the task comment.
time
datetime
The timestamp the comment was left on the task. If omitted, this will default to current timestamp at data ingestion.
authorReference
json required
A reference to the Canvas Practitioner who authored the task comment.
Click to view child attributes
reference
string required
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
input
array[json]
Information used to perform the task. In Canvas this translates to added labels on a Task.
If the label doesn't exist in Canvas already, it will be created.   
When labels are created or updated through the Task endpoint, Canvas automatically scopes them to the Tasks module. If you reference an existing label that does not yet include the Tasks module, Canvas adds it during ingestion. Labels with an empty `modules` array remain global and continue to work across every module.
Click to view child attributes
type
json required
Label for the input.
Click to view child attributes
text
string required
**Value Options Supported:**
  - label
valueString
string required
Name of the label. If the label doesn't exist in Canvas already, it will be created.
### Responses
200 OK
The server has successfully processed the request.  
Canvas returns a `null` response body.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Task
#### Task search
Search for a task
### Query Parameters
****
_id
string
Search by a task id.
_sort
string
Triggers sorting of the results by a specific criteria.
**Search Values Supported:**
  - _id (sort in ascending order)
  - due-date (sort in ascending order)
  - -_id (sort in descending order)
  - -due-date (sort in descending order)
description
string
Search by description.
due
string
Filter by due date and time. See [Date Filtering](/api/date-filtering) for more information.
label
string
Search for a task with an associated label
modified
string
Filter by modified date and time. See [Date Filtering](/api/date-filtering) for more information.
owner
string
Search by task owner in the format `Practitioner/3a9cafb9d1b445be95a2e2548e12a787`.
patient
string
Search by patient in the format `Patient/a39cafb9d1b445be95a2e2548e12a787`.
priority
string
Search by task priority
**Search Values Supported:**
  - stat
  - urgent
  - routine
requester
string
Search by task requester in the format `Practitioner/3a9cafb9d1b445be95a2e2548e12a787`.
status
string
Search by task status
**Search Values Supported:**
  - requested
  - completed
  - cancelled
### Response Payload Attributes
resourceType
string
The FHIR Resource name.
type
string
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
total
integer
The number of resources that match the search parameter.
link
array[json]
Attributes relevant to pagination, see our [Pagination page](/api/pagination) for more detail.
Click to view child attributes
relation
enum [self|first|next|last]
The relation of the page search
url
The search url for the specific relation
entry
array[json]
The results bundle that lists out each object returned in the search
Click to view child attributes
resource
json
The attributes specific to the resource type, see the Attributes section below
### Attributes
id
string
The identifier of the task.
extension
array[json]
Additional content defined by implementations  
  - Canvas supports assigning a task to a group/team. This optional field requires a reference to the team from the [FHIR Group](/api/group) endpoint. In the Canvas UI, this will display under the field **team** in the task card.
  - When reading our a FHIR Task objects, a permalink URL to the task may be supplied. This link will take you directly to the task in the Canvas UI.
Click to view child attributes
url
string
Reference that defines the content of this object.
**Value Options Supported:**
  - http://schemas.canvasmedical.com/fhir/extensions/task-permalink (This url will have an associated valueString with a url that will directly link to the task in the Canvas UI.)
  - http://schemas.canvasmedical.com/fhir/extensions/task-group (This url will have an associated valueReference for the FHIR Group that this task is assigned to.)
valueString
string
Supplied in the extensions associated to the permalink. This string will represent a URL to the task in the Canvas UI.
valueReference
json
A reference to a FHIR Group resource that represents the canvas team assigned to the task.
Click to view child attributes
reference
string
The reference string of the group in the format of `"Group/13f3941f-0b51-4409-9a2f-e2f0353b324e"`.
type
string
Type the reference refers to (e.g. "Group").
display
string
Display name of the FHIR Group.
status
string
The current status of the task.
**Value Options Supported:**
  - requested (In canvas this maps to a status of open.)
  - completed
  - cancelled (In canvas this maps to a status of closed.)
priority
string
The priority level of the task.
**Value Options Supported:**
  - stat
  - urgent
  - routine
description
string
Human-readable explanation of task.
for
json
Beneficiary of the Task. This must be a [Patient](/api/patient) reference. If this attribute is supplied, the task will be visible on the patient's chart.
Click to view child attributes
reference
string
The reference string of the patient in the format of `"Patient/cfd91cd3bd9046db81199aa8ee4afd7f"`.
type
string
Type the reference refers to (e.g. "Patient").
authoredOn
datetime
Task Creation Date. If omitted from the message, it will default to the current timestamp at the time of ingestion.
lastModified
datetime
Task Update Date. Whenever the task receieves any updates, including comments, this field will be updated accordingly.
requester
json
Who is asking for task to be done. This must be a [Practitioner](/api/practitioner) reference.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
type
string
Type the reference refers to (e.g. "Practitioner").
owner
json
Responsible individual. If supplied, this must be a [Practitioner](/api/practitioner) reference. In canvas this practitioner will become the staff member assignee.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
type
string
Type the reference refers to (e.g. "Practitioner").
intent
enum [unknown]
Distinguishes whether the task is a proposal, plan or full order. Canvas does not have a mapping for this field, so it should always be set to **unknown**.
restriction
json
Constraints on fulfillment tasks. In Canvas, this field is used to represent the due date for a task.
Click to view child attributes
period
json
When fulfillment sought.
Click to view child attributes
end
datetime
Due date for the task to be performed by.
note
array[json]
Comments made about the task.
Click to view child attributes
text
string
The text of the task comment.
time
datetime
The timestamp the comment was left on the task. If omitted, this will default to current timestamp at data ingestion.
authorReference
json
A reference to the Canvas Practitioner who authored the task comment.
Click to view child attributes
reference
string
The reference string of the practitioner in the format of `"Practitioner/4150cd20de8a470aa570a852859ac87e"`.
type
string
Type the reference refers to (e.g. "Practitioner").
input
array[json]
Information used to perform the task. In Canvas this translates to added labels on a Task.
Click to view child attributes
type
json
Label for the input.
Click to view child attributes
text
string
**Value Options Supported:**
  - label
valueString
string
Name of the label. If the label doesn't exist in Canvas already, it will be created.
### Responses
200 OK
Request was successful.
### Errors
400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  - **curl**
        ```sh
        curl --request POST \
             --url 'https://fumage-example.canvasmedical.com/Task' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Task",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/task-group",
                    "valueReference": {
                        "reference": "Group/0c59ba86-dd40-4fde-8179-6e0b91dc617b"
                    }
                }
            ],
            "status": "requested",
            "priority": "urgent",
            "description": "Ask patient for new insurance information.",
            "for": { "reference": "Patient/cfd91cd3bd9046db81199aa8ee4afd7f" },
            "authoredOn": "2023-09-22T14:00:00.000Z",
            "requester": { "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e" },
            "owner": { "reference": "Practitioner/a02cbf2403e140f7bc9a355c6ed420f3" },
            "intent": "unknown",
            "restriction": { "period": { "end": "2023-09-23T14:00:00.000Z" } },
            "note": [
                {
                    "text": "Please call patient to update insurance information.",
                    "time": "2023-09-22T14:00:00.000Z",
                    "authorReference": { "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e" }
                }
            ],
            "input": [
                {
                    "type": { "text": "label" },
                    "valueString": "Urgent"
                }
            ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Task"
        payload = {
            "resourceType": "Task",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/task-group",
                    "valueReference": {
                        "reference": "Group/0c59ba86-dd40-4fde-8179-6e0b91dc617b"
                    }
                }
            ],
            "status": "requested",
            "priority": "urgent",
            "description": "Ask patient for new insurance information.",
            "for": { "reference": "Patient/cfd91cd3bd9046db81199aa8ee4afd7f" },
            "authoredOn": "2023-09-22T14:00:00.000Z",
            "requester": { "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e" },
            "owner": { "reference": "Practitioner/a02cbf2403e140f7bc9a355c6ed420f3" },
            "intent": "unknown",
            "restriction": { "period": { "end": "2023-09-23T14:00:00.000Z" } },
            "note": [
                {
                    "text": "Please call patient to update insurance information.",
                    "time": "2023-09-22T14:00:00.000Z",
                    "authorReference": { "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e" }
                }
            ],
            "input": [
                {
                    "type": { "text": "label" },
                    "valueString": "Urgent"
                }
            ]
        }
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **201**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Task/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Task/<id>"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
         {
            "resourceType": "Task",
            "id": "5f72fbcc-10ac-48ff-a2d2-02b229c38ce9",
            "extension":
            [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/task-group",
                    "valueReference":
                    {
                        "reference": "Group/0c59ba86-dd40-4fde-8179-6e0b91dc617b",
                        "type": "Group",
                        "display": "Payment Collection"
                    }
                },
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/task-permalink",
                    "valueString": "http://example.canvasmedical.com/permalinks/v1/VGFzazo4OTo3MA=="
                }
            ],
            "status": "completed",
            "priority": "urgent",
            "description": "Ask patient for new insurance information.",
            "for":
            {
                "reference": "Patient/cfd91cd3bd9046db81199aa8ee4afd7f",
                "type": "Patient"
            },
            "authoredOn": "2023-09-22T14:00:00+00:00",
            "lastModified": "2023-10-22T21:06:27.893521+00:00",
            "requester":
            {
                "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                "type": "Practitioner"
            },
            "owner":
            {
                "reference": "Practitioner/a02cbf2403e140f7bc9a355c6ed420f3",
                "type": "Practitioner"
            },
            "intent": "unknown",
            "restriction":
            {
                "period":
                {
                    "end": "2023-09-23T14:00:00+00:00"
                }
            },
            "note":
            [
                {
                    "authorReference":
                    {
                        "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                        "type": "Practitioner"
                    },
                    "time": "2023-09-22T14:00:00+00:00",
                    "text": "Please call patient to update insurance information."
                }
            ],
            "input":
            [
                {
                    "type":
                    {
                        "text": "label"
                    },
                    "valueString": "Urgent"
                }
            ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Task resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **curl**
        ```sh
        curl --request PUT \
             --url 'https://fumage-example.canvasmedical.com/Task/<id>' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json' \
             --header 'content-type: application/json' \
             --data '
        {
            "resourceType": "Task",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/task-group",
                    "valueReference": {
                        "reference": "Group/0c59ba86-dd40-4fde-8179-6e0b91dc617b"
                    }
                }
            ],
            "status": "completed",
            "priority": "urgent",
            "description": "Ask patient for new insurance information.",
            "for": { "reference": "Patient/cfd91cd3bd9046db81199aa8ee4afd7f" },
            "authoredOn": "2023-09-22T14:00:00.000Z",
            "requester": { "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e" },
            "owner": { "reference": "Practitioner/a02cbf2403e140f7bc9a355c6ed420f3" },
            "intent": "unknown",
            "restriction": { "period": { "end": "2023-09-23T14:00:00.000Z" } },
            "note": [
                {
                    "text": "Please call patient to update insurance information.",
                    "time": "2023-09-22T14:00:00.000Z",
                    "authorReference": { "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e" }
                }
            ],
            "input": [
                {
                    "type": { "text": "label" },
                    "valueString": "Urgent"
                }
            ]
        }
        '
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Task/<id>"
        payload = {
            "resourceType": "Task",
            "extension": [
                {
                    "url": "http://schemas.canvasmedical.com/fhir/extensions/task-group",
                    "valueReference": {
                        "reference": "Group/0c59ba86-dd40-4fde-8179-6e0b91dc617b"
                    }
                }
            ],
            "status": "completed",
            "priority": "urgent",
            "description": "Ask patient for new insurance information.",
            "for": { "reference": "Patient/cfd91cd3bd9046db81199aa8ee4afd7f" },
            "authoredOn": "2023-09-22T14:00:00.000Z",
            "requester": { "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e" },
            "owner": { "reference": "Practitioner/a02cbf2403e140f7bc9a355c6ed420f3" },
            "intent": "unknown",
            "restriction": { "period": { "end": "2023-09-23T14:00:00.000Z" } },
            "note": [
                {
                    "text": "Please call patient to update insurance information.",
                    "time": "2023-09-22T14:00:00.000Z",
                    "authorReference": { "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e" }
                }
            ],
            "input": [
                {
                    "type": { "text": "label" },
                    "valueString": "Urgent"
                }
            ]
        }
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "content-type": "application/json"
        }
        response = requests.put(url, json=payload, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        null
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```
  - **404**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-found",
              "details": {
                "text": "Unknown Task resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
              }
            }
          ]
        }
        ```
  - **405**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "not-supported",
              "details": {
                "text": "Operation is not supported"
              }
            }
          ]
        }
        ```
  - **412**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "conflict",
              "details": {
                "text": "Resource updated since If-Unmodified-Since date"
              }
            }
          ]
        }
        ```
  - **422**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "business-rule",
              "details": {
                "text": "Unprocessable entity"
              }
            }
          ]
        }
        ```
  - **curl**
        ```shell
        curl --request GET \
             --url 'https://fumage-example.canvasmedical.com/Task?owner=Practitioner/a02cbf2403e140f7bc9a355c6ed420f3&label=Urgent' \
             --header 'Authorization: Bearer <token>' \
             --header 'accept: application/json'
        ```
  - **python**
        ```python
        import requests
        url = "https://fumage-example.canvasmedical.com/Task?owner=Practitioner/a02cbf2403e140f7bc9a355c6ed420f3&label=Urgent"
        headers = {
            "accept": "application/json",
            "Authorization": "Bearer <token>"
        }
        response = requests.get(url, headers=headers)
        print(response.text)
        ```
  - **200**
        ```json
        {
            "resourceType": "Bundle",
            "type": "searchset",
            "total": 1,
            "link":
            [
                {
                    "relation": "self",
                    "url": "/Task?owner=Practitioner%2Fa02cbf2403e140f7bc9a355c6ed420f3&label=Urgent&_count=10&_offset=0"
                },
                {
                    "relation": "first",
                    "url": "/Task?owner=Practitioner%2Fa02cbf2403e140f7bc9a355c6ed420f3&label=Urgent&_count=10&_offset=0"
                },
                {
                    "relation": "last",
                    "url": "/Task?owner=Practitioner%2Fa02cbf2403e140f7bc9a355c6ed420f3&label=Urgent&_count=10&_offset=0"
                }
            ],
            "entry":
            [
                {
                    "resource":
                    {
                        "resourceType": "Task",
                        "id": "5f72fbcc-10ac-48ff-a2d2-02b229c38ce9",
                        "extension":
                        [
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/task-group",
                                "valueReference":
                                {
                                    "reference": "Group/0c59ba86-dd40-4fde-8179-6e0b91dc617b",
                                    "type": "Group",
                                    "display": "Payment Collection"
                                }
                            },
                            {
                                "url": "http://schemas.canvasmedical.com/fhir/extensions/task-permalink",
                                "valueString": "http://example.canvasmedical.com/permalinks/v1/VGFzazo4OTo3MA=="
                            }
                        ],
                        "status": "completed",
                        "priority": "urgent",
                        "description": "Ask patient for new insurance information.",
                        "for":
                        {
                            "reference": "Patient/cfd91cd3bd9046db81199aa8ee4afd7f",
                            "type": "Patient"
                        },
                        "authoredOn": "2023-09-22T14:00:00+00:00",
                        "lastModified": "2023-10-22T21:06:27.893521+00:00",
                        "requester":
                        {
                            "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                            "type": "Practitioner"
                        },
                        "owner":
                        {
                            "reference": "Practitioner/a02cbf2403e140f7bc9a355c6ed420f3",
                            "type": "Practitioner"
                        },
                        "intent": "unknown",
                        "restriction":
                        {
                            "period":
                            {
                                "end": "2023-09-23T14:00:00+00:00"
                            }
                        },
                        "note":
                        [
                            {
                                "authorReference":
                                {
                                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                    "type": "Practitioner"
                                },
                                "time": "2023-09-22T14:00:00+00:00",
                                "text": "Please call patient to update insurance information."
                            }
                        ],
                        "input":
                        [
                            {
                                "type":
                                {
                                    "text": "label"
                                },
                                "valueString": "Urgent"
                            }
                        ]
                    }
                }
            ]
        }
        ```
  - **400**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "invalid",
              "details": {
                "text": "Bad request"
              }
            }
          ]
        }
        ```
  - **401**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "unknown",
              "details": {
                "text": "Authentication failed"
              }
            }
          ]
        }
        ```
  - **403**
        ```json
        {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "forbidden",
              "details": {
                "text": "Authorization failed"
              }
            }
          ]
        }
        ```

---

# Terms of Use

Source: https://docs.canvasmedical.com/api/terms-of-use/

This Developer Tools Agreement (this "Agreement") is between you and Canvas Medical, Inc. ("us", "we", and "our") and governs your rights to use and access Developer Tools for the purpose of developing, implementing, and releasing Connected Services. We may modify the terms of this Agreement at any time and will inform you of such changes in writing (including by email). For purposes of this Agreement, "you" and "your" means you as the user of the Developer Tools. If you are entering into this Agreement on behalf of an entity (such as a medical practice, company, firm, partnership, or any other organization type), you are binding such entity to this Agreement, and you represent that you have the actual authority to bind such entity to this Agreement, and references to "you" and "your" means such entity. Such entity will be legally and financially responsible for use of the Developer Tools by anyone affiliated with such entity, including employees, agents, and contractors. By using the Developer Tools, you accept all of the provisions of this Agreement and represent to us that you are at least 18 years of age and legally competent to enter into and agree to this Agreement. If you do not agree to this Agreement, you may not use the Developer Tools. THIS AGREEMENT INCLUDE (1) AN ARBITRATION PROVISION; (2) A WAIVER OF RIGHTS TO BRING A CLASS ACTION AGAINST US; AND (3) A RELEASE BY YOU OF ALL CLAIMS FOR DAMAGE AGAINST US THAT MAY ARISE OUT OF YOUR USE OF THE DEVELOPER TOOLS. BY USING ANY OF THE DEVELOPER TOOLS, YOU AGREE TO THESE PROVISIONS.
Definitions. "Application" means our software-as-a-service web-based primary care technology platform. "Developer Tools" means APIs and SDKs made available to you by us, as well as all accompanying and related source code, executables, documentation, and content. "Connected Services" means web or other software applications that you develop that use or interact with Developer Tools. "API" means an application programming interface developed and enabled by us that permits our customers and other third parties to access certain functionality provided by the Application. "SDK" means any software development kit related to the Application developed and enabled by us. Rights Granted. We grant you a non-exclusive, non-transferable, non-sublicensable, worldwide, revocable right and license during the term of this Agreement to use and make calls to Developer Tools to develop, implement, release, and support Connected Services that are capable of exchanging information with the Application. You agree we may limit, suspend, or revoke your access to or use of Developer Tools, and make modifications to or deprecate Developer Tools, at any time for any reason, with or without notice. Your Responsibilities. Connected Services do not in any way inherit government clearance or other regulatory approval solely by integrating with or incorporating the Application. You (not us) are solely responsible for ensuring Connected Services comply with all applicable laws, including those governing use in a health care setting. You agree you will comply with, and will ensure the Connected Services will comply with, policies and other restrictions we have implemented from time to time regarding use of Developer Tools. You agree to not and will not attempt to, under any circumstances, repackage or in any way resell the Application, in whole or in part, using the Developer Tools or any other method, in each case without our specific written permission. You agree not to share with any third party, and to securely store, any credentials we provide for you to use Developer Tools. Unless otherwise specifically agreed by us, you are solely responsible for the accuracy, completeness, quality, integrity, legality, reliability, and appropriateness of the Connected Services, as well as the security and integrity of data processed by the Connected Services. Without limiting the foregoing, you (not us) are responsible for (a) the technical installation and operation of Connected Services; creating and displaying information and content on, through or within Connected Services; (c) ensuring that Connected Services do not violate or infringe the another's intellectual property rights; (e) ensuring Connected Services do not contain or introduce malicious code into the Application, or any data processed by the Application; and (f) ensuring Connected Services are not designed to or utilized for the purpose of spamming any Application end users. Disclaimer of Warranties, Limitation of Liability. THE DEVELOPER TOOLS ARE PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS, WITHOUT ANY WARRANTIES OF ANY KIND TO THE FULLEST EXTENT PERMITTED BY LAW, AND WE EXPRESSLY DISCLAIM ANY AND ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, TITLE, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. YOU AGREE THAT WE DO NOT WARRANT THAT THE DEVELOPER TOOLS WILL BE UNINTERRUPTED, TIMELY, SECURE, ERROR-FREE OR FREE FROM VIRUSES OR OTHER MALICIOUS SOFTWARE, AND NO INFORMATION OR ADVICE OBTAINED BY YOU FROM US WILL CREATE ANY WARRANTY NOT EXPRESSLY STATED IN THIS AGREEMENT. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY (WHETHER IN CONTRACT, TORT, NEGLIGENCE OR OTHERWISE) WILL WE, OR OUR AFFILIATES, OFFICERS, DIRECTORS, EMPLOYEES, AGENTS, SUPPLIERS OR LICENSORS BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOST PROFITS, LOST SALES OR BUSINESS, LOST DATA, BUSINESS INTERRUPTION, LOSS OF GOODWILL, OR FOR ANY TYPE OF INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, CONSEQUENTIAL OR PUNITIVE LOSS OR DAMAGES, OR ANY OTHER LOSS OR DAMAGES INCURRED BY YOU OR A THIRD PARTY IN CONNECTION WITH THIS AGREEMENT OR THE DEVELOPER TOOLS, REGARDLESS OF WHETHER WE WERE ADVISED OF THE POSSIBILITY OF OR COULD HAVE FORESEEN SUCH DAMAGES. NOTWITHSTANDING ANYTHING TO THE CONTRARY IN THIS AGREEMENT, OUR AGGREGATE LIABILITY TO YOU OR ANY THIRD PARTY ARISING OUT OF THIS AGREEMENT OR THE DEVELOPER TOOLS, WILL IN NO EVENT EXCEED ONE HUNDRED DOLLARS ($100.00). ANY CLAIM ARISING OUT OF OR RELATING TO THIS AGREEMENT MUST BE BROUGHT WITHIN ONE (1) YEAR OF THE FIRST EVENT OR OCCURRENCE GIVING RISE TO THE CLAIM. Indemnification. You agree to defend or settle, and to indemnify us and hold us harmless from, any claim brought by a third party against us arising from or related to any breach of an obligation, representation, warranty, covenant or other provision of this Agreement by you or any matter which you have agreed to be responsible for under this Agreement. Arbitration and Class Action Waiver. This Section includes an arbitration agreement and an agreement that all claims will be brought only in an individual capacity (and not as a Class Action or other representative proceeding). Please read it carefully. You may opt out of the arbitration agreement by following the opt out procedure described below. Informal Process First. You agree that in the event of any dispute between you and us, you will first contact us and make a good faith sustained effort to resolve the dispute before resorting to more formal means of resolution, including without limitation any court action. Arbitration Agreement. Under this Agreement, you agree that any dispute, claim, or controversy arising out of or relating to this Agreement your use of the Developer Tools, or relating in any way to the communications between you and us or any other user of Use will be finally resolved by confidential binding arbitration administered by Judicial Arbitration and Mediation Services ("JAMS") in San Francisco, California, or another forum mutually agreed upon by you and us. The arbitration will be conducted according to the JAMS Expedited Procedures for arbitration by a single arbitrator nominated jointly by you and us. If JAMS is not hearing consumer commercial disputes at the time, we may select another arbitral body at its sole discretion. The arbitrator's award will be binding and may be entered as a judgment in a court of competent jurisdiction. This clause shall not preclude us from seeking provisional remedies in aid of arbitration from a court of appropriate jurisdiction, or to seek injunctive relief in a court of competent jurisdiction to prevent the actual or threatened infringement, misappropriation, or violation of our copyrights, trademarks, trade secrets, or patents. This arbitration agreement does not (a) govern any Claim by us for infringement of our intellectual property or access to the Developer Tools that is unauthorized or exceeds authorization granted in this Agreement or (b) bar you from making use of applicable small claims court procedures in appropriate cases.
You agree that the U.S. Federal Arbitration Act governs the interpretation and enforcement of this provision, and that you and we are each waiving the right to a trial by jury or to participate in a Class Action. This arbitration provision will survive any termination of these this Agreement.
Class Action Waiver. Any Claim must be brought in the respective party's individual capacity, and not as a plaintiff or class member in any purported class, collective, representative, multiple plaintiff, or similar proceeding ("Class Action"). The parties waive any ability to maintain any Class Action in any forum. If the Claim is subject to arbitration, the arbitrator will not have authority to combine or aggregate similar claims or conduct any Class Action nor make an award to any person or entity not a party to the arbitration. Any claim that all or part of this Class Action Waiver is unenforceable, unconscionable, void, or voidable may be determined only by a court of competent jurisdiction and not by an arbitrator. The parties understand that any right to litigate in court, to have a judge or jury decide their case, or to be a party to a class or representative action, is waived, and that any claims must be decided individually, through arbitration.
If this Class Action waiver is found to be unenforceable, then the entirety of this Arbitration and Class Action Waiver Section, if otherwise effective, will be null and void. The arbitrator may award declaratory or injunctive relief only in favor of the individual party seeking relief and only to the extent necessary to provide relief warranted by that party's individual claim. If for any reason a claim proceeds in court rather than in arbitration, you and us each waive any right to a jury trial.
Ownership. Subject to the licenses and rights specified in this Agreement, nothing in this Agreement transfers or assigns to us any of your intellectual property rights in the Connected Services or your trademarks, logos, or other brand insignia nor does this Agreement transfer or assign to you any of our intellectual property rights in the Application and Developer Tools or our trademarks, logos, or other brand insignia. Support. This Agreement does not entitle you to receive from us any technical, customer, or sales support of the Application, Developer Tools, or Connected Services. You (not us) are solely responsible for providing technical assistance and other support related to the Connected Services. Miscellaneous. This Agreement constitutes the entire agreement between you and us regarding your use of the Developer Tools. If any term or provision of this Agreement is found to be invalid, illegal or otherwise unenforceable, such a finding will not affect the other terms or provisions of this Agreement, but such a term or provision will be deemed modified to the extent necessary to render such a term or provision enforceable, and the rights and obligations of you and us will be construed and enforced accordingly, preserving to the fullest permissible extent the intent and agreements set forth in this Agreement. Your obligations pursuant to this Agreement will survive termination of your use of the Developer Tools. The JAMS Rules and the laws of the State of California, excluding its conflicts of law rules, governs this Agreement and your use of the Developer Tools. Your use of the Developer Tools may also be subject to other local, state, national, or international laws.

---

# How to add additional fields to the scheduling appointment fields

Source: https://docs.canvasmedical.com/guides/appointments-additional_fields/

This guide explains how to add additional fields that will appear when scheduling an appointment. With this, you can define custom fields, and the information will be stored as appointments metadata.
##  What you'll learn: 
  - Use the [`AppointmentMetadataCreateForm`](/sdk/appointment-metadata-create-form-effect) effect to display additional fields when scheduling an appointment.
  - Use the [`FormField`](/sdk/appointment-metadata-create-form-effect/#formfield) class to create fields
##  Appointment Metadata Create form plugin 
####  1\. FormField 
To create the form, we need to specify which items will be included. For this, we use the [`FormField`](/sdk/appointment-metadata-create-form-effect/#formfield) class, where we can define our inputs and their attributes.
    ```python
    from canvas_sdk.effects.appointments_metadata import FormField, InputType
    FormField(
        key='state',
        label='State',
        type=InputType.TEXT,
        required=False,
        editable=True,
        value="CA"
    ),
    ```
####  2\. AppointmentMetadataCreateFormEffect 
The next step is to add these fields to the effect so they can be used to build the form.
    ```python
    from canvas_sdk.effects.appointments_metadata import AppointmentsMetadataCreateFormEffect, FormField, InputType
    AppointmentsMetadataCreateFormEffect(form_fields=[
        FormField(
            key='state',
            label='State',
            type=InputType.TEXT,
            required=False,
            editable=True,
            value="CA"
        ),
        ...,
    ])
    ```
####  3\. The plugin 
Here's an example of a complete plugin showcasing the different input types.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.appointments_metadata import AppointmentsMetadataCreateFormEffect, InputType, FormField
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    # Inherit from BaseHandler to properly get registered for events
    class Handler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.APPOINTMENT__FORM__GET_ADDITIONAL_FIELDS)
        def compute(self) -> list[Effect]:
            form = AppointmentsMetadataCreateFormEffect(form_fields=[
                FormField(
                    key='state',
                    label='State',
                    type=InputType.TEXT,
                    required=False,
                    editable=True,
                ),
                FormField(
                    key='occupation',
                    label='Occupation',
                    type=InputType.SELECT,
                    required=False,
                    editable=True,
                    options=["Engineer", "Teacher", "Other"]
                )
            ])
            return [form.apply()]
    ```
####  4\. The Output 
Below, you can see how it will appear in the app — these fields will be stored as appointments metadata.
![appointments-additional-fields](/assets/images/appointments-additional-fields.png)

---

# Audit Logging and Telemetry

Source: https://docs.canvasmedical.com/guides/audit-logging-and-telemetry/

Canvas records an attributed audit trail of activity in your instance and makes it available to you through several export paths. This page describes what is captured, how long it is retained, and how to get it out — whether for an internal investigation, a compliance review, or ingestion into your own SIEM.
##  What is captured 
Canvas maintains a per-record audit trail. Each entry identifies the record type acted on, the action taken, the acting user, the patient context where applicable, and a UTC timestamp.
Action| Captured| Granularity  
---|---|---  
Create| Yes| Per record, per model, attributed to the acting user  
Edit or change| Yes| Per record, with full authorship history  
Delete, void, or enter-in-error| Yes| Per record, covering hard deletion, soft deletion, and marking entered-in-error  
Print| Yes| Every printed document, attributed to the user who printed it  
Chart access| Yes| Chart-open events, attributed to the user opening the chart  
Individual record reads within an already-opened chart are not enumerated separately; chart access is recorded at the point the chart is opened.
###  Print events 
Printing discloses patient information, so Canvas records every print. Recorded documents include notes, After Visit Summaries, letters, appointment lists, claim forms, and superbills. Patient receipts and ledgers, insurance cards, and cash reconciliation reports are recorded too. So are full chart exports that a plugin requests on a staff member's behalf. When a patient downloads the After Visit Summary of their own visit from the patient portal, Canvas records a download attributed to that patient.
Each print event records the document printed, its identifier, the acting user, the patient in context, and a UTC timestamp. Some documents, such as appointment lists and cash reconciliation reports, are not about a single patient, so their events have no patient. If Canvas cannot record the event, the print fails and the document is not delivered.
Opening a fax preview is recorded as a fax preview rather than a print. Sending the fax does not record a separate print event.
Alongside the record audit trail, Canvas captures:
  - **Authentication events** — sign-in successes and failures, account lockouts, and Canvas administrators starting and ending a session as another user.
  - **Refused requests** — requests and GraphQL operations refused for lack of permission, attributed to the user who was refused.
  - **Administrative activity** — configuration and permission changes, surfaced in the admin console and protected there against edit and deletion.
  - **Staff activity reports** — generated nightly.
###  Change history through FHIR Provenance 
Authorship and change history are also exposed as FHIR `Provenance` resources across supported resource types, giving you a queryable record of who created or revised a resource and when. See the [Provenance API](/api/provenance/) reference for supported resource types and query parameters.
Clinical notes additionally carry in-application revision history, visible to users directly in the chart.
##  Retention 
Audit records are retained in the live, queryable index for **90 days**. Older indices are archived to durable object storage and remain recoverable well beyond that window. If you require retrieval of archived records, contact Canvas support with the date range you need.
Retention requirements that exceed the live window are best served by exporting on a schedule into your own retention tier — see the export paths below.
##  Viewing the audit trail in the application 
Authorized users can browse the audit trail in a filterable, searchable, read-only view built into the application. It surfaces recorded events without allowing any change to them.
The view is enabled per instance by Canvas; contact Canvas to turn it on for your instance. Once enabled, access still requires an explicit permission that no default role carries, so a customer administrator must grant it intentionally.
This view reviews audit data in place; it does not extract or export anything. To get audit data out of Canvas, see the paths below.
##  Getting audit data out 
Five supported paths exist today. Which one fits depends on whether you need a point-in-time extract, an ongoing feed, or ad-hoc investigation.
Path| Best for| Interface  
---|---|---  
Audit Report export| Point-in-time extract of administrative and record-level audit events| Admin console  
[FHIR Provenance API](/api/provenance/)| Authorship and change history for specific resources| FHIR API  
FHIR Bulk Data export| Large-scale structured extraction| FHIR API — see [Electronic Health Information (EHI) Export](/documentation/ehi-export/)  
Read-only replica database| Ad-hoc investigation, custom reporting, scheduled ingestion| SQL  
Streaming to a SIEM| Continuous security monitoring in your own SIEM| HTTPS push  
###  Audit Report export 
The Audit Report is generated from the admin console and exports the audit trail for a selected date range. This is the most direct route to the record-level events described above, including chart access and print events.
For print events, the report shows the document type as the data accessed and `print` or `faxpreview` as the action. When an event has no patient in context, the patient columns read `N/A`.
> **Warning:** Audit Report access is permission-based. If you need access, your internal administrators can work with Canvas support to assign it to the appropriate groups.
###  Read-only replica database 
Instances can be provisioned with a read-only replica for direct SQL access. This is the most flexible path for building custom audit reporting with your own SQL queries, and for ad-hoc or scheduled extraction into an external system. For continuous security monitoring, use the SIEM export below instead.
###  Streaming to a SIEM 
Canvas pushes audit events to an HTTPS endpoint you control. Events use the Open Cybersecurity Schema Framework (OCSF) schema — an open, vendor-neutral format that SIEMs understand — and are delivered as batched newline-delimited JSON (NDJSON).
The endpoint must be an `https://` URL whose host resolves only to public internet addresses, not to private, loopback, or link-local ones. The URL can't contain a username, password, or backslash; Canvas sends credentials in a request header instead. If the URL doesn't meet these requirements, Canvas sends nothing and holds events until the URL is corrected. Canvas doesn't follow redirects, so the endpoint must accept the POST at the configured URL. A redirect response counts as a failed delivery, and Canvas retries the batch later.
Delivery is at-least-once, so the receiving system must tolerate occasional duplicate events. "Delivered" means your endpoint accepted the batch with an HTTP 2xx response; it is not a guarantee that every event became queryable in your SIEM. Reconcile against the events you actually receive.
Delivery is also durable: Canvas stores each audit event and keeps trying to deliver it, retrying when your endpoint is temporarily unreachable, so a brief outage at your end does not immediately drop events from the feed. If you suspect a gap in what your SIEM received, the same events are retained in Canvas (see Retention above) and remain available through the other audit paths on this page, so you can reconcile or recover them there. If a delivery problem persists, contact Canvas.
The export never includes patient names, dates of birth, or clinical values — only opaque identifiers, booleans, and enumerated values. Identifiers are direct Canvas identifiers by default, or pseudonymized on request.
> **Info:** The SIEM export is opt-in and enabled per instance by Canvas — it is not a self-serve toggle. Request it through your Canvas representative, who sets up your destination endpoint and the credentials Canvas presents to it.
####  Event format 
Each request to your endpoint is a `POST` with `Content-Type: application/x-ndjson`, carrying up to 500 events by default, one JSON object per line. Every body ends with a newline, so successive bodies appended to one file read as a single NDJSON stream. Events follow OCSF 1.1.0.
Field| Meaning  
---|---  
`metadata.uid`| Unique id for the event. Delivery is at-least-once, so use it to drop duplicates.  
`metadata.correlation_uid`| Id of the request that produced the event, when there was one. Events from the same request share it.  
`metadata.version`| OCSF schema version.  
`metadata.tenant_uid`| The Canvas instance that produced the event, so one SIEM can take events from several instances.  
`metadata.labels`| `environment:production` for a production instance, `environment:non-production` for a sandbox or test instance.  
`category_uid`, `class_uid`, `activity_id`, `type_uid`| OCSF classification of the event (see the table below). `type_uid` is `class_uid * 100 + activity_id`.  
`time`| When the event happened, in milliseconds since the Unix epoch (UTC).  
`status_id`| Outcome: `1` success, `2` failure.  
`status_code`| Why an event failed: `invalid_credentials` or `account_locked` on a sign-in, `403` on a refused request, `permission_denied` on a refused GraphQL operation. Absent on success.  
`api.operation`| On a refused request, the operation that was refused: the HTTP method and the URL pattern the request matched (`GET api/Patient/(?P<key>[a-f0-9]{32})$`), or `graphql`, the operation type, and the top-level field (`graphql mutation updateNoteBody`). Never the actual path or its arguments.  
`actor.user.uid`, `actor.user.name`| Canvas user id and username of the acting user. On a failed sign-in or lockout, `uid` is `null` and `name` is the username that was tried. Both are `null` when no signed-in user caused the event. While a Canvas administrator is acting as another user, this is the user being acted as.  
`actor.invoked_by`| The plugin whose action caused the event. Absent when a user acted directly.  
`src_endpoint.ip`, `src_endpoint.user_agent`| Client address and browser or client identifier. Both are `null` when the event didn't come from a client request.  
`resources`| What the event acted on: the patient (`type` `patient`) and the record, typed by its Canvas resource name. The patient `uid` is the patient key, the same id the FHIR API uses for the Patient. A record `uid` is Canvas's internal record id, which differs from the record's FHIR resource id. On an update to a clinical record, the record's `data.changed_fields` lists the names of the fields that changed; values are never included.  
`enrichments`| Canvas detail. `source` is `authentication`, `activity_log`, `provenance`, or `access_control`; `event_name` names the Canvas action; `impersonated_by` is the username of the administrator acting as the user in `actor`, on every event during that session (`id:` followed by the administrator's user id if the username can't be read); `plugin_handler` names the plugin handler alongside `actor.invoked_by`; `payload` carries extra identifiers; `payload_withheld` lists the names of payload fields left out because they can contain names or free text.  
`class_uid`| OCSF class| Canvas events  
---|---|---  
3001| Account Change| Staff account created  
3002| Authentication| Sign-in, sign-out, failed sign-in, account lockout, patient portal sign-in link issued, an administrator starting or ending a session as another user  
3005| User Access Management| Staff access granted or revoked  
6001| Web Resources Access| Chart opened, note printed  
6003| API Activity| Clinical records and the patient record created, updated, or deleted; coverage, address, patient location, facility address, and care team changes; requests refused for lack of permission  
`activity_id` values depend on the class. In Authentication, `1` is a sign-in attempt, including failed sign-ins, lockouts, issued portal sign-in links, and the start of a session as another user, and `2` is a sign-out or the end of one. In User Access Management, `1` grants access and `2` revokes it. In the other classes, `1` is create, `2` is read, `3` is update, `4` is delete, and `99` is a refused GraphQL mutation. A refused request whose operation type can't be determined has `0`. Marking a clinical record entered in error is reported as a delete.
On a staff account created or a change to staff access, `actor` is the administrator who made the change and `resources` holds the account changed. A change made outside a signed-in session, such as a directory sync, has a `null` actor. When an administrator starts a session as another user, `actor` is the administrator and `resources` holds the user taken over, with `event_name` `impersonation.started` (and `impersonation.ended` when the session returns to the administrator).
With pseudonymized identifiers, `resources[].uid` values are per-customer HMAC-SHA256 tokens (64 hex characters) in place of Canvas identifiers, and `enrichments.payload` and `enrichments.payload_withheld` are omitted. `changed_fields` is kept, since it holds only field names.
####  Example events 
The examples below are formatted across several lines for reading; each arrives on a single line. Identifiers and addresses are illustrative.
A failed sign-in:
    ```json
    {
      "metadata": {
        "version": "1.1.0",
        "uid": "6be79fea-caa8-40e1-a480-9c86e2b243f4",
        "product": {"name": "Canvas", "vendor_name": "Canvas Medical"},
        "tenant_uid": "acme",
        "labels": ["environment:production"],
        "correlation_uid": "7a1c3e5f9b2d4f6a8c0e1b3d5f7a9c2e"
      },
      "category_uid": 3,
      "class_uid": 3002,
      "activity_id": 1,
      "type_uid": 300201,
      "time": 1791999125000,
      "actor": {"user": {"uid": null, "name": "jsmith"}},
      "src_endpoint": {
        "ip": "203.0.113.24",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Safari/605.1.15"
      },
      "status_id": 2,
      "status_code": "invalid_credentials",
      "enrichments": {"source": "authentication"}
    }
    ```
A staff member opening a patient's chart:
    ```json
    {
      "metadata": {
        "version": "1.1.0",
        "uid": "b7f9f925-646d-4607-ac71-36f5708565ca",
        "product": {"name": "Canvas", "vendor_name": "Canvas Medical"},
        "tenant_uid": "acme",
        "labels": ["environment:production"],
        "correlation_uid": "f32eec1863c3dda8afea21ba0cb39a9d"
      },
      "category_uid": 6,
      "class_uid": 6001,
      "activity_id": 2,
      "type_uid": 600102,
      "time": 1791999185000,
      "actor": {"user": {"uid": "412", "name": "jsmith"}},
      "src_endpoint": {
        "ip": "203.0.113.24",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Safari/605.1.15"
      },
      "status_id": 1,
      "resources": [{"type": "patient", "uid": "381bf94ac3b269eedec9dc3f660a4cf0"}],
      "enrichments": {"source": "activity_log", "event_name": "chart_access"}
    }
    ```
An update to a condition on that patient's chart:
    ```json
    {
      "metadata": {
        "version": "1.1.0",
        "uid": "98e8a792-dd0f-4d4e-909e-94653f2af09c",
        "product": {"name": "Canvas", "vendor_name": "Canvas Medical"},
        "tenant_uid": "acme",
        "labels": ["environment:production"],
        "correlation_uid": "0c5d1f7a9e2b4c6d8f1a3b5c7d9e0f12"
      },
      "category_uid": 6,
      "class_uid": 6003,
      "activity_id": 3,
      "type_uid": 600303,
      "time": 1791999302000,
      "actor": {"user": {"uid": "412", "name": "jsmith"}},
      "src_endpoint": {
        "ip": "203.0.113.24",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Safari/605.1.15"
      },
      "status_id": 1,
      "resources": [
        {"type": "patient", "uid": "381bf94ac3b269eedec9dc3f660a4cf0"},
        {
          "type": "Condition",
          "uid": "52817",
          "data": {"changed_fields": ["clinical_status", "committer"]}
        }
      ],
      "enrichments": {"source": "provenance"}
    }
    ```
A request refused for lack of permission:
    ```json
    {
      "metadata": {
        "version": "1.1.0",
        "uid": "3d0b8f4e-2a61-4c7e-9f15-6e8a2c4b7d90",
        "product": {"name": "Canvas", "vendor_name": "Canvas Medical"},
        "tenant_uid": "acme",
        "labels": ["environment:production"],
        "correlation_uid": "5e7a9c1b3d5f7a9c2e4b6d8f0a2c4e6b"
      },
      "category_uid": 6,
      "class_uid": 6003,
      "activity_id": 2,
      "type_uid": 600302,
      "time": 1791999411000,
      "actor": {"user": {"uid": "418", "name": "mlee"}},
      "src_endpoint": {
        "ip": "198.51.100.7",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36"
      },
      "status_id": 2,
      "status_code": "403",
      "api": {"operation": "GET api/Patient/(?P<key>[a-f0-9]{32})$"},
      "enrichments": {"source": "access_control", "event_name": "access_denied"}
    }
    ```
A Canvas administrator, signed in as `jsmith`, opening a patient's chart:
    ```json
    {
      "metadata": {
        "version": "1.1.0",
        "uid": "c41e7a2d-8b3f-4e19-a6d0-2f5c9b1e7a34",
        "product": {"name": "Canvas", "vendor_name": "Canvas Medical"},
        "tenant_uid": "acme",
        "labels": ["environment:production"],
        "correlation_uid": "9c2e4b6d8f0a2c4e6b8d0f1a3c5e7b9d"
      },
      "category_uid": 6,
      "class_uid": 6001,
      "activity_id": 2,
      "type_uid": 600102,
      "time": 1791999520000,
      "actor": {"user": {"uid": "412", "name": "jsmith"}},
      "src_endpoint": {
        "ip": "192.0.2.15",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36"
      },
      "status_id": 1,
      "resources": [{"type": "patient", "uid": "381bf94ac3b269eedec9dc3f660a4cf0"}],
      "enrichments": {
        "source": "activity_log",
        "event_name": "chart_access",
        "impersonated_by": "canvas-support"
      }
    }
    ```
##  Plugin activity 
Plugins execute in an isolated runner, and their activity is instrumented per plugin, including outbound HTTP calls made through the SDK. Plugins can also emit their own application logs — see [Plugin Logs](/sdk/plugin-logs/).
##  Related 
  - [Platform Security Overview](/guides/platform-security-overview/)
  - [Roles and Permissions](/guides/roles-and-permissions/)
  - [Plugin Security Model](/guides/plugin-security-model/)
  - [Provenance API](/api/provenance/)
  - [EHI Export](/documentation/ehi-export/)

---

# Automating Note and Billing Workflows

Source: https://docs.canvasmedical.com/guides/automating-note-and-billing-workflows/

Plugins can react to clinical and administrative events on notes and automate steps that staff would otherwise do by hand: carrying commands forward to a new note, reassigning a note based on the payer, attaching billing line items to a diagnosis, and notifying an external system when a note is locked. This guide collects several event-driven patterns that share the same shape — listen for an event, read the relevant data, return an effect.
##  Carrying commands forward to a new note 
When a command is created or deleted, the event context already carries the data you need — you usually do not have to query the database. For example, to restore a Diagnose command after it is deleted (and re-apply the same code the user had selected), listen for `DIAGNOSE_COMMAND__POST_DELETE` and read the code straight from the context.
On a Diagnose delete, `self.context['fields']` looks like this:
    ```python
    {
        'diagnose': {
            'text': 'Malignant neoplasm of abdomen',
            'extra': {
                'coding': [
                    {'code': 'C762', 'system': 'ICD-10', 'display': 'Malignant neoplasm of abdomen'},
                    {'code': 188366002, 'system': 'http://snomed.info/sct', 'display': 'Malignant neoplasm of abdomen'},
                ],
            },
            'value': 'C762',
            'disabled': False,
            'annotations': ['C76.2', 'HCC'],
            'description': None,
        },
        'background': '',
        'today_assessment': '',
        'approximate_date_of_onset': None,
    }
    ```
The selected ICD-10 code is at `self.context['fields']['diagnose']['value']`. That makes the handler simple:
    ```python
    from canvas_sdk.commands.commands.diagnose import DiagnoseCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.protocols import BaseProtocol
    from logger import log
    class HandleDiagnoseCommandDelete(BaseProtocol):
        """Adds a Diagnose command back if it is deleted."""
        RESPONDS_TO = [
            EventType.Name(EventType.DIAGNOSE_COMMAND__POST_DELETE),
        ]
        def compute(self) -> list[Effect]:
            note_id = self.context.get("note", {}).get("uuid")
            patient_id = self.context.get("patient", {}).get("id")
            diagnose_command = DiagnoseCommand(note_uuid=note_id)
            try:
                icd10_code = self.context.get("fields", {}).get("diagnose", {}).get("value")
                if icd10_code:
                    log.info(f"restoring diagnose command with code: {icd10_code}")
                    diagnose_command.icd10_code = icd10_code
                else:
                    log.info(f"no code found for patient: {patient_id}, restoring command without code")
            except Exception as e:
                log.info(f"Failed to find icd10 code for patient: {patient_id}, error: {e}")
            return [diagnose_command.originate()]
    ```
The general pattern for a "carry forward" plugin is to read a `Command.data` attribute (or, as above, the context fields) and originate a duplicate command with the same data. You do not always want to carry every command forward verbatim — sometimes you want to advance it to the next stage instead (for example, carrying a prior Diagnose forward as an Assess of that condition rather than duplicating the diagnosis). For a fuller worked example, see the Medical Software Foundation [carry-forward extension](https://github.com/Medical-Software-Foundation/canvas/tree/action-button-examples-for-developer-support/extensions/carry-forward).
##  Reassigning a note based on the payer 
You can detect the payer associated with a note and reassign the note to a different provider (for example, a supervisor). When a billable note type is created, Canvas automatically creates a [Claim](/sdk/data-claim/) for the appointment/note, and that claim carries the payer information.
Listen for both `APPOINTMENT_CREATED` and `NOTE_STATE_CHANGE_EVENT_CREATED`, find the associated claim, check the payer against your rules, and return a [Note](/sdk/effect-notes/) or [Appointment](/sdk/effect-notes/#appointment-effect) effect that updates the provider.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note import Appointment as AppointmentEffect, Note as NoteEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.protocols import BaseProtocol
    from canvas_sdk.v1.data import (
        Appointment as AppointmentModel,
        Claim,
        Note as NoteModel,
        Staff,
    )
    class Protocol(BaseProtocol):
        """Detect the payer for a new note and re-assign the provider."""
        RESPONDS_TO = [
            EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED),
            EventType.Name(EventType.APPOINTMENT_CREATED),
        ]
        def handle_note_create(self) -> list[Effect]:
            if self.event.context["state"] != "NEW":
                return []
            note_model = NoteModel.objects.get(id=self.event.context["note_id"])
            claim = note_model.get_claim()
            if not claim:
                return []
            return self.update_provider(claim)
        def handle_appointment_create(self) -> list[Effect]:
            appointment_model = AppointmentModel.objects.get(id=self.event.target.id)
            note_model = appointment_model.note
            if not note_model or not (claim := note_model.get_claim()):
                return []
            return self.update_provider(claim)
        def update_provider(self, claim: Claim) -> list[Effect]:
            if claim.current_coverage.payer_id == "J4054":
                # Replace with whatever payer logic you need. You can also look up
                # more about the payer from the Transactor model.
                new_provider = Staff.objects.filter(first_name="Andrew").first()
                Effect = AppointmentEffect if self.is_appointment else NoteEffect
                effect = Effect(instance_id=self.event.target.id, provider_id=new_provider.id)
                return [effect.update()]
            return []
        def compute(self) -> list[Effect]:
            if self.event.type == EventType.NOTE_STATE_CHANGE_EVENT_CREATED:
                self.is_appointment = False
                return self.handle_note_create()
            if self.event.type == EventType.APPOINTMENT_CREATED:
                self.is_appointment = True
                return self.handle_appointment_create()
            return []
    ```
The payer information lives on the claim's [`current_coverage`](/sdk/data-claim/#claimcoverage); for additional payer detail you can read the [`Transactor`](/sdk/data-coverage/#transactor) model.
##  Attaching a billing line item to a diagnosis 
You can automate billing for specific note types — for instance, adding a diagnosis and an associated billing line item when an intake note is created. The key detail is that a billing line item is linked to a diagnosis through its **Assessment** , and the Assessment ID only exists once the Assess command has been **committed**. Passing the command UUID as the assessment ID will not work; the assessment must come from the committed command.
Split the work into two handlers. First, originate and commit an Assess command with the ICD-10 code when the note is created. It records the condition if the patient doesn't have it yet, or reuses the charted one:
    ```python
    from uuid import uuid4
    from canvas_sdk.commands import AssessCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    from canvas_sdk.protocols import BaseProtocol
    from canvas_sdk.v1.data import Encounter
    class IntakeCreatedProtocol(BaseProtocol):
        RESPONDS_TO = EventType.Name(EventType.ENCOUNTER_CREATED)
        def compute(self) -> list[Effect]:
            encounter = Encounter.objects.get(id=self.event.target.id)
            note = encounter.note
            # Verify the note type is approved for this workflow before proceeding.
            assess_command = AssessCommand(note_uuid=str(note.id), icd10_code="Z13.41")
            assess_command.command_uuid = str(uuid4())
            return [assess_command.originate(), assess_command.commit()]
    ```
Then, in a second handler, listen for `ASSESS_COMMAND__POST_COMMIT`, retrieve the assessment (the command's `anchor_object`), confirm its condition is the diagnosis you care about, and attach the billing line item using the assessment's ID:
    ```python
    from canvas_sdk.commands.constants import CodeSystems
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.billing_line_item import AddBillingLineItem
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.command import Command
    class AddBillingLineItemToAutismDiagnoses(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.ASSESS_COMMAND__POST_COMMIT)
        def compute(self) -> list[Effect]:
            command = Command.objects.get(id=self.event.target.id)
            assessment = command.anchor_object
            icd_10_coding = assessment.condition.codings.filter(system=CodeSystems.ICD10).first()
            if not icd_10_coding or icd_10_coding.code.replace(".", "") != "Z1341":
                return []
            note = command.note
            b = AddBillingLineItem(
                note_id=str(note.id),
                cpt="AUTISM_DX",
                assessment_ids=[str(assessment.id)],
            )
            return [b.apply()]
    ```
In this example the ICD-10 code `Z13.41` and CPT `AUTISM_DX` are placeholders from the originating discussion — substitute the codes and fee schedule entries your workflow requires, and confirm code selection with your clinical and billing teams.
##  Triggering an external transfer when a note is locked 
To push data to an external system when a provider locks a note, build a [webhook plugin](/guides/creating-webhooks-with-the-canvas-sdk/) that listens for `NOTE_STATE_CHANGE_EVENT_CREATED` and checks for the lock state. A note lock is the state `'LKD'`; ignore other states (see the full list of [note states](/sdk/data-note/#notestates)).
Read `note_id` and `patient_id` from the context, look up the note's [Encounter](/sdk/data-encounter/#encounter), fetch the data you want to send from the FHIR API (which returns FHIR-shaped JSON), and forward it to your endpoint. Use the [`Http`](/sdk/utils/) util for the requests and store credentials in [secrets](/sdk/secrets/) rather than in plaintext.
    ```python
    from urllib.parse import urlencode
    from canvas_sdk.events import EventType
    from canvas_sdk.protocols import BaseProtocol
    from canvas_sdk.utils import Http
    from canvas_sdk.v1.data import Encounter
    from logger import log
    class Protocol(BaseProtocol):
        """When a note is locked, fetch FHIR data and notify an external endpoint."""
        RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_CREATED)
        def compute(self):
            # Ignore any note state change that is not a lock.
            if self.event.context["state"] != "LKD":
                return []
            note_id = str(self.event.context["note_id"])
            patient_id = str(self.event.context["patient_id"])
            # The FHIR Encounter is identified by the encounter's id, not the note's.
            encounter = Encounter.objects.filter(note__id=note_id).first()
            if encounter is None:
                return []
            http = Http()
            # Get a bearer token using your OAuth client credentials.
            payload = urlencode(
                {
                    "grant_type": "client_credentials",
                    "client_id": self.secrets["CLIENT_ID"],
                    "client_secret": self.secrets["CLIENT_SECRET"],
                }
            )
            bearer_token = http.post(
                "your-canvas-ehr-instance/auth/token",
                headers={"Content-Type": "application/x-www-form-urlencoded"},
                data=payload,
            )
            headers = {"Authorization": f"Bearer {bearer_token}"}
            # Read the FHIR Patient and Encounter resources.
            patient_fhir_data = http.get(
                f"https://fumage-example.canvasmedical.com/Patient/{patient_id}", headers=headers
            )
            encounter_fhir_data = http.get(
                f"https://fumage-example.canvasmedical.com/Encounter/{encounter.id}", headers=headers
            )
            # Forward the payload to your secure endpoint.
            response = http.post(
                "your-secure-api-gateway-address",
                json={"patient": patient_fhir_data, "encounter": encounter_fhir_data},
                headers={"Authorization": f"Bearer {self.secrets['AUTH_TOKEN']}"},
            )
            if response.ok:
                log.info("Successfully notified API of note lock!")
            else:
                log.info("Notification unsuccessful.")
            return []
    ```
This pattern runs entirely inside the Canvas environment — there is no need to host a separate EC2 service to react to the lock. See the [Patient read](/api/patient/#read) and [Encounter read](/api/encounter/#read) API references for the resources you can pull.

---

# Building Custom Plugin UI with Action Buttons and SimpleAPI

Source: https://docs.canvasmedical.com/guides/build-custom-ui-with-action-buttons/

A common need is to add your own button to the Canvas UI that opens a custom screen — a printable visit summary, a data-entry form, a dashboard — and then act on what the user does there. The building blocks are always the same three pieces:
  1. An [`ActionButton`](/sdk/handlers-action-buttons/) (or [`Application`](/sdk/handlers-applications/)) places a button in the UI and, when clicked, returns a [`LaunchModalEffect`](/sdk/layout-effect/#modals).
  2. The modal shows HTML/JavaScript, either inlined with `content=` or loaded from a URL served by your own [`SimpleAPI`](/sdk/handlers-simple-api-http/).
  3. The `SimpleAPI` endpoint queries data, renders HTML, and/or receives requests from the modal's JavaScript and returns [effects](/sdk/effects/) (such as [commands](/sdk/commands/)) that change the note.
This guide shows two variations of the pattern: a read-only custom print template, and an interactive form that adds a command to a note.
##  Two ways to populate the modal 
`LaunchModalEffect` accepts either:
  - `content=` — an HTML string you render inline. Best for small, self-contained screens.
  - `url=` — a path served by your plugin's `SimpleAPI`, in the form `/plugin-io/api/<plugin_name>/...`. Best when you need to query several data models server-side, serve CSS or images as separate files, reuse the endpoint for external integrations (fax, PDF generation), or you would otherwise hit size limits on inline content.
##  Pattern 1: A custom printable visit summary 
The default "Print note" button gives you no control over layout. By serving your own HTML template from a `SimpleAPI` endpoint, you fully control the printed output. The plugin registers two components: an `ActionButton` in the note header and a `SimpleAPI` that renders the page.
For a complete, ready-to-install version, see the [patient-visit-summary](https://github.com/medical-software-foundation/canvas/tree/main/extensions/patient-visit-summary) extension. It adds a patient-friendly visit summary to the note, plus a panel where staff choose and reorder the note's sections, preview the result, and print it or save it as a PDF to the patient's chart. The sections below build a simpler version of the same pattern.
###  Manifest 
Register both components in `CANVAS_MANIFEST.json`:
    ```json
    {
        "sdk_version": "0.75.0",
        "plugin_version": "1.0.0",
        "name": "patient_visit_summary",
        "components": {
            "protocols": [
                {
                    "class": "patient_visit_summary.protocols.patient_visit_summary:CustomHTMLActionButton",
                    "description": "Note header button that opens the visit summary."
                },
                {
                    "class": "patient_visit_summary.protocols.patient_visit_summary:CustomerHTMLApi",
                    "description": "API endpoint serving the visit summary HTML."
                }
            ]
        },
        "variables": [
            {"name": "simpleapi-api-key", "sensitive": true}
        ]
    }
    ```
###  Action button 
The button opens the modal by pointing it at the plugin's own API endpoint:
    ```python
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.action_button import ActionButton
    class CustomHTMLActionButton(ActionButton):
        BUTTON_TITLE = "Patient Visit Summary"
        BUTTON_KEY = "PATIENT_VISIT_SUMMARY"
        BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_HEADER
        def visible(self) -> bool:
            # Add logic here if the button should only show on specific notes.
            return True
        def handle(self):
            return [
                LaunchModalEffect(
                    url=f"/plugin-io/api/patient_visit_summary/?patient_id={self.event.target.id}&note_id={self.event.context['note_id']}"
                ).apply()
            ]
    ```
Key details:
  - `self.event.target.id` gives the patient ID.
  - `self.event.context['note_id']` gives the current note's database id (`dbid`), not its UUID.
  - The URL pattern `/plugin-io/api/<plugin_name>/` routes to your `SimpleAPI`.
###  SimpleAPI that renders the HTML 
The endpoint authenticates the caller, queries the data you want on the page, and returns rendered HTML. Authenticating via the session first lets staff click straight through from the Canvas UI; the optional API-key fallback lets you fetch the same page from outside Canvas.
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import HTMLResponse, Response
    from canvas_sdk.handlers.simple_api import (
        APIKeyAuthMixin,
        APIKeyCredentials,
        Credentials,
        SessionCredentials,
        SimpleAPI,
        StaffSessionAuthMixin,
        api,
    )
    from canvas_sdk.handlers.simple_api.exceptions import AuthenticationError
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data.note import Note
    from canvas_sdk.v1.data.patient import Patient
    class CustomerHTMLApi(StaffSessionAuthMixin, APIKeyAuthMixin, SimpleAPI):
        def authenticate(self, credentials: Credentials) -> bool:
            # A staff member clicking through from the Canvas UI.
            try:
                return StaffSessionAuthMixin.authenticate(self, SessionCredentials(self.request))
            except AuthenticationError:
                pass
            # Otherwise, a request from outside Canvas with the API key.
            return APIKeyAuthMixin.authenticate(self, APIKeyCredentials(self.request))
        @api.get("/")
        def index(self) -> list[Response | Effect]:
            patient_id = self.request.query_params.get("patient_id")
            note_id = self.request.query_params.get("note_id")
            patient = Patient.objects.get(id=patient_id)
            note = Note.objects.get(dbid=note_id)
            # Fetch any data you want on the page (vitals, assessments, prescriptions, etc.).
            return [
                HTMLResponse(
                    render_to_string(
                        "templates/patient_visit_summary.html",
                        context={"patient": patient, "note": note},
                    ),
                    status_code=HTTPStatus.OK,
                )
            ]
        @api.get("/style.css")
        def get_css(self) -> list[Response | Effect]:
            return [
                Response(
                    render_to_string("templates/style.css").encode(),
                    status_code=HTTPStatus.OK,
                    content_type="text/css",
                )
            ]
    ```
###  HTML template 
The template is where you craft your print layout. Reference the CSS through the plugin's own API endpoint and add a print button:
    ```html
    <link rel="stylesheet" type="text/css"
          href="/plugin-io/api/patient_visit_summary/style.css">
    <button class="print-button" onclick="window.print()">Print</button>
    ```
A `@media print` query keeps the page clean when printed — hide the button and control page breaks:
    ```css
    .print-button {
        position: fixed;
        top: 10px;
        right: 10px;
    }
    @media print {
        body { background-color: white; padding: 0; }
        #container { box-shadow: none; }
        .print-button { display: none; }
        h2 { page-break-after: avoid; }
        .section-container { page-break-inside: avoid; }
    }
    ```
###  Recommended structure 
A clean layout for this kind of plugin is:
  - `protocols/` — the `ActionButton` handler and the `SimpleAPI` handler (in one file, or split across two).
  - `templates/` — the Django HTML templates rendered by `render_to_string()`.
  - `images/` — logos stored as base64-encoded strings (for example in an `images_b64.py`) and embedded directly into the HTML via template variables, which avoids serving image files separately.
###  Flow summary 
    ```text
    User clicks "Patient Visit Summary" in the note header
      → ActionButton.handle() fires
      → LaunchModalEffect opens /plugin-io/api/patient_visit_summary/?patient_id=X&note_id=Y
      → SimpleAPI authenticates via session cookie (staff user)
      → SimpleAPI queries patient data, commands, vitals, assessments, etc.
      → render_to_string() renders the HTML template with all context
      → HTMLResponse returns the fully rendered page
      → User sees the summary in a modal and clicks "Print" → window.print()
    ```
##  Pattern 2: A form that adds a command to the note 
The same architecture works in reverse: instead of only displaying data, the modal's JavaScript can POST back to a `SimpleAPI` endpoint that originates a command on the note. Here the modal content is inlined with `content=` and a `SimpleAPI` route handles the submission.
###  Action button rendering an inline form 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.action_button import ActionButton
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data.note import Note
    class AddDiagnosisButton(ActionButton):
        """ActionButton in the note header that lets users add diagnoses to the note."""
        BUTTON_TITLE = "Add Diagnosis"
        BUTTON_KEY = "ADD_DIAGNOSIS"
        BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_HEADER
        def handle(self) -> list[Effect]:
            note_dbid = self.event.context.get("note_id", "")
            note_id = Note.objects.filter(dbid=note_dbid).values_list("id", flat=True).first()
            patient_id = self.event.target.id
            context = {
                "note_id": note_id,
                "patient_id": patient_id,
                "api_endpoint": "/plugin-io/api/diagnosis_modal/diagnoses",
            }
            html_content = render_to_string("templates/add_diagnosis.html", context)
            return [
                LaunchModalEffect(
                    content=html_content,
                    target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
                    title="Add Diagnosis",
                ).apply()
            ]
    ```
###  Frontend JavaScript 
The template embeds the note ID and API endpoint, captures form input, and calls the endpoint with `fetch()`. Include the session cookie with `credentials: 'include'`:
    ```html
    <script>
        const noteId = "{{ note_id }}";
        const apiEndpoint = "{{ api_endpoint }}";
        document.getElementById('diagnosisForm').addEventListener('submit', async (e) => {
            e.preventDefault();
            const formData = {
                note_id: noteId,
                icd10_code: document.getElementById('icd10Code').value,
                background: document.getElementById('background').value,
                assessment: document.getElementById('assessment').value
            };
            const response = await fetch(apiEndpoint, {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                credentials: 'include',  // include session cookies
                body: JSON.stringify(formData)
            });
            const data = await response.json();
            // ... handle success/error in the UI
        });
    </script>
    ```
###  SimpleAPI endpoint that originates a command 
Use `StaffSessionAuthMixin` so only logged-in staff can call the endpoint. Parse the request, build the command, and return its `.originate()` effect alongside a JSON response:
    ```python
    from http import HTTPStatus
    from uuid import uuid4
    from canvas_sdk.commands import AssessCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import SimpleAPIRoute, StaffSessionAuthMixin
    from logger import log
    class AddDiagnosisAPI(StaffSessionAuthMixin, SimpleAPIRoute):
        """Adds a diagnosis command to a note. Only logged-in staff can call it."""
        PATH = "/diagnoses"
        def post(self) -> list[Response | Effect]:
            body = self.request.json()
            note_id = body.get("note_id")
            icd10_code = body.get("icd10_code")
            background = body.get("background", "")
            assessment = body.get("assessment", "")
            assess = AssessCommand(
                # Set command_uuid so the response can return the new command's ID.
                command_uuid=str(uuid4()),
                note_uuid=note_id,
                icd10_code=icd10_code,
                background=background,
                narrative=assessment,
            )
            log.info(f"Adding diagnosis {icd10_code} to note {note_id}")
            return [
                assess.originate(),
                JSONResponse(
                    {
                        "success": True,
                        "message": "Diagnosis added to note",
                        "command_id": assess.command_uuid,
                    },
                    status_code=HTTPStatus.CREATED,
                ),
            ]
    ```
###  Flow summary 
    ```text
    User clicks "Add Diagnosis" in the note header
      → ActionButton.handle() returns a LaunchModalEffect with HTML/JS (note_id embedded)
      → The modal form captures input and POSTs to the SimpleAPI endpoint
      → AddDiagnosisAPI authenticates (StaffSessionAuthMixin), builds an AssessCommand with the ICD-10 code
      → It calls .originate() and returns a JSON response
      → The Assess Condition command appears in the note body
    ```
##  One plugin or several? Grouping components 
Both patterns above register more than one component in a single plugin. When deciding whether to ship related components together or split them across plugins, keep these tradeoffs in mind:
  - **Deploy and update together.** Components in one plugin are installed, updated, and removed as a unit, so components that depend on one another are guaranteed to be deployed and updated together.
  - **They do not crash together.** If a handler errors on installation, only that affected handler fails to load — the others in the plugin still run. (Interdependent components can still misbehave if one is missing, so account for that.)
  - **Cache and pub/sub are scoped per plugin.** A plugin can only read and write its own [cache](/sdk/caching/) (keys are namespaced by plugin), and can only publish to its own [pub/sub](/sdk/handlers-simple-api-websocket/) channel (channels are namespaced too). If two components must share cached state or a channel, they need to live in the same plugin.
There are no known performance benefits or penalties to grouping itself.

---

# Choosing Your Patient Experience

Source: https://docs.canvasmedical.com/guides/choosing-your-patient-experience/

The first decision when building a patient-facing experience on Canvas isn't technical — it's about **how much of that experience you want to own**. Canvas gives you a spectrum: turn on our built-in patient portal as-is, extend it with plugins, or build your own patient app entirely and use Canvas as the clinical backend. This guide helps you pick the path that fits your product, team, and timeline — and points you to the how-to docs once you've decided.
> **Info:** There's no wrong door, and you're not locked in. Most teams start with the built-in portal and add custom pieces over time — the paths below are complementary, not one-way.
##  The three paths 
| **Use the built-in portal**| **Extend the built-in portal**| **Build your own**  
---|---|---|---  
**Who builds the UI**|  Canvas| Canvas + your plugins| You  
**Effort**|  Lowest| Medium| Highest  
**Control over look & flow**| Configuration| Configure, plus inject widgets, applications, and logic| Total  
**Patient data**|  Handled for you| Handled for built-in pages; you supply data to your own widgets & applications (Canvas data module, Custom Data, or external sources)| You read & write it via Canvas APIs  
**Best when**|  You want a working, compliant portal fast| The built-in portal is close, but you need extra pages, branding, or custom rules| You have (or want) your own branded app and use Canvas as the source of truth  
##  How to choose 
* * *
##  Path 1 — What's already built into Canvas 
When you sign with Canvas, you already have a full patient portal — no build, no plugins, nothing to stand up. Patients can log in (with their email, phone number, or username, plus a password) and use it from day one, and Canvas hosts it and handles the login, data, and compliance for you.
Out of the box it includes **messaging, payments, labs, and a contact page**. Other pages — **scheduling, My Health, health records, consents, and self-registration** — are built in too and ready to switch on whenever you want them.
Everything in this path is **configuration only — no plugins or code**. You decide which built-in pages appear and set basic branding; that's the whole effort.
###  Built-in pages you can turn on or off 
Each page is toggled with a **Constance** setting, managed by Canvas Support — so [contact Support](https://canvas-medical.help.usepylon.com/) to change them. For a full walkthrough, see [Managing the Patient Portal](https://canvas-medical.help.usepylon.com/articles/7348270931-managing-the-patient-portal).
Setting| Page| What patients can do| Default  
---|---|---|---  
`PATIENT_APP_MESSAGING`| Messaging| Securely message their care team| `True`  
`PATIENT_APP_PAYMENTS`| Payment| View and pay outstanding balances| `True`  
`PATIENT_APP_LABS`| Lab| View their lab results| `True`  
`PATIENT_APP_CONTACT`| Contact| See the practice's contact information| `True`  
`PATIENT_APP_MY_HEALTH`| My Health| Review conditions, medications, allergies, and related clinical info| `False`  
`PATIENT_APP_RECORDS`| Health Records| Access and download their health records| `False`  
`PATIENT_APP_APPOINTMENTS`| Scheduling flow| Book and view appointments| `False`  
`PATIENT_APP_CONSENTS`| Consents| Review and complete consents| `False`  
`PATIENT_APP_REGISTER`| Register| Self-register from the login page| `False`  
**Other portal settings:**
Setting| Controls| Default  
---|---|---  
`ENABLE_PATIENT_PORTAL`| Whole portal on/off| `True`  
`ALLOW_PATIENT_DOCUMENT_UPLOADS`| Patient document uploads on "My Health"| `False`  
`PATIENT_APP_USERS_EMAIL_ONLY`| Email-only login (access mode, not a page)| `False`  
`PATIENT_APP_BANNER`| Banner text on the portal login page| `""`  
`PATIENT_PORTAL_REQUISITION_ORDER_STATES`| Which orders patients can [download requisitions](/sdk/patient-portal/#link-to-lab-and-imaging-requisitions) for: **Open orders only** or **Open and completed orders**| **Open orders only**  
> **Warning:** Defaults are mixed, not all-off. Messaging, Payments, Labs, and Contact are on out of the box; My Health, Health Records, Appointments, Consents, and Register are off. So you typically turn off the stock pages you don't want and turn on the ones you do — rather than enabling everything from scratch.
###  Sign-in links in notifications 
When the care team sends a patient a message or shares a lab result, Canvas notifies the patient by email or text message. When the patient is sent a statement, Canvas notifies them by email. Each notification carries a sign-in link, so the patient can go straight to the new item without entering a password. Opening the link signs the patient in and opens the matching page: Messaging, Labs, or Payments.
  - **Each link works once.** The email and the text for the same notification carry separate links, so opening one doesn't invalidate the other. After a link has been used, the patient signs in with their password as usual.
  - **Links stay valid for 30 days** by default, so the patient can open one well after the notification arrives.
  - **The session lasts 15 minutes** by default. It doesn't extend while the patient is active; when it ends, the patient returns to the login page.
Both limits are organization settings managed by Canvas: the link lifetime is the `notificationLink` value (in seconds) in `accessTokenExpirationInSeconds`, and the session length is `magicLinkSessionInMinutes`. [Contact Support](https://canvas-medical.help.usepylon.com/) to change either one.
###  Branding 
You can put your organization's identity on the portal without building anything:
  - **Logo** — your organization's logo is shown on the login page and throughout the portal. It's configured on your Canvas organization; until you provide one, the default Canvas logo appears. Work with Canvas to set it.
  - **Banner message** — `PATIENT_APP_BANNER` sets a short greeting above the login card.
  - **Email sender for patient messages** — message and notification emails to patients are sent with **your organization's name** as the sender, from the address in your organization's `defaultEmail` setting (default `do-not-reply@canvasmedical.com`). You can change that address; using your own domain may require sender authentication set up with Canvas.
What stays **Canvas-driven** and isn't branded per organization:
  - **The portal URL** — patients sign in at `https://<your-instance>.canvasmedical.com/app/`.
  - **The login flow** — the sign-in and verification screens are Canvas's.
  - **Sign-in & verification emails** — these are sent from a fixed `no-reply@canvasmedical.com` (a separate path from the patient-message sender above), so they can't be rebranded.
> **Info:** Want your own domain and login flow end to end? That's Path 3 — build your own app and use Canvas as the backend.
* * *
##  Path 2 — Extend the built-in portal with plugins 
The built-in portal is a strong starting point — but it's rarely _exactly_ what you want. Path 2 is where you make it feel like **yours** : add the cards, pages, and rules your patients and workflows actually need, while Canvas keeps hosting the portal and handling login, data, and compliance. You never stand up your own app.
Under the hood, every extension is a plugin that **reacts to a portal event and returns an effect**. As patients move through the portal, your handler can add a widget, render a page, filter appointment slots, and so on.
New to plugins? Start with [Your First Plugin](/guides/your-first-plugin-with-claude-code/), then keep the [Patient Portal config hub](/sdk/patient-portal/) and the [portal events](/sdk/events/) handy. And for inspiration, the community-run [Medical Software Foundation library](https://github.com/medical-software-foundation/canvas) has production-ready portal extensions you can install or learn from — several are linked below.
Here's what you can do — mix and match as many as you like.
###  Personalize the landing page with widgets 
The portal home is the first thing patients see after logging in, and it's the easiest place to add value. **Widgets** are cards you render there: a "your next appointment" summary, an outstanding-balance nudge, a care-gap reminder ("you're due for a flu shot"), links to your own resources — anything you can compute for that patient.
You control what each card shows, pulling from the Canvas data module, your plugin's Custom Data, or an external service.
See [Portal Landing Page Widgets](/sdk/patient-portal/#portal-landing-page-widgets) and the [Custom Landing Page guide](/guides/custom-landing-page/) for the exact documentation on how to build them. And you don't have to start from a blank file — there's a ready-made [patient_portal_plugin](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/patient_portal_plugin) in our open-source examples repo you can install as-is or use as a reference and starting point.
###  Shape self-scheduling 
Self-scheduling is powerful, but you'll usually want guardrails. Filter or reorder the slots a patient can book _before they see them_ — keep new patients on longer visit types, hide same-day slots, steer certain reasons to specific providers, or enforce your booking policies.
See [Shape Self-Scheduling](/sdk/patient-portal/#shape-self-scheduling) · SDK example: [patient_portal_search_appointments_slots_plugin](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/patient_portal_search_appointments_slots_plugin).
Real-world example (MSF):
  - [urgent-care-self-scheduler](https://github.com/medical-software-foundation/canvas/tree/main/extensions/urgent-care-self-scheduler) — adds a "Need to be seen today?" portal card and a full self-booking flow that offers only credentialed providers, blocks duplicate bookings, and pre-populates the visit note. A good end-to-end model.
###  Tailor appointment cards 
Fine-tune the actions on each appointment. Hide **Cancel** or **Reschedule** when your policy says so (for example, no reschedule within 24 hours of the visit), or add a **telehealth join link** to virtual appointments — decided per appointment.
See [Customize Appointment Cards](/sdk/patient-portal/#customize-appointment-cards).
Real-world example (MSF):
  - [portal_disable_cancel_appts](https://github.com/medical-software-foundation/canvas/tree/main/extensions/portal_disable_cancel_appts) — answers the "can this appointment be canceled?" check with _no_ , removing the self-service Cancel action so cancellations route through staff.
###  Surface forms and react to responses 
Meet patients with the right questionnaire at the right moment — an intake packet before a first visit, a PHQ-9 for a behavioral-health appointment, a post-visit survey — and act on what they submit. Forms are surfaced to the patient when they log in to the portal: you choose which ones appear, then react to responses to store the answers or trigger follow-up. Responses are saved as Interviews, and you can even generate a Questionnaire command in the patient's note.
See the [Patient Portal effects → Forms](/sdk/patient-portal/#forms) for the technical reference.
###  Automate login and activation 
Getting patients into the portal doesn't have to be manual. Automatically **invite** patients to activate their account when they're ready — for example, once you've confirmed a good email or phone — instead of having staff send invitations one at a time. You can also keep a patient's portal **login in sync** when their email or phone changes, and **verify** a contact point before you rely on it to invite them or send messages.
Prefer to send the invite yourself? A plugin can mint the patient's activation or password reset link and deliver it through your own email or SMS provider, with your own wording and branding. You choose where in the portal the link lands the patient, such as their appointments or one of your own portal pages.
See [User Login](/sdk/patient-portal/#user-login) for automating invitations and keeping the login in sync, [Getting a patient portal login link](/sdk/utils/#getting-a-patient-portal-login-link) for minting a link to send yourself, and [Send Contact Verification](/sdk/effect-send-contact-verification/) for confirming a contact point first.
###  Greet patients as soon as they sign in 
The moment right after login is the natural place to ask for something before the patient goes anywhere else: collect a consent, walk a new patient through a short tour, or show an alert about an upcoming visit or a balance due. The [`PATIENT_PORTAL__POST_LOGIN`](/sdk/events/#patient-portal-events) event fires once each time a patient signs in, and your plugin can respond by opening a **modal** over the page they land on.
The event tells you how the patient signed in: with their username and password, with the sign-in link from a notification, or by registering. That lets you, for example, welcome a newly registered patient differently from one who signs in every week. Refreshing the page or returning with a remembered session doesn't count as a new sign-in, so patients aren't shown the same modal over and over.
Modals aren't limited to sign-in. Any handler that runs because of something the patient did can open one in the portal, for example a [SimpleAPI](/sdk/handlers-simple-api-http/) route your portal page calls. The modal appears if the patient still has the portal open.
When the patient has to finish the step before going further, such as signing a consent, make the modal **blocking**. The patient can't close it or navigate away, and it closes only when your page says the step is done.
See [Show a Modal After Login](/sdk/patient-portal/#show-a-modal-after-login), [Modals](/sdk/layout-effect/#modals), and [Blocking Modals](/sdk/layout-effect/#blocking-modals) for the technical reference.
###  Share after-visit summaries 
Patients can download the after-visit summary of their own locked visit notes from the portal, as the same PDF a clinician prints from the note. The portal doesn't link to it on its own, so you decide where patients find it: a "your visit summary is ready" widget on the landing page, a visit history page of your own, or a link in a follow-up message.
Each download fires an event your plugin can respond to, so you can keep track of which patients have received their summary and follow up with the ones who haven't.
See [Link to After-Visit Summaries](/sdk/patient-portal/#link-to-after-visit-summaries) for the technical reference.
###  Share lab and imaging requisitions 
Patients can also download the requisition of their own lab and imaging orders. A lab requisition is the form a clinician prints from the order. An imaging requisition is the letter that tells the patient how to prepare for the test. As with summaries, you decide where the link appears, such as next to an upcoming lab visit on a page of your own. By default, a requisition is available until results arrive for the order. Canvas Support can extend that to completed orders with the `PATIENT_PORTAL_REQUISITION_ORDER_STATES` setting.
Downloads fire the same event as summaries, so one handler can track every document a patient has received.
See [Link to Lab and Imaging Requisitions](/sdk/patient-portal/#link-to-lab-and-imaging-requisitions) for the technical reference.
###  Control the navigation layout 
Decide which items appear in the portal navigation and in what order — and do it **conditionally per patient**. Surface a page only to patients in a certain program, reorder the menu so what matters most comes first, or hide built-in items you don't use. The navigation isn't fixed; you compute it for each patient every time the portal loads.
See [Configure Portal Menu Items](/sdk/patient-portal/#configure-portal-menu-items).
###  Add your own pages 
Need more than a card? Add entire patient-facing **pages** with an Application scoped to the patient portal — a program dashboard, an intake wizard, a financial-assistance flow, an education library. The page lives inside the portal (same URL, same login, same navigation), but its UI and logic are entirely yours.
This is also how you **replace a built-in page you don't love**. Don't like how the stock My Health page presents conditions, medications, and allergies? Build your own version exactly the way you want it, then turn off the built-in page with its Path 1 toggle (`PATIENT_APP_MY_HEALTH`) so patients only ever see yours. The same works for any built-in section — keep the stock pages that suit you and swap out the ones that don't, one at a time.
You can go further and make one of your pages the portal's **home page**. Patients who open the portal land on your page instead of the widgets landing page, with any consents, forms, and sign-in modals still shown on top. While a home page is set, patients don't see landing page widgets, so choose one approach or the other. See [Configuring the Patient Portal](/sdk/patient-portal/#configuring-the-patient-portal).
See the [Applications handler](/sdk/handlers-applications/) and [Configure Portal Menu Items](/sdk/patient-portal/#configure-portal-menu-items) for surfacing your page in the portal navigation · SDK examples: [example_patient_portal_page](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/example_patient_portal_page), [patient_app_schedule](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/patient_app_schedule).
Real-world examples (MSF):
  - [patient-portal-profile](https://github.com/medical-software-foundation/canvas/tree/main/extensions/patient-portal-profile) — adds a read-only **My Profile** page (demographics, care team, preferred pharmacy).
  - [portal-content](https://github.com/medical-software-foundation/canvas/tree/main/extensions/portal-content) — builds richer **My Records** and **My Profile** pages (visit notes, labs, imaging, letters, insurance) with optional review-gating. A great model for replacing the stock pages with your own.
  - [patient-portal-forms](https://github.com/medical-software-foundation/canvas/tree/main/extensions/patient-portal-forms) — ships a whole forms experience as its own portal page: staff assign questionnaires (PHQ-9, GAD-7, ROS…) that patients complete in the portal, with responses posting back to the chart.
###  Collect insurance cards and photo IDs 
Let patients send what your front desk usually chases down at check-in: photos of their insurance card, a driver's license or other photo ID, or a document their care team asked for. Add an upload step to one of your own portal pages, such as an intake wizard or a pre-visit checklist, and the files land on the patient's record in Canvas without staff scanning or re-keying anything.
Your page posts the patient's files to a [SimpleAPI](/sdk/handlers-simple-api-http/) route that [stores uploads](/sdk/handlers-simple-api-http/#storing-uploaded-files). Canvas saves each file before your handler runs and hands your handler a key for it. Protect the route with the [patient session mixin](/sdk/handlers-simple-api-http/#patient-session) so only signed-in patients can call it, then pass each key to the effect that fits:
  - **Insurance card:** the [Coverage](/sdk/effect-coverage/) effect adds or updates the patient's coverage with front and back card images. Collect the member ID and payer on the same page, since a new coverage needs both.
  - **Photo ID:** the [Patient Identification Card](/sdk/effect-patient-identification-card/) effect adds the image to the patient's identification cards.
  - **Anything else:** the [Message](/sdk/effect-messages/#attaching-files) effect attaches PNG, JPEG, or PDF files to a message to the care team.
See [Storing uploaded files](/sdk/handlers-simple-api-http/#storing-uploaded-files) for the full list of effects that accept an upload, and the example route on the [Coverage](/sdk/effect-coverage/) effect page that creates a coverage from uploaded card photos.
###  Send patients to another page 
Your pages can move the patient along when they finish a step: after they submit an intake form, take them to their messages; from a "schedule your follow-up" card on the landing page, open your scheduling page; when a step happens on a partner's site, send them there.
When the patient does something in your page or widget, the handler that responds, such as a [SimpleAPI](/sdk/handlers-simple-api-http/) route your page calls, returns a redirect. Within the portal, the patient moves without a page reload, and Back returns them to where they were. A redirect can go to:
  - a built-in portal page that is turned on for your instance, such as Messages or Appointments
  - one of your own portal pages
  - an external URL, in the same tab or a new one
Each destination has to be on your plugin's allowlist, which an administrator sets for each instance, so a plugin can only send patients where you've approved.
See [Redirects in the patient portal](/sdk/effect-redirect/#redirects-in-the-patient-portal) for the technical reference.
###  Missing something? Ask before you rebuild 
Customizing the portal puts you in the best position to see what's missing. If you hit something plugins can't do in the portal yet, requesting a **new SDK capability** is often a better move than jumping to building your own (Path 3) — it can unlock what you need _inside_ the built-in portal, so you keep everything Canvas handles for you (login, data, compliance) instead of rebuilding it. Many of today's patient-portal capabilities exist because customers asked for them.
> **Info:** Hitting the edge of what plugins can do in the portal? Tell your Canvas contact or Support what you're trying to build. A new SDK capability may unlock it inside the portal — and your request helps shape what we build next for everyone.
* * *
##  Path 3 — Build your own patient app on Canvas data 
If you want a fully branded app — your own UI, your own login — build it as an external application and use Canvas as the clinical source of truth. You move data between your app and Canvas in three **complementary** ways; most portals use a combination, because each fits a different job and has its own authentication model.
  - **[FHIR API](/api/)** and **[SimpleAPI](/sdk/handlers-simple-api-http/)** are calls _from your app into Canvas_ — **Canvas authenticates you**.
  - **[Events → webhooks](/sdk/events/)** are calls _from Canvas out to your app_ — **you authenticate Canvas**.
A typical combination:
  - **FHIR API** for the bulk of standard reads and writes (patients, appointments, conditions, coverage…).
  - **SimpleAPI** where you need something FHIR doesn't expose, a tailored/bundled response, or custom data — your app hits one plugin endpoint instead of stitching several calls.
  - **Events → webhooks** to keep your app in sync as things change in Canvas, instead of polling.
###  FHIR API — read & write standard Canvas data directly 
**Best for:** standard resources (Patient, Appointment, Condition, Coverage, etc.) read or written straight from your app.
**Auth (your app → Canvas):** Canvas issues OAuth2 tokens with SMART on FHIR scopes. For a portal where a patient logs in and must only see their **own** record, use a [patient-scoped token](/api/customer-authentication/#patient-scoped-tokens) — it's locked to a single patient and Canvas enforces it server-side, so any read or write touching another patient is rejected. See [Customer Authentication](/api/customer-authentication/) for the full flow, scopes, and the `user/` and `system/` contexts.
See the [FHIR API reference](/api/) and [Auth best practices](/api/authentication-best-practices/).
Examples:
  - [canvas_fhir_client](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/canvas_fhir_client) (SDK) — a Python client that authenticates and reads/writes Canvas FHIR resources.
  - [cms-access-fhir-client](https://github.com/medical-software-foundation/canvas/tree/main/extensions/cms-access-fhir-client) (MSF) — FHIR-client mechanics in action (OAuth plus a full request/response exchange), here integrating with the external CMS ACCESS FHIR APIs.
###  SimpleAPI — build the exact endpoints your app wishes Canvas had 
Where FHIR gives you standard resources, **SimpleAPI lets you define your own** — you own the URL, the request, and the JSON response shape, all running inside a Canvas plugin. Instead of bending your app to fit a generic API, you build the endpoint your app actually wants and call it directly.
_New to the idea? Read the announcement:[Introducing Custom API Endpoints with the Canvas SDK](https://www.canvasmedical.com/articles/introducing-custom-api-endpoints)._
This is where SimpleAPI shines:
  - **Shape the payload to your UI.** Return exactly the fields a screen needs, already assembled — no over-fetching, no reshaping FHIR bundles on the client.
  - **Collapse many calls into one.** Bundle related reads and writes into a single round-trip, so a screen that would take five FHIR calls takes one. Fewer requests, simpler client code, faster load.
  - **Reach data FHIR doesn't expose.** Surface your plugin's own [Custom Data](/sdk/custom-data/), computed values, or anything else in the [data module](/sdk/data/).
  - **Run your logic server-side, next to the data.** Validation, orchestration, and business rules live in the plugin — close to Canvas and behind your key — instead of scattered across your app.
Reads come from the [data module](/sdk/data/); writes go through [Effects](/sdk/effects/) and [Commands](/sdk/commands/) (the SDK data models are read-only).
**Auth (your app → Canvas):** an **API key** — declare a secret in the plugin and send it in the `Authorization` header (`APIKeyAuthMixin`). Simple, and the right choice for an external caller.
See [SimpleAPI HTTP handlers](/sdk/handlers-simple-api-http/).
SDK examples:
  - [api_samples](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/api_samples) — start here; the core request/response patterns.
  - [charting_api_examples](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/charting_api_examples) — endpoints that read and write chart data.
  - [note_management_app](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/note_management_app) — a fuller app built on SimpleAPI endpoints.
  - [custom_data_room_booking](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/custom_data_room_booking) — endpoints backed by Custom Data.
Real-world examples (MSF):
  - [lab-result-api](https://github.com/medical-software-foundation/canvas/tree/main/extensions/lab-result-api) — one `GET /lab-result/<id>` returns a lab report with its patient, originating order, ordering provider, and nested result values assembled into a single response. A textbook "collapse many calls into one, shaped to your UI" endpoint.
  - [cpt-billing-api](https://github.com/medical-software-foundation/canvas/tree/main/extensions/cpt-billing-api) — a write endpoint that adds CPT billing line items to a note from an external caller.
  - [note-command-api](https://github.com/medical-software-foundation/canvas/tree/main/extensions/note-command-api) — read notes with enhanced command data, and create notes via `POST /create-note` with flexible identifier lookup.
  - [custom-observation-management](https://github.com/medical-software-foundation/canvas/tree/main/extensions/custom-observation-management) — an API-key-authed read/write API over a clinical resource: `GET` a single observation, a filtered list, or the available filters, and `POST` to record a new one.
###  Events → webhooks — Canvas pushes changes to your app the moment they happen 
Instead of your app constantly polling Canvas asking "anything new?", **let Canvas tell you.** A plugin subscribes to the events you care about — an appointment booked, a task created, a patient updated — and POSTs to your endpoint the instant it happens.
Why reach for webhooks:
  - **Real-time sync, no polling.** Keep an external system current — a billing platform, a CRM, a data warehouse, your own app's database — the moment data changes, instead of nightly jobs that are always a little stale. For example, a patient gives the front desk an updated address; a webhook pushes that change to your app so it's already reflected the next time they log in to your portal.
  - **Trigger downstream workflows.** Fire an appointment reminder, page a care team, kick off a prior-auth, or open a ticket in your system as soon as the triggering event lands.
  - **Fan out from one event.** A single Canvas change can notify several systems at once, each with the payload it needs.
  - **Lower latency and load.** You react in seconds and skip the wasted requests — and the changes missed between polls — that polling brings.
**Auth (Canvas → your app — reversed):** **you** secure your receiving endpoint. The plugin sends a shared secret/signature (stored as a plugin secret) that your app verifies; no Canvas token is involved on the inbound call.
See the [SDK Events reference](/sdk/events/), the [HTTP Request effect](/sdk/effect-http-request/), and the [Creating Webhooks guide](/guides/creating-webhooks-with-the-canvas-sdk/).
SDK examples:
  - [example_patient_sync](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/example_patient_sync) — push patient changes to an external system on create/update.
  - [coverage_metadata_sync](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/coverage_metadata_sync) — sync coverage metadata when it changes.
Real-world examples (MSF):
  - [appointment-sync-webhook](https://github.com/medical-software-foundation/canvas/tree/main/extensions/appointment-sync-webhook) — POSTs appointment lifecycle events (created, cancelled, no-show) to an external system as they happen.
  - [task_webhook_notification](https://github.com/medical-software-foundation/canvas/tree/main/extensions/task_webhook_notification) — sends a customizable payload to your endpoint whenever a task is created or updated.
  - [gcal_sync](https://github.com/medical-software-foundation/canvas/tree/main/extensions/gcal_sync) — near-real-time two-way sync between Canvas appointments and Google Calendar, with Canvas as the system of record.
* * *
##  Still deciding? 
  - Want a portal live quickly with minimal effort → **Path 1** , and [contact Support](https://canvas-medical.help.usepylon.com/) to set the page toggles.
  - Happy with the built-in portal but need a few custom touches → **Path 2** ; skim the [Patient Portal config hub](/sdk/patient-portal/).
  - Building your own branded experience → **Path 3** ; start with the [FHIR API](/api/) and add SimpleAPI and webhooks as needed.

---

# Creating Webhooks With the Canvas SDK

Source: https://docs.canvasmedical.com/guides/creating-webhooks-with-the-canvas-sdk/

Webhooks are user-defined callbacks that make a request to an API. You may want to create a webhook to notify a system you control that some event has occurred in Canvas. This guide shows how to create a webhook that sends an API request containing the ID of a Task upon its creation.
> **Info:** This guide assumes pre-existing knowledge of the Canvas SDK. If you're starting from scratch, you may want to read and implement [Your First Plugin (with Claude Code)](/guides/your-first-plugin-with-claude-code/) before working through this exercise.
##  Initialize a new plugin 
The Canvas CLI gives you a great head start when creating a plugin. Run `canvas init`, and answer the prompt to name your plugin.
    ```sh
    $ canvas init
      [1/1] project_name (My Cool Plugin): Task Webhook
    Project created in /Users/andrew/src/canvas-plugins/task-webhook
    Registered acme__task_webhook with Canvas Platform.
    ```
This output shows the location of our freshly generated plugin. If you're signed in to Canvas Platform with [`canvas login`](/sdk/canvas_cli/#signing-in-to-canvas-platform), `canvas init` names the package with your organization's prefix, such as `acme__task_webhook`, and registers it with Canvas Platform. It also makes the project folder a git repository that [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy) pushes to.
##  Edit the plugin code 
The default content of this file shows you the information you have available to you in the comments. I've stripped it down to almost nothing so we can layer in the functionality step by step.
###  Log a message when a task is created. 
The code below listens for the `TASK_CREATED` event and logs the string "A Task was created!".
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    class Handler(BaseHandler):
        """
        When a task is created, log a message
        """
        RESPONDS_TO = EventType.Name(EventType.TASK_CREATED)
        def compute(self):
            """
            Log a message as tasks are created.
            """
            log.info("A Task was created!")
            return []
    ```
You can see this log output by first streaming logs with `canvas logs` and then creating a task. You can create this task with Canvas Chat, a Task Command, or our [FHIR Task Create endpoint](/api/task/#create).
After you've [deployed your plugin](/sdk/canvas_cli/#canvas-deploy) and created a task, you should see this in your log stream:
    ```sh
    INFO 2024-09-26 17:04:08,396 Starting server, listening on port 50051
    INFO 2024-09-26 17:04:08,396 Loading custom-plugins/acme__task_webhook
    INFO 2024-09-26 17:04:08,396 Loading plugin 'acme__task_webhook:acme__task_webhook.handlers.event_handlers:Handler'
    INFO 2024-09-26 17:04:24,410 A Task was created!
    ```
Awesome! But we're not here to log, we need to make an API request. To do that, we need to use the HTTP client found in the Canvas SDK's [Utils module](/sdk/utils/)
###  Make an HTTP request when a Task is created 
We can use <https://webhook.site/> for a quick way to test our webhook and see the requests it receives. Here is the updated code that uses the HTTP client to make the request:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.utils import Http
    from logger import log
    class Handler(BaseHandler):
        """
        When a task is created, hit a webhook
        """
        RESPONDS_TO = EventType.Name(EventType.TASK_CREATED)
        def compute(self):
            """
            Notify our server of tasks as they are created.
            """
            url = "https://webhook.site/ee7aed78-b652-4d9e-b858-04465c409d15"
            payload = {
                "message": "A Task was created!"
            }
            http = Http()
            response = http.post(url, json=payload)
            if response.ok:
                log.info("Successfully notified API of task creation!")
            else:
                log.info("Notification unsuccessful. =[")
            return []
    ```
After you've [deployed your updated plugin](/sdk/canvas_cli/#canvas-deploy) and created a task, you should see this in your log stream:
    ```sh
    INFO 2024-09-26 17:18:23,206 Loading custom-plugins/acme__task_webhook
    INFO 2024-09-26 17:18:23,207 Reloading plugin 'acme__task_webhook:acme__task_webhook.handlers.event_handlers:Handler'
    INFO 2024-09-26 17:18:33,850 Successfully notified API of task creation!
    ```
One thing worth mentioning here: making HTTP requests to external servers will slow plugin execution while it waits on the external server to respond. It's a good idea to make sure the servers you're hitting have a sufficiently quick response time.
Checking in on our webhook.site logs shows it received our request! ![Log of web
request](/assets/images/webhook-guide/webhook-guide-first-request.png)
Awesome, but you aren't sending these requests to a server that allows unauthenticated requests! And this request doesn't even tell you anything about the task it's notifying you about. This isn't useful at all!
Let's do another iteration, this time using the information provided along with the event so that we can send a usable message, securely. We're specifically going to incorporate the event's `target` and `secrets`.
###  Make an authenticated HTTP request that includes the newly created Task's ID 
Within your `Handler` class, you have access to `self.target`, which represents the ID of the subject of the event. In our case, it will be the Task's ID. This is the same ID used in the [FHIR Task endpoints](/api/task/), so you can use it to make FHIR API requests.
You also have access to `self.secrets`, which is a python dictionary containing the key-value pairs from your plugins configuration page. You declare the keys in your [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#variables), and can then set the values after the plugin is installed.
We'll set two secrets, one for the unique id of the webhook, and one for an auth token. Here's what the manifest file looks like with secrets declared:
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "acme__task_webhook",
        "description": "Webhooks for task creation",
        "components": {
            "handlers": [
                {
                    "class": "acme__task_webhook.handlers.event_handlers:Handler",
                    "description": "Hit an API when a task is created",
                    "data_access": {
                        "event": "",
                        "read": [],
                        "write": []
                    }
                }
           ]
        },
        "variables": [
            {"name": "WEBHOOK_ID", "sensitive": true},
            {"name": "AUTH_TOKEN", "sensitive": true}
        ],
        "tags": {},
        "license": "",
        "readme": "./README.md"
    }
    ```
The `variables` array declares two sensitive variables, `WEBHOOK_ID` and `AUTH_TOKEN`. After we update the plugin, we can set values for these in the plugin configuration page. This allows for different values to be used across different installations. Marking each entry with `"sensitive": true` means the values will be masked in the Admin UI and listed only as `[set]` or `[not set]` by `canvas config list`.
You can also set them from the CLI with [`canvas config set`](/sdk/canvas_cli/#canvas-config-set):
    ```console
    $ canvas config set acme__task_webhook WEBHOOK_ID=<webhook-id> AUTH_TOKEN=<auth-token> --instance <instance>
    ```
Here's how that configuration looks in the plugin configuration page:
![Plugin secrets
configuration](/assets/images/webhook-guide/webhook-guide-secrets.png)
With those values set, we can use them in our code:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.utils import Http
    from logger import log
    class Handler(BaseHandler):
        """
        When a task is created, hit a webhook
        """
        RESPONDS_TO = EventType.Name(EventType.TASK_CREATED)
        def compute(self):
            """
            Notify our server of tasks as they are created.
            """
            url = f"https://webhook.site/{self.secrets['WEBHOOK_ID']}"
            headers = {
                "Authorization": f"Bearer {self.secrets['AUTH_TOKEN']}"
            }
            payload = {
                "message": "A Task was created!",
                "resource_id": self.target
            }
            http = Http()
            response = http.post(url, json=payload, headers=headers)
            if response.ok:
                log.info("Successfully notified API of task creation!")
            else:
                log.info("Notification unsuccessful. =[")
            return []
    ```
And checking once more on our webhook.site logs shows it received our updated request, including our `AUTH_TOKEN` value and the created task's ID.
![Log of web
request](/assets/images/webhook-guide/webhook-guide-second-request.png)
##  Listening for multiple events 
A single plugin handler can listen for multiple event types. The event type will be available in `self.event.type`, which will contain a member of the `EventType` enum. The [full list of events is available](/sdk/events/#event-types-and-context). Here is a short example that listens for two different events:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.utils import Http
    from logger import log
    class Handler(BaseHandler):
        """
        When a task is created or updated, hit a webhook
        """
        RESPONDS_TO = [
            EventType.Name(EventType.TASK_CREATED),
            EventType.Name(EventType.TASK_UPDATED),
        ]
        def compute(self):
            """
            Notify our server of tasks as they are created.
            """
            url = f"https://webhook.site/{self.secrets['WEBHOOK_ID']}"
            headers = {"Authorization": f"Bearer {self.secrets['AUTH_TOKEN']}"}
            # self.event.type is a member of the EventType enum corresponding to
            # one of the event types in the handler's RESPONDS_TO attribute
            verb = 'created' if self.event.type == EventType.TASK_CREATED else 'updated'
            payload = {
                "message": f"A Task was {verb}!",
                "resource_id": self.target,
            }
            http = Http()
            response = http.post(url, json=payload, headers=headers)
            # You can also get the name of the event as as string using EventType.Name()
            event_name = EventType.Name(self.event.type)
            if response.ok:
                log.info(f"Successfully notified API of {event_name}")
            else:
                log.info(f"Notification of {event_name} unsuccessful. =[")
            return []
    ```
Alternatively, you could include several classes, each resposible for some specific request type. When including several classes in one plugin, they all have access to the same secrets dictionary, you just need to declare each class in the manifest file.
##  Conclusion 
I hope you found this helpful. Happy coding, we can't wait to see what you build!

---

# Building a Custom Portal Landing Page

Source: https://docs.canvasmedical.com/guides/custom-landing-page/

This guide provides examples of how to leverage patient data to personalize the portal landing page, and explains how to integrate the ready-made widgets provided by Canvas.
> **Info:** This guide assumes pre-existing knowledge of the Canvas SDK. If you're starting from scratch, you may want to read and implement [Your First Plugin (with Claude Code)](/guides/your-first-plugin-with-claude-code/) before working through this exercise.
##  What Are Widgets in the Patient Portal? 
[Widgets](/sdk/patient-portal/#portal-landing-page-widgets) in the patient portal are interactive components that enhance the user experience by providing quick access to information and functionalities. They can display key details like upcoming appointments. Widgets can be fully customized with unique content or leverage ready-made components—such as Appointments and Messaging provided by Canvas to ensure consistency and ease of use. These widgets are organized on the landing page using a grid layout, which supports various sizes to optimize the visual presentation and responsiveness across different devices.
##  How to add a Widget? 
A widget can be added by listening to the `PATIENT_PORTAL__WIDGET_CONFIGURATION` event and returning one or several `PortalWidget`
###  Step 1: Initialize a plugin 
The Canvas CLI gives you a great head start when creating a plugin. Run
    ```bash
      canvas init
    ```
Then, follow the prompts to name and configure your new plugin project. If you're signed in to Canvas Platform with [`canvas login`](/sdk/canvas_cli/#signing-in-to-canvas-platform), `canvas init` names the package with your organization's prefix, such as `acme__my_cool_plugin`, and registers it with Canvas Platform. It also makes the project folder a git repository that [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy) pushes to.
###  Step 2: Update your handler 
Modify your handler to handle the widget configuration event. For example:
    ```python
    from canvas_sdk.effects.widgets import PortalWidget
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class Handler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__WIDGET_CONFIGURATION)
        def compute(self):
            widget = PortalWidget(
              content="Hello World",
              size=PortalWidget.Size.COMPACT,
              priority=10
            )
            return [widget.apply()]
    ```
This code listens for the `PATIENT_PORTAL__WIDGET_CONFIGURATION` event and, when triggered, creates a new widget with a simple "Hello World" message, a compact size, and a priority of 10.
##  Patient medication widget 
This widget will show the last medication and CTA to request a refill.
So let's update the example above to:
  - Fetch the patient's medication.
  - Leverage [HTML templating](/sdk/layout-effect/#custom-html-and-django-templates) to display the necessary information
###  Step 1: Fetch patient medication 
Since the event includes the patient object, you can easily access all the necessary data. Add the following snippet to your compute method to retrieve the patient's details:
    ```python
    patient = Patient.objects.get(id=self.target)
    last_medication = patient.medications.last()
    ```
###  Step 2: Prepare HTML template 
Create a `templates` folder inside your plugin's folder:
    ```bash
      mkdir templates
    ```
Add the HTML file:
    ```bash
      touch medication_widget.html
    ```
And add the following HTML:
    ```html
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <style>
        body, html {
          height: 100%;
          width: 100%;
          margin: 0;
          font-family: "Roboto","Helvetica","Arial",sans-serif;
          font-size: 16px;
        }
      </style>
    </head>
    <body>
    </body>
    </html>
    ```
###  Step 3: Design your widget 
> **Info:** Developers are responsible for providing all the necessary CSS to style their widget. The widget does not include default styles, so you should include custom CSS—either inline or via an external stylesheet—to define the layout, typography, colors, spacing, and interactive elements.
While you can design your widget in any way that suits your needs, for this example we'll create one featuring a header and a card component. The card will display the medication name, the prescription date, and a clear call-to-action (CTA) button that redirects the patient to the messaging page to request a refill.
####  Header 
A light gray background color and a blue text to ensure it matches the patient portal aesthetic.
    ```html
    <style>
      .header {
          padding: 8px;
          background: #E5E5E5;
          color: #2185D0;
          text-align: left;
          margin: 0;
          font-weight: 500;
          font-size: 18px;
          line-height: 1.6;
        }
    </style>
    <body>
        <div class="header">My Health</div>
    </body>
    ```
####  Card Component 
We will add template variables for the medication name and start date, allowing these values to be dynamically updated in the plugin.
    ```html
    <body>
      <div class="widget">
        <div class="medication-info">
          <span class="material-icons">medication</span>
          <span>{{name}}</span>
        </div>
        <p style="padding: 0 12px">This medication was prescribed on {{start_date}}. Do you need a refill?</p>
        <button onclick="onClick()">Ask for a refill</button>
      </div>
      <script>
        function onClick() {
          window.top.location.href = "http://localhost:8000/app/messaging"
        }
      </script>
    </body>
    ```
Let's dive in and add some styles to the card.
Our `widget` class ensures that all elements are both vertically and horizontally centered, creating a sleek card design with rounded borders and a subtle shadow for a modern, elevated look.
    ```css
    .widget {
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      width: 98%;
      height: 80%;
      border-radius: 4px;
      box-shadow: 0 2px 1px -1px rgba(0, 0, 0, 0.2), 0 1px 1px 0 rgba(0, 0, 0, 0.14), 0 1px 3px 0 rgba(0, 0, 0, 0.12);
      background-color: #f9f9f9;
      text-align: center;
      margin: 4px auto auto;
    }
    ```
Our medication info section will feature a Material UI icon next to the medication name, providing a clear and modern visual representation consistent with the portal's design aesthetic.
    ```css
    .medication-info {
      display: flex;
      align-items: center;
      gap: 10px;
      margin-bottom: 15px;
      padding: 0 8px;
      font-size: 14px;
    }
    .material-icons {
      font-size: 50px;
    }
    ```
And finally, we style the CTA button to mimic a Material UI button, ensuring it aligns perfectly with the portal's overall design aesthetic.
    ```css
    button {
      margin-top: 16px;
      background-color: #1976d2;
      color: #fff;
      border: none;
      border-radius: 4px;
      padding: 16px 16px;
      font-size: 14px;
      min-width: 64px;
      text-transform: uppercase;
      box-shadow: 0 3px 1px -2px rgba(0,0,0,0.2),
                  0 2px 2px 0 rgba(0,0,0,0.14),
                  0 1px 5px 0 rgba(0,0,0,0.12);
      cursor: pointer;
      transition: background-color 0.3s ease;
    }
    button:hover {
      background-color: #115293;
    }
    ```
###  Step 4: Tying everything together 
Update your plugin's `compute` method to pass the desired values for medication name and start date using `render_to_string` function
    ```python
    medication_info = {
        "start_date": last_medication.start_date.strftime("%B %d, %Y"),
        "name": last_medication.codings.first().display
    }
    widget = PortalWidget(content=render_to_string("templates/medication_widget.html", medication_info), size=PortalWidget.Size.COMPACT, priority=10)
    ```
![medication widget](/assets/images/sdk/widgets/patient_medication_widget.png)
###  Full Example 
    ```python
    from canvas_sdk.effects.widgets import PortalWidget
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Patient
    class Handler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__WIDGET_CONFIGURATION)
        def compute(self):
            patient = Patient.objects.get(id=self.target)
            last_medication = patient.medications.last()
            medication_info = {
                "start_date": last_medication.start_date.strftime("%B %d, %Y"),
                "name": last_medication.codings.first().display
            }
            medication_widget = PortalWidget(
              content=render_to_string("templates/medication_widget.html", medication_info),
              size=PortalWidget.Size.COMPACT,
              priority=10
            )
            return [medication_widget.apply()]
    ```
    ```html
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
      <style>
        body, html {
          height: 100%;
          width: 100%;
          margin: 0;
          font-family: "Roboto","Helvetica","Arial",sans-serif;
          font-size: 16px;
        }
        .widget {
          display: flex;
          flex-direction: column;
          justify-content: center;
          align-items: center;
          width: 98%;
          height: 80%;
          border-radius: 4px;
          box-shadow: 0 2px 1px -1px rgba(0, 0, 0, 0.2), 0 1px 1px 0 rgba(0, 0, 0, 0.14), 0 1px 3px 0 rgba(0, 0, 0, 0.12);
          background-color: #f9f9f9;
          text-align: center;
          margin: 4px auto auto;
        }
        .header {
          padding: 8px;
          background: #E5E5E5;
          color: #2185D0;
          text-align: left;
          margin: 0;
          font-weight: 500;
          font-size: 18px;
          line-height: 1.6;
        }
        .medication-info {
          display: flex;
          align-items: center;
          gap: 10px;
          margin-bottom: 15px;
          padding: 0 8px;
          font-size: 14px;
        }
        .material-icons {
          font-size: 50px;
        }
        button {
          margin-top: 16px;
          background-color: #1976d2;
          color: #fff;
          border: none;
          border-radius: 4px;
          padding: 16px 16px;
          font-size: 14px;
          min-width: 64px;
          text-transform: uppercase;
          box-shadow: 0 3px 1px -2px rgba(0,0,0,0.2),
                      0 2px 2px 0 rgba(0,0,0,0.14),
                      0 1px 5px 0 rgba(0,0,0,0.12);
          cursor: pointer;
          transition: background-color 0.3s ease;
        }
        button:hover {
          background-color: #115293;
        }
      </style>
    </head>
    <body>
      <div class="header">My Health</div>
      <div class="widget">
        <div class="medication-info">
          <span class="material-icons">medication</span>
          <span>{{name}}</span>
        </div>
        <p style="padding: 0 12px">This medication was prescribed on {{start_date}}. Do you need a refill?</p>
        <button onclick="onClick()">Ask for a refill</button>
      </div>
      <script>
        function onClick() {
          window.top.location.href = "http://localhost:8000/app/messaging"
        }
      </script>
    </body>
    </html>
    ```
##  Upcoming appointments Widget provided by Canvas 
This is one of the ready-made widgets provided by Canvas that you can add to your patient portal. It will show upcoming appointments.
###  Step 1: Add a new handler to your plugin 
Create a new handler in your plugin with the following content:
    ```python
    from canvas_sdk.effects.widgets import PortalWidget
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class UpcomingAppointmentWidget(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_PORTAL__WIDGET_CONFIGURATION)
        def compute(self):
            widget = PortalWidget(component=PortalWidget.Component.APPOINTMENTS, priority=25)
            return [widget.apply()]
    ```
![medication widget](/assets/images/sdk/widgets/upcoming_appointments_widget.png)

---

# Customize your panel buttons

Source: https://docs.canvasmedical.com/guides/customize-panel-buttons/

This guide is intended to help you customize which buttons are shown on the main page and the patient page. It allows you to add, order, or hide specific buttons as needed.
##  Getting Started 
To achieve this, you'll use the [PANEL_SECTIONS_CONFIGURATION](/sdk/events) event, which sends both the patient and the user attributes.
If you need to identify where the event is coming from, you can check if the patient attributes are present — on the global (main) page, the patient will be empty.
##  Defining the Sections 
In the SDK, you'll use the [PanelConfiguration](/sdk/layout-effect/#panel-configuration) effect. This effect takes in the sections you want to display and specifies the page where they should appear.
You'll use:
  - PanelPatientSection – for sections shown on the patient page
  - PanelGlobalSection – for sections shown on the main (global) page
The SDK has built-in safeguards to prevent you from mixing them up or placing a section on the wrong page.
That's It!
Once you apply the effect, your panel is configured — go check your page to see the changes in action!
##  The Complete Example 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.panel_configuration import PanelConfiguration
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class CustomizePatientSection(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PANEL_SECTIONS_CONFIGURATION)
        def compute(self) -> list[Effect]:
            patient = self.target
            # user = self.context["user"]
            if patient:
                return [PanelConfiguration(sections=[
                    PanelConfiguration.PanelPatientSection.REFILL_REQUEST,
                    PanelConfiguration.PanelPatientSection.LAB_REPORT,
                    PanelConfiguration.PanelPatientSection.CHANGE_REQUEST,
                    PanelConfiguration.PanelPatientSection.TASK,
                ], page=PanelConfiguration.Page.PATIENT if patient else PanelConfiguration.Page.GLOBAL).apply()]
            else:
                return []
    class CustomizeGlobalSection(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PANEL_SECTIONS_CONFIGURATION)
        def compute(self) -> list[Effect]:
            patient = self.target
            # user = self.context["user"]
            if not patient:
                return [PanelConfiguration(sections=[
                    PanelConfiguration.PanelGlobalSection.LAB_REPORT,
                    PanelConfiguration.PanelGlobalSection.TASK,
                    PanelConfiguration.PanelGlobalSection.CHANGE_REQUEST,
                ], page=PanelConfiguration.Page.PATIENT if patient else PanelConfiguration.Page.GLOBAL).apply()]
            else:
                return []
    ```

---

# Customize Search Results

Source: https://docs.canvasmedical.com/guides/customize-search-results/

In a typical visit note, it's common for clinicians to make 20, 30, even 50 or more selections from structured terminologies with commands like Diagnose, Prescribe, Family History, and many more. You can help clinicians make faster and more accurate selections with Canvas plugins. Write simple plugin code to apply custom filtering, sorting, and search result annotations in real time with near zero latency.
This search modification can help clinicians:
  - Choose the most appropriate medication that is also covered by insurance
  - Prioritize in-network specialists
  - Consider appropriate risk adjustment factors when selecting diagnosis codes
Canvas supports modifying search results in [all refactored commands](/product-updates/commands-module/#progress).
First, we'll show you a complete example of customizing the search results for choosing a medication in a Medication Statement command, then we'll break it down piece by piece so you can adapt the example to your own needs.
##  The Complete Example 
This example checks for the presence of a particular medication in the search results and, if present, annotates that medication option with additional information and adjusts its position to the top of the search results.
For reference, here's the difference in behavior with the plugin inactive vs active:
**Inactive (normal behavior):**
![With the plugin inactive, the results are unaltered](/assets/images/customize-search-results/plugin-inactive.png)
**Active (modified behavior):**
![With the plugin active, the preferred result is listed first, and with additional context](/assets/images/customize-search-results/plugin-active.png)
Here's the code in its entirety:
    ```python
    import json
    from canvas_sdk.events import EventType
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.handlers import BaseHandler
    class Handler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.MEDICATION_STATEMENT__MEDICATION__POST_SEARCH)
        def compute(self):
            results = self.context.get("results")
            if results is None:
                return [Effect(type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS, payload=json.dumps(None))]
            post_processed_results = []
            for result in results:
                should_float_to_top = False
                for coding in result.get("extra", {}).get("coding", []):
                    if (
                        coding.get("code") == 554704
                        and coding.get("system") == "http://www.fdbhealth.com/"
                    ):
                        if result.get("annotations") is None:
                            result["annotations"] = []
                        result["annotations"].append("Kirkland Signature")
                        should_float_to_top = True
                if should_float_to_top:
                    post_processed_results.insert(0, result)
                else:
                    post_processed_results.append(result)
            return [
                Effect(
                    type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS,
                    payload=json.dumps(post_processed_results),
                )
            ]
    ```
##  Anatomy of the Example 
This code can be broken down into the following sections:
  - Register interest in the correct search event
  - Decide whether to make any changes
  - Loop through the results, making modifications as appropriate
  - Return the modified results as a properly typed effect
###  Register interest in the correct search event 
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class Handler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.MEDICATION_STATEMENT__MEDICATION__POST_SEARCH)
        def compute(self):
            results = self.context.get("results")
    ```
The class inherits from `BaseHandler`, which clues the plugin-runner into registering your code as interested in the event or events listed in the `RESPONDS_TO` class constant. We only specify one event here, `MEDICATION_STATEMENT__MEDICATION__POST_SEARCH`, but you could make this value a list to fire on multiple events. The event we've chosen to listen for can be read backwards to understand when it fires. This event is emitted after (" _post_ ") the normal _search_ results are found for the _medication_ autocomplete field of the _medication statement_ command. This event comes with a context that contains the search results that would be served to the user if there were no modifications.
###  Decide whether to make any changes 
    ```python
            if results is None:
                return [Effect(type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS, payload=json.dumps(None))]
    ```
If the value of the results `is None`, we bail out early. There is a subtle difference between results of `None` and an empty result set (`[]`). Results being `None` means "make no changes, present the results without modification", whereas an empty result set means "present no options to the user".
###  Loop through the results, making modifications as appropriate 
    ```python
            post_processed_results = []
            for result in results:
                should_float_to_top = False
                for coding in result.get("extra", {}).get("coding", []):
                    if (
                        coding.get("code") == 554704
                        and coding.get("system") == "http://www.fdbhealth.com/"
                    ):
                        if result.get("annotations") is None:
                            result["annotations"] = []
                        result["annotations"].append("Kirkland Signature")
                        should_float_to_top = True
                if should_float_to_top:
                    post_processed_results.insert(0, result)
                else:
                    post_processed_results.append(result)
    ```
In this block of code, we create a new list named `post_processed_results` to hold our modified result set. We then loop through each result in the unmodified results set, and check to see if the current medication result matches our chosen criteria (FDB code 554704).
If it does match, we first check to see if any annotations already exist and initialize the annotations list if needed. We then append our chosen annotation to the result's annotation list and flag it as needing to be floated to the top (we had defaulted it to not be floated earlier on).
Finally, we add the result to our parallel list, `post_processed_results`. If it matched and was marked as being floated to the top, we insert it into the list at position 0. If it did not match, we append the result to the end of the list.
###  Return the modified results as a properly typed effect 
    ```python
            return [
                Effect(
                    type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS,
                    payload=json.dumps(post_processed_results),
                )
            ]
    ```
With our list of modified results in place, we just need to return an effect of type `AUTOCOMPLETE_SEARCH_RESULTS` with our modified list as the payload.
The dropdown of options presented to the user now reflects our modifications!
##  Understanding Search Result Data Structures 
The search results in this example follow the MedicationSearchResult structure. Each result contains fields like `text`, `disabled`, `description`, `annotations`, `extra`, and `value` that provide detailed information about the medication option.
For complete details about medication search result data contracts and other search result structures, see the [Search Result Data Structures](/sdk/events/#search-result-data-structures) section in the Events documentation.
##  Offering your own providers alongside the directory 
Five surfaces search for providers: Refer, Imaging Order, Order DME, fax recipient, and a patient's external care team. Each searches the shared contact directory by default. Providers you create with the [ServiceProvider effect](/sdk/effect-service-provider/) are not searched automatically, so if you maintain your own directory you have to offer them yourself.
The pattern is the same on all five surfaces: query your own [ServiceProvider](/sdk/data-serviceprovider/) records, put them ahead of the directory's results, and return the combined list.
**Use the POST_SEARCH event, not PRE_SEARCH.** Only the post-search context carries what the directory returned, in `context["results"]`. On a pre-search that list is empty, so there is nothing to merge with — and on a command pre-search any `AUTOCOMPLETE_SEARCH_RESULTS` effect you return is authoritative, which means an empty reply blanks the dropdown instead of leaving it alone.
Which helper you call depends on the surface:
Surface| Event| Helper  
---|---|---  
Refer| `REFER__REFER_TO__POST_SEARCH`| `as_search_result()`  
Imaging Order| `IMAGING_ORDER__IMAGING_CENTER__POST_SEARCH`| `as_search_result()`  
Order DME| `ORDER_DME__SEND_TO__POST_SEARCH`| `as_search_result()`  
Fax recipient| `FAX__RECIPIENT__POST_SEARCH`| `as_search_contact()`  
External care team| `PATIENT_PROFILE__EXTERNAL_CARE_TEAM__POST_SEARCH`| `as_search_contact()`  
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import ServiceProvider
    # Cap the query so a loose search term cannot pull your whole table into the sandbox.
    MAX_LOCAL_PROVIDERS = 200
    # The sandbox has no Q objects, so each field is queried separately and unioned in Python.
    SEARCHABLE_FIELDS = ("first_name", "last_name", "practice_name", "specialty")
    def matching_providers(search_term):
        matches = {}
        for field in SEARCHABLE_FIELDS:
            providers = ServiceProvider.objects.filter(
                is_active=True, **{f"{field}__icontains": search_term}
            )[:MAX_LOCAL_PROVIDERS]
            for provider in providers:
                matches.setdefault(provider.dbid, provider)
        return list(matches.values())[:MAX_LOCAL_PROVIDERS]
    class ContactDirectorySearch(BaseHandler):
        """Offer our own providers above the directory's on the fax and care team searches."""
        RESPONDS_TO = [
            EventType.Name(EventType.FAX__RECIPIENT__POST_SEARCH),
            EventType.Name(EventType.PATIENT_PROFILE__EXTERNAL_CARE_TEAM__POST_SEARCH),
        ]
        def compute(self):
            search_term = str(self.event.context.get("search_term") or "").strip()
            if not search_term:
                # An empty term must not push the entire local directory into the dropdown.
                return self.no_opinion()
            matches = matching_providers(search_term)
            if not matches:
                return self.no_opinion()
            ours = [
                provider.as_search_contact(["Our directory"])
                for provider in matches
            ]
            # Keep the directory's results underneath, minus anyone we already offered.
            superseded = {provider.full_name.lower() for provider in matches}
            theirs = [
                result
                for result in (self.event.context.get("results") or [])
                if f"{result.get('firstName') or ''} {result.get('lastName') or ''}".strip().lower()
                not in superseded
            ]
            return [
                Effect(
                    type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS,
                    payload=json.dumps(ours + theirs),
                )
            ]
        def no_opinion(self):
            """A null payload means "keep whatever the search already found"."""
            return [
                Effect(type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS, payload=json.dumps(None))
            ]
    ```
For Refer, Imaging Order, and Order DME, subscribe to those three events instead and swap `as_search_contact()` for `as_search_result()`. The merge is the same, except the directory's results carry their display name in `text` rather than in `firstName` / `lastName`.
A few things worth carrying over into your own version:
  - **Filter to`is_active=True`.** Deactivating a provider is how a customer retires it, so offering a deactivated one invites picking it again.
  - **Return a null payload when you have nothing to add** , rather than an empty list. On the contact surfaces an empty list clears the results.
  - **Prefer your own record when it duplicates a directory contact.** Selecting your record threads its `service_provider_id` through to the commit, so the existing row is reused instead of a near-duplicate being written. Match conservatively — listing a provider twice is a smaller failure than hiding one.
  - **Annotate what you add** so the user can tell your entries from the directory's.
##  Accessing User Context 
PRE_SEARCH and POST_SEARCH events include information about the user performing the search in the event context. This includes search events for command fields like prescriber, medication, diagnosis, pharmacy, and many others. It also includes the non-command fax recipient and external care team directory searches listed under [Other Events](/sdk/events/#other-events). All of these searches can be customized the same way.
You can access the user's staff id from the context:
    ```python
    def compute(self):
        user_context = self.context.get("user", {})
        staff_key = user_context.get("staff")
        # Use the staff id to customize search results
        # based on the user's role, preferences, or permissions
    ```
This can be useful for customizing search results based on:
  - User-specific preferences or settings
  - Role-based filtering (e.g., showing different prescriber options based on the user's specialty)
  - Permission-based access control
  - User's organization or practice location
##  Mapping Lay Terms to Medical Terms 
A common question is whether custom search results can map an over-general lay term to a proper medical term and coding — for example, surfacing _Essential hypertension (I10)_ when a clinician searches for "high blood pressure."
What these events give you is the ability to **modify the result set that Canvas returns for a search**. In a `POST_SEARCH` handler you receive the results Canvas found for the user's query in `self.context["results"]`, and you can reorder them, annotate them, filter them, or add to them before they are shown — exactly as the example above floats a preferred medication to the top. So if a search for a lay term already returns the medical concept you want among its results, you can promote and annotate that result so the clinician sees it first.
The search events are not a free-text translation layer, however: the events carry the structured search results rather than an arbitrary mapping from any phrase to any coding. If you need to act on the exact text the user typed (to recognize specific lay phrases), inspect the search context the event provides rather than relying on the rendered UI. Because terminology mapping touches clinical coding accuracy, validate any term-to-code associations with your clinical team before deploying.
##  Watch Me Build It 

---

# Customizing Commands Beyond the Built-ins

Source: https://docs.canvasmedical.com/guides/customizing-commands/

The built-in [commands](/sdk/commands/) cover most charting. When a workflow needs more, you can add fields to a built-in command, show your own content on it, add commands of your own, or write commands from outside Canvas.
##  Adding fields to a built-in command 
To collect extra information on a built-in command, such as a few more fields on a Plan, add them with the [command metadata form](/sdk/command-metadata-create-form-effect/). The fields appear with the command in the note, and their values are saved as [command metadata](/sdk/data-command/#commandmetadata).
##  Showing your own content on a built-in command 
To display extra information with a built-in command, such as a summary or a reference link, attach HTML to it with [`set_custom_html`](/sdk/commands/#set_custom_html). The HTML renders alongside the command in the note. The command must still be staged, not committed.
##  Adding your own command 
To add your own named command, such as a "Wound assessment" command, there are two routes.
**A[custom command](/sdk/commands-custom-command/).** You declare it in your plugin's manifest, and it shows HTML you supply in the note. The command itself is read-only, so the work is in deciding what goes into it and when your plugin inserts it:
  - **From data your plugin already has:** build the HTML from the chart or your own records and originate the command, for example from an event handler.
  - **From a form you build:** gather the data in any interface your plugin shows, then originate the command when the information is ready to submit officially.
    - [Action buttons](/sdk/handlers-action-buttons/) open your form in a [modal](/sdk/layout-effect/#modals) from the note header or footer, or the chart. Good for a short form the clinician fills in once.
    - [Note applications](/sdk/handlers-embedded-applications/#note-applications) add a tab next to the note body. Good for a longer form the clinician works through during the visit.
    - Other [applications](/sdk/handlers-applications/#application-scopes), in the patient chart, the app drawer, or the [patient portal](/sdk/patient-portal/), gather data outside the note, including answers from the patient.
The form sends its data to a [SimpleAPI](/sdk/handlers-simple-api-http/) endpoint in your plugin, which can save it as it comes in, for example in [custom data](/sdk/custom-data/), so the user can come back to an unfinished form. The custom command you originate at the end is the record in the note.
See the [CustomCommand reference](/sdk/commands-custom-command/) for manifest setup, print content, and examples.
**A questionnaire-based command.** Build a questionnaire and use it with the [Questionnaire](/sdk/effect-questionnaires/), Review of Systems, Physical Exam, or Structured Assessment command. Canvas provides the form, so clinicians answer it directly in the note.
##  Writing commands from outside Canvas 
When another system needs to write commands to a chart, such as an intake form, a device, or an internal tool, use [`CommandAPI`](/sdk/handlers-simple-api-commands/). It turns a command into an HTTP endpoint in your plugin: it reads the request body onto the command, validates it, and writes the command to the note. [Writing Commands Over HTTP](/guides/writing-commands-over-http/) walks through building one, including checking that the caller may write to the note.

---

# Embedding a SMART app into Canvas

Source: https://docs.canvasmedical.com/guides/embedding-a-smart-on-fhir-application/

Canvas' FHIR API supports the SMART launch sequence, and the Canvas SDK allows you to embed html content within the Canvas EMR. The combination of these capabilities is a frictionless experience when embedding a SMART app into Canvas. This example will show you how to register a SMART app's credentials and create an application to launch it from within a patient's chart.
##  In this guide you will learn how to: 
  - Configure credentials for a public OAuth application.
  - Create an application to initiate the SMART launch sequence.
  - Use application launch context to help form the SMART launch URL parameters.
##  What is a SMART app? 
SMART on FHIR applications adhere to a standards-based approach to authentication, authorization, and data access with the goal of being portable across EMR installations and vendors. Because SMART apps limit themselves to standards based data, the logic can be agnostic to the EMR it is running against. Vendor to vendor, site to site, FHIR is FHIR, that's how it works, right?
##  Where can I get a SMART app? 
We've provided an example SMART app [here](https://github.com/canvas-medical/example-smart-on-fhir-app). You can fork it and customize, or just use ours as-is. We use GitHub pages to host it at `https://canvas-medical.github.io/example-smart-on-fhir-app/`. Please ensure the client id [listed in `launch.html`](https://github.com/canvas-medical/example-smart-on-fhir-app/blob/205b14ed8d4f4d9c57fd11a26f9a22c800f38c29/launch.html#L15) matches the client id for the credentials you configure in the next step.
##  Configuring credentials 
The first step to embedding a SMART application is to configure OAuth credentials for it to use. Navigate to `<YOUR_CANVAS_URL>/auth/applications/register/` and choose `Public` client type, `Authorization code` grant type, the `RSA` algorithm, and set the redirect uri for your SMART application. Registering an application takes the Administrative Developer or Clinical Developer role, or a group with the **Can register and manage OAuth applications** permission; see [Registering a third-party application on Canvas](/api/customer-authentication/#registering-a-third-party-application-on-canvas).
![OAuth Configuration](/assets/images/guides/embedding-a-smart-app/SMART_OAuth.png)
##  Creating an application 
We encourage you to read our more comprehensive guide on [creating applications via the Canvas SDK](/guides/your-first-application/), but we can provide an abridged version here.
Using the [Canvas CLI](/sdk/canvas_cli/), create an application from a template using `canvas init application`. After providing a name, the Canvas CLI will create a directory with your application inside it. If you're signed in to Canvas Platform with [`canvas login`](/sdk/canvas_cli/#signing-in-to-canvas-platform), the directory is named with your organization's prefix, such as `acme__my_smart_app`. The application is also registered with Canvas Platform.
    ```bash
    dev@canvas:plugins$ canvas init application
      [1/1] project_name (My Cool Application): My Smart App
    Project created in /Users/dev/src/plugins/acme__my_smart_app
    Registered acme__my_smart_app with Canvas Platform.
    dev@canvas:plugins$ tree acme__my_smart_app/
    acme__my_smart_app/
    ├── CANVAS_MANIFEST.json
    ├── README.md
    ├── applications
    │   ├── __init__.py
    │   └── my_application.py
    └── assets
        └── python-logo.png
    3 directories, 5 files
    ```
There are two files we'll want to visit for changes: `CANVAS_MANIFEST.json` and `applications/my_application.py`.
###  Configuring the manifest file 
In order to set the same-origin policy for the iframe our SMART app will be embedded into, we need to make sure the url where the SMART app is hosted is listed in the `url_permissions` section of the manifest, and the `ALLOW_SAME_ORIGIN` permission is requested.
    ```json
        "url_permissions": [
            {
                "url": "https://canvas-medical.github.io",
                "permissions": ["ALLOW_SAME_ORIGIN"]
            }
        ],
    ```
We also want to change the application scope from the default "global" setting to "patient specific":
    ```json
        "components": {
            "applications": [
                {
                    ...
                    "scope": "patient_specific",
                }
            ],
        },
    ```
###  Setting the SMART launch URL 
The SMART authorization dance begins with the SMART app's launch URL. The parameters present on this URL set the wheels in motion. The launch URL is loaded in an iframe, and javascript immediately reads the `iss` param in order to probe the FHIR API's CapabilityStatement for the EMR's Authorize endpoint, which the iframe is then redirected to, with its own load of URL parameters in tow.
We can set this initial URL and launch params in the `on_open` method found in `applications/my_application.py`. This is the code that is invoked when a user clicks the application's launch icon.
    ```python
    import json
    from base64 import b64encode
    from urllib.parse import urlencode
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class MyApplication(Application):
        def on_open(self) -> Effect:
            launch_context = {
                "patient": self.context["patient"]["id"]
            }
            encoded_launch_context = b64encode(json.dumps(launch_context).encode()).decode()
            launch_params = {
                "iss": f"https://fumage-{self.environment['CUSTOMER_IDENTIFIER']}.canvasmedical.com",
                "launch": encoded_launch_context
            }
            encoded_launch_params = urlencode(launch_params)
            return LaunchModalEffect(
                url=f"https://canvas-medical.github.io/example-smart-on-fhir-app/launch.html?{encoded_launch_params}",
                target=LaunchModalEffect.TargetType.RIGHT_CHART_PANE,
            ).apply()
    ```
That's all the plugin work we need to do in order to create a launcher for the SMART application. Deploy the plugin to your Canvas instance with [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy), navigate to a patient's chart, and choose your application from the launcher.
    ```console
    $ canvas deploy acme__my_smart_app --instance <instance>
    ```
Canvas Platform hosts a git repository for each plugin, rooted at the folder that contains `acme__my_smart_app`. The first deploy offers to create that repository, so if the folder holds other projects, move the application into a folder of its own first.
##  Executing the launch sequence 
Upon launching your application, the SMART app will need the user to sign off on the access token it will receive to access the FHIR API on behalf of the logged in user.
![Authorize the token](/assets/images/guides/embedding-a-smart-app/SMART_Authorize.png)
The page you're seeing in the image is served by Canvas. This page is asking for the logged in user's consent to sending the SMART app a token which can access the FHIR API on the user's behalf. Clicking `Authorize` will redirect the iframe to the URL specified in the OAuth client's configuration with several params, most critically the API access token.
With the SMART app now in possession of a valid API access token, the application can function with access to all the data it is authorized to retrieve from the FHIR API. The example SMART app we've been working with simply shows the raw FHIR records retrieved for the patient.
![SMART app in action](/assets/images/guides/embedding-a-smart-app/SMART_App.png)
If you want to update the example SMART app to authorize additional data access from the FHIR API, you'll need to add those endpoints to the `scope` values in [launch.html](https://github.com/canvas-medical/example-smart-on-fhir-app/blob/main/launch.html), or wherever your authorize method is called:
    ```html
        <script>
            FHIR.oauth2.authorize({
                ...
                // The scopes that you request from the EHR. In this case we want to:
                scope: "patient/Patient.read patient/MedicationStatement.read patient/Goal.read patient/DocumentReference.read launch offline_access openid fhirUser",
                ...
            });
        </script>
    ```
For a more comprehensive list of available FHIR scopes, visit the [API docs](https://docs.canvasmedical.com/api/).
##  A more flexible alternative 
If you're looking to provide your users a more native experience without requiring the intricate authorization dance SMART prescribes, you're already pretty close just by going through the exercise above! While we created an embedded iframe of remote-hosted content, the Canvas SDK also allows you to [define HTTP endpoints](/sdk/handlers-simple-api-http/) which can also be the targets of the iframes. This allows your plugins to host [dynamically rendered HTML](/sdk/layout-effect/#custom-html-and-django-templates), CSS, Javascript, and more, with no external hosting required! You can take advantage of the built-in [session authentication](/sdk/handlers-simple-api-http/#session) for access control (no separate logins or authorizations for your users), and you have direct access to the EMR database through the Canvas SDK's [data module](/sdk/data/). [Caching](/sdk/caching/) and [websockets](/sdk/handlers-simple-api-websocket/) help you provide modern experiences, while the [effects module](/sdk/effects/) ensures you can write new data back into Canvas as needed.
The Canvas SDK allows you to deploy full web applications within the EMR, colocating your code with the data it needs to function, and without requiring any additional infrastructure. Want to explore further? Join us in our [developer community](https://github.com/canvas-medical/canvas-plugins/discussions) and say hello!

---

# Visualizing Data Within the Canvas Chart

Source: https://docs.canvasmedical.com/guides/growth-charts/

The Canvas SDK gives you access to real-time patient data and allows you to create custom UIs accessible from a patient's chart. The combination of these capabilities allows you to create rich, interactive data visualizations your clinicians can access directly in the charting interface. This example will show you how we've used this approach to implement a pediatric growth charts feature.
##  In this guide you will learn how to: 
  - Use the [`ActionButton`](/sdk/handlers-action-buttons) handler to provide a button, specify its location, and define its action in the UI.
  - Use the [`LaunchModalEffect`](/sdk/layout-effect/#modals) to display your custom visualization.
  - Fetch patient [observations](/sdk/data-observation/), such as height and weight, from the [data module](/sdk/data/).
  - Use the patient observation data within an HTML template.
  - Combine all of the above to surface a pediatric growth chart visualization right in the chart.
##  Growth Charts 
Growth charts are percentile curves showing the distribution of selected body measurements in children. A growth chart shows how a child's height, weight, and head circumference (for infants) compare to other children of the same age and sex. It helps track a child's growth over time and can indicate whether they are growing at an expected rate. Growth charts are commonly used by doctors to monitor development and identify potential health concerns. In this guide we will use charts from the [Center for Disease Control and Prevention (CDC)](https://www.cdc.gov/growthcharts/who-data-files.htm) to demonstrate how you can create your own.
The complete plugin is open-source and can be found in the [Medical Software Foundation GitHub repo](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/growth_charts/).
The plugin adds a button on the Vital Signs section of the patient chart that, when clicked, launches a modal displaying the patient's height, weight, and head circumference measurements graphed against various percentile curves.
![vitals action button](/assets/images/vitals-action-button.png)
![chart template](/assets/images/growth-charts.png)
In the following steps, we'll show you how we used the Canvas SDK to create it.
##  Adding a button 
To add a button to the vital signs section, you'll implement an [`ActionButton`](/sdk/handlers-action-buttons) handler. In your handler class, you'll set the `BUTTON_LOCATION` constant to `ActionButton.ButtonLocation.CHART_SUMMARY_VITALS_SECTION` to make the action button appear in the corresponding summary section of the chart.
    ```python
    from canvas_sdk.handlers.action_button import ActionButton
    from canvas_sdk.effects import Effect
    class GenerateVitalsGraphs(ActionButton):
        BUTTON_TITLE = "Growth Charts"
        BUTTON_KEY = "show_growth_charts"
        BUTTON_LOCATION = ActionButton.ButtonLocation.CHART_SUMMARY_VITALS_SECTION
        def handle(self) -> list[Effect]:
            # This method is invoked when the button is clicked.
            pass
    ```
##  Launching a modal when the button is clicked 
Now that you have your button showing in the chart section, you can launch a modal when it's clicked using the [`LaunchModalEffect`](/sdk/layout-effect/#modals)
In this guide, we are launching a modal, but this click action can result in any [effect](/sdk/effects/) your handling code returns.
Here's an example of a simple plugin using the `LaunchModalEffect` to display a "Hello World" message.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.action_button import ActionButton
    from canvas_sdk.templates import render_to_string
    class HelloWorld(ActionButton):
        BUTTON_TITLE = "Hello World"
        BUTTON_KEY = "show_hello_world"
        BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_HEADER
        def handle(self) -> list[Effect]:
            launch_modal = LaunchModalEffect(content=render_to_string("templates/hello-world.html", { "title": "hello world" }))
            return [launch_modal.apply()]
    ```
And here's the result!
![action button](/assets/images/action-button-hello-world.png)
![hello world](/assets/images/template-hello-world.png)
##  Using HTML templates in the modal 
The use of templates allows us to render any kind of information from the data we have. We can even import external libraries from CDNs and add CSS styles to customize and enhance our modal.
To draw our graphs we use d3js, a free, open-source JavaScript library for visualizing data. How to use d3js is outside the scope of this guide, but you can find great documentation and tutorials on the d3 website [here](https://d3js.org/getting-started)
Here's an example of a template file name `hello-world.html` that receives a variable called title, which will be used inside the template.
    ```html
    <!DOCTYPE html>
    <style>
        body {
            font-family: Arial, sans-serif;
            font-size: 30px;
        }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
    <html lang="en">
        <h1 id="main"></h1>
    </html>
    <script>
        const div = document.getElementById('main');
        div.textContent = ``;
    </script>
    ```
##  Fetching the observations 
To retrieve the patient data we use the [Data Module](/sdk/data/). Specifically, the [`Observation`](/sdk/data-observation/) model.
Here, we can use `self.target`, which is the patient's `id`, to retrieve the patient and their observations by filtering for the values we need — such as weight, height, etc.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.v1.data.observation import Observation
    from canvas_sdk.v1.data.patient import Patient
    def handle(self) -> list[Effect]:
        patient = Patient.objects.get(id=self.target)
        sex_at_birth = patient.sex_at_birth
        birth_date = patient.birth_date
        observation_weight = Observation.objects.for_patient(self.target).filter(name="weight")
        observation_length = Observation.objects.for_patient(self.target).filter(name="length")
        observation_bmi = Observation.objects.for_patient(self.target).filter(name="bmi")
        observation_head_circumference = Observation.objects.for_patient(self.target).filter(name="head_circumference")
    ```
##  Tying it all together 
We now know:
  1. How to put a button in the chart
  2. How to launch a modal when that button is clicked
  3. How to create an HTML template to render within that modal
  4. How to retrieve data to use within that HTML template
All that's left is combining these actions into a useful data visualization for our clinical users.
You can see our HTML template [here](https://github.com/Medical-Software-Foundation/canvas/blob/main/extensions/growth_charts/templates/chart.html), which draws many charts based on the observations provided and the percentile curve data provided by the CDC. To make that percentile data usable in our template, we transformed the Excel files from the CDC website into structured data we could use programatically. You can find those python representations of the percentile data [here](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/growth_charts/graphs).
Here's an excerpt:
    ```python
    who_boys_length_age = [
        { "x": 0, "y": 46.77032, "z": "5th" },
        { "x": 1, "y": 51.52262, "z": "5th" },
        { "x": 2, "y": 55.13442, "z": "5th" },
        ...,
        { "x": 23, "y": 92.93123, "z": "98th" },
        { "x": 24, "y": 93.92634, "z": "98th" }
    ]
    ```
In addition to the percentile data series, we of course need to plot the patient observation data series. To do this, we create a lists of x and y values corresponding to the patient's age and measurements. You can see this in more detail in the [GitHub repo](https://github.com/Medical-Software-Foundation/canvas/blob/5e8a3dfdb18307e596d2da2d9fce33a3e379cd11/extensions/growth_charts/protocols/growth_charts.py#L80), but here's an excerpt:
    ```python
    import arrow
    import datetime
    from canvas_sdk.effects import Effect
    from canvas_sdk.v1.data.note import Note
    from canvas_sdk.v1.data.observation import Observation
    from canvas_sdk.v1.data.patient import Patient
    def convert_oz_to_kg(oz: str) -> float:
        return float(oz) * 0.0283495
    def get_age_in_months(birth_date: datetime.date, date: datetime.date = datetime.datetime.now()) -> int:
        now = arrow.get(date)
        date = arrow.get(birth_date)
        year_difference = now.year - date.year
        month_difference = now.month - date.month
        return year_difference * 12 + month_difference
    def handle(self) -> list[Effect]:
        graphs = []
        patient = Patient.objects.get(id=self.target)
        sex_at_birth = patient.sex_at_birth
        birth_date = patient.birth_date
        age_in_months = get_age_in_months(birth_date)
        is_less_than_24_months_old = age_in_months < 24
        is_less_than_36_months_old = age_in_months < 36
        observation_weight = Observation.objects.for_patient(self.target).filter(name="weight")
        observation_height = Observation.objects.for_patient(self.target).filter(name="height")
        observation_length = Observation.objects.for_patient(self.target).filter(name="length")
        observation_bmi = Observation.objects.for_patient(self.target).filter(name="bmi")
        observation_head_circumference = Observation.objects.for_patient(self.target).filter(name="head_circumference")
        weight_for_age = {}
        length_for_age = {}
        weight_for_length = {}
        head_for_age = {}
        bmi_for_age = {}
        for obs in observation_weight:
            if obs.value:
                note = Note.objects.get(dbid=obs.note_id)
                age_in_months = get_age_in_months(birth_date, note.datetime_of_service)
                weight_in_kg = convert_oz_to_kg(obs.value)
                weight_for_age[age_in_months] = weight_in_kg
        # ... repeat for other data series
    ```
Finally, we create a list of graphs with the necessary variables and data, which are passed to the template to generate and render the graph.
    ```python
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.templates import render_to_string
    who_boys_length_age = ... # from growth_charts.graphs.who_boys_length_age
    class Handler(BaseHandler):
        def compute(self):
            # list of graphs
            length_for_age = {} # filled in the actual implementation, see linked GitHub repository
            graphs = [
                {
                    "data": who_boys_length_age, # the data from the graph file
                    "title": 'Length for age (Boys 0 - 2 years)', # graph title
                    "xType": 'Generic', # the type of x axis (Generic, Length, Weight) - We need this info to convert the values
                    "yType": 'Length', # the type of y axis (Generic, Length, Weight)
                    "xLabel": 'Age', # label for the x axis
                    "yLabel": 'Length', # label for the y axis
                    "zLabel": 'Percentile', # label for the z axis
                    "layerData": length_for_age, # the patient's data that will be plotted on the graph
                    "tab": "WHO" # the section where the graph should be rendered (WHO or CDC)
                },
                # ...repeat for other data series
            ]
            launch_modal = LaunchModalEffect(
                content=render_to_string("templates/chart.html", {"graphs": graphs}),
            )
            return [launch_modal.apply()]
    ```
![chart template](/assets/images/growth-charts.png)
By combining action buttons, the data module, and the `LaunchModalEffect`, you can create unique visualizations to help contextualize patient data for your clinical users.

---

# Improve HCC Coding Accuracy

Source: https://docs.canvasmedical.com/guides/improve-hcc-coding-accuracy/

Different patients present unique challenges, and your tools should adapt to meet their specific needs.
Hierarchical condition category (HCC) coding is a critical component of value-based care, especially for organizations serving Medicare Advantage patients. Accurate risk adjustment ensures patients receive appropriate coverage while aligning reimbursement with the complexity of their care needs. However, navigating HCC coding can feel overwhelming with so many diagnoses to consider, guidelines to follow, and tools to use.
This guide will walk you through practical steps to use HCC codings in Canvas for more efficient and effective care delivery. You'll learn how to leverage our [HCC capture plugin](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/hcc_capture) to do the following:
  - Create coding gaps from external data using the FHIR DetectedIssue endpoint
  - Surface coding gaps as actionable protocol cards
  - Address and resolve codings gaps seamlessly within the clinical workflow through streamlined commands.
  - Annotate ICD-10 codes that are mapped to HCC categories
By surfacing relevant data when and where it's needed, you can eliminate unnecessary steps, reduce cognitive load, and keep workflows aligned with patient needs.
##  Create Coding Gaps via FHIR Detected Issue 
The [DetectedIssue FHIR resource](/api/detectedissue)) can be used to surface an actual or potential clinical issue with or between one or more active or proposed clinical actions for a patient; e.g. Drug-drug interaction, ineffective treatment frequency, procedure-condition conflict, gaps in care, etc.
A key use case is surfacing potential codings gaps that come from external sources.
The workflow within Canvas is centered around issues created with the `DetectedIssue.code` set to `CODINGGAP`. Although we are leveraging it in our R4 endpoint, `CODINGGAP` was introduced to the value set in R5, and can be used for surfacing conditions that may be present on historical claims but not yet diagnosed within the current year, suspect conditions, or condition data from external sources. The code should be structured as follows:
    ```json
        "code": {
            "coding": [
                {
                    "system": "https://terminology.hl7.org/CodeSystem/v3-ActCode",
                    "code": "CODINGGAP"
                }
            ]
        },
    ```
The ICD-10 code can be added to `DetectedIssue.evidence` attribute.
Validated coding gaps (where `DetectedIssue.status` = `preliminary`) will appear in the patient summary if the coding gap commands are enabled in your environment (see more below).
##  Surface New Coding Gaps as Protocol Cards 
Clinical Documentation Improvement (CDI) staff often play a crucial role in reviewing potential coding gaps, especially those added via the API using external data.
There is no built in UI feature in Canvas that surfaces coding gaps that have yet to be reviewed for accuracy by staff members. Instead, We haven chosen to leverage plugins to allow for customization within your workflow for surfacing gaps in care. The example protocol below creates a [protocol card](/sdk/effect-protocol-cards/) when a new DetectedIssue is created for a coding gap with a `registered` status. It then recommends that a staff member validates the information before presenting it to a clinician in the summary.
The protocol will surface in each patient's chart and staff can also leverage the population page as a work list.
    ```python
    from canvas_sdk.protocols.clinical_quality_measure import ClinicalQualityMeasure
    from canvas_sdk.events import EventType
    from canvas_sdk.effects.protocol_card import ProtocolCard
    from canvas_sdk.v1.data.detected_issue import DetectedIssue
    class SurfaceNonvalidatedCodingGaps(ClinicalQualityMeasure):
        class Meta:
            title = "Validate Coding Gaps"
            identifiers = ["HCCCapturev1"]
            description = "Surfaces registered coding gaps within a protocol card with the recommendation to validate"
            information = "https://canvasmedical.com"
            references = ["Canvas Medical. https://docs.canvasmedical.com/guides/improve-hcc-coding-accuracy/"]
            authors = ["Canvas Medical"]
        RESPONDS_TO = [
            EventType.Name(EventType.DETECTED_ISSUE_CREATED),
            EventType.Name(EventType.DETECTED_ISSUE_UPDATED),
        ]
        def surface_non_validated_coding_gaps(self, patient, nonvalidated_coding_gaps):
            """
            Craft a protocol card with the list of coding gaps and return an add protocol card effect
            """
            card = ProtocolCard(
                patient_id=patient.id,
                key="hcccapturev1",
                title="Coding Gaps",
                narrative="These codings gaps have not been validated.",
                status=ProtocolCard.Status.DUE,
                feedback_enabled=False,
            )
            for coding_gap in nonvalidated_coding_gaps:
                coding_gap_title_strings = []
                for evidence in coding_gap.evidence.all():
                    coding_gap_title_strings.append(f"{evidence.display} ({evidence.code})")
                card.add_recommendation(
                    title="\n".join(coding_gap_title_strings),
                    button="Validate",
                    command="validateCodingGap",
                    context={"detected_issue_id": coding_gap.dbid},
                )
            return [card.apply()]
        def resolve_coding_gaps_protocol_card(self, patient):
            """
            Craft and return a remove protocol card effect
            """
            card = ProtocolCard(
                patient_id=patient.id,
                key="hcccapturev1",
                title="Coding Gaps",
                narrative="There are no non-validated coding gaps for this patient.",
                status=ProtocolCard.Status.SATISFIED,
                feedback_enabled=False,
            )
            return [card.apply()]
        def compute(self) -> list:
            """
            When a new detectedissue is created or updated, reevaluate (create/update/remove) a protocol card based on the associated evidence
            """
            detected_issue_from_the_event = DetectedIssue.objects.get(id=self.target)
            if detected_issue_from_the_event.code != "CODINGGAP":
                # This detected issue has no impact on the protocol card, so we
                # don't need to do any work.
                return []
            patient = detected_issue_from_the_event.patient
            all_of_that_patients_non_validated_detected_issues = patient.detected_issues.filter(status="registered", code="CODINGGAP")
            if all_of_that_patients_non_validated_detected_issues.count() > 0:
                return self.surface_non_validated_coding_gaps(patient, all_of_that_patients_non_validated_detected_issues)
            else:
                return self.resolve_coding_gaps_protocol_card(patient)
    ```
##  Use Coding Gap Commands to Update the Patient's Record 
The API can be leveraged to create coding gaps in various states. There are also 4 commands for clinicians and staff to manage coding gaps.
  - **Create Coding Gap** serves as a manual way to add coding gaps to the chart. Staff have the ability to create and validate in the same step.
  - **Validate Coding Gap** allows the care team (often CDI Reviewers) to review the external date and confirm that the gap should be surfaced to a clinician.
  - **Assess Coding Gap** allows clinicians to accept or refute the diagnose and choose the appropriate diagnosis to add to the visit.
  - **Defer Coding Gap** allows clinicians to acknowledge the gap and snooze it for a period of time so that they can return to it at a later date. This may be necessary if the patient is unable to provide enough detail or they run out of time during a visit. When recapture rate is an important metric, this allow reporting to reflect an action was taken.
##  Annotate ICD-10 Codes 
Adding an HCC tag as an annotation to ICD-10 is an easy way to increase awareness for clinicians. The example handlers below leverage a static list of ICD-codes. You could also reference a file contained within the plugin pacakge. Depending on which [HCC model](https://www.cms.gov/medicare/payment/medicare-advantage-rates-statistics/risk-adjustment) you follow, you can swap out the codes accordingly.
###  Adding "HCC" to Command Search Results 
The following handler leverages [command `POST_SEARCH` lifecycle events](/sdk/events/#command-lifecycle-events) and adds an `HCC` annotation to the associated ICD-10 codes within the results for the diagnose, past medical history, create coding gap, and assess coding gap commands.
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    ICD_CODES = {
        "HCC": {"A0103", "A0104", "A0105", "A021", "A0222", "A0223", "A0224", "A065", "A072", "A202", "ADD_MORE_CODES..."}
    }
    class AnnotateSearchResults(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.DIAGNOSE__DIAGNOSE__POST_SEARCH),
            EventType.Name(EventType.MEDICAL_HISTORY__PAST_MEDICAL_HISTORY__POST_SEARCH),
            EventType.Name(EventType.CREATE_CODING_GAP__DIAGNOSE__POST_SEARCH),
            EventType.Name(EventType.ASSESS_CODING_GAP__DIAGNOSE__POST_SEARCH),
        ]
        def compute(self):
            """
            Add HCC code annotation if the HCC code is found in the search results.
            """
            results = self.context.get("results")
            if results is None:
                return [Effect(type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS, payload=json.dumps(None))]
            post_processed_results = []
            for result in self.context["results"]:
                for coding in result.get("extra", {}).get("coding", []):
                    if not coding.get("system") in ("http://hl7.org/fhir/sid/icd-10", "ICD-10"):
                        continue
                    if coding.get("code") in ICD_CODES["HCC"]:
                        if result.get("annotations") is None:
                            result["annotations"] = []
                        result["annotations"].append("HCC")
                        break
                post_processed_results.append(result)
            return [
                Effect(
                    type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS,
                    payload=json.dumps(post_processed_results),
                )
            ]
    ```
###  Adding Annotations to Conditions and Detected Issues 
The following event/effect pairings can be leveraged to add annotations (such as the `HCC` tag) to conditions and detected issues in the patient summary as well as on claims using the handler code below.
  - `CLAIM__CONDITIONS` and `ANNOTATE_CLAIM_CONDITION_RESULTS`
  - `PATIENT_CHART__CONDITIONS` and `ANNOTATE_PATIENT_CHART_CONDITION_RESULTS`
  - `PATIENT_CHART__DETECTED_ISSUES` and `ANNOTATE_PATIENT_CHART_DETECTED_ISSUE_RESULTS`
    ```python
    import json
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    ICD_CODES = {
        "HCC": {
            "A0103", "A0104", "A0105", "A021", "A0222", "A0223", "A0224", "A065", "A072", "A202", "ADD_MORE_CODES...",
        }
    }
    HCC = "HCC"
    class PatientChartConditionAnnotation(BaseHandler):
        """
        Annotate Conditions in the Patient Chart with an HCC tag
        """
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART__CONDITIONS)
        def compute(self):
            """
            Annotate patient summary conditions if they match the provided set of HCC codes
            """
            hcc_codes = ICD_CODES[HCC]
            payload = {}
            for condition in self.context:
                icd10_code = next((coding.get("code") for coding in condition.get("codings", []) if coding.get("system") == "ICD10"), None)
                if not icd10_code:
                    continue
                if icd10_code in hcc_codes:
                    payload[condition["id"]] = [HCC]
            return [Effect(type=EffectType.ANNOTATE_PATIENT_CHART_CONDITION_RESULTS, payload=json.dumps(payload))]
    class ClaimConditionAnnotation(BaseHandler):
        """
        Annotate Conditions in the Claim modal with an HCC tag
        """
        RESPONDS_TO = [EventType.Name(EventType.CLAIM__CONDITIONS)]
        def compute(self):
            """
            Annotate claim conditions if they match the provided set of HCC codes
            """
            hcc_codes = ICD_CODES[HCC]
            payload = {}
            for condition in self.context:
                icd10_code = next((coding.get("code") for coding in condition.get("codings", []) if coding.get("system") == "ICD10"), None)
                if not icd10_code:
                    continue
                if icd10_code in hcc_codes:
                    payload[condition["id"]] = [HCC]
            return [Effect(type=EffectType.ANNOTATE_CLAIM_CONDITION_RESULTS, payload=json.dumps(payload))]
    class DetectedIssueAnnotation(BaseHandler):
        """
        Annotate Detected Issues in the Patient Chart with ICD-10 codes from evidence
        """
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART__DETECTED_ISSUES)
        def compute(self):
            """
            Annotate patient summary detected issues with their ICD-10 code from evidence
            """
            payload = {}
            for detected_issue in self.context:
                # Get the first ICD-10 code from evidence if available
                evidence_code = None
                if detected_issue.get("evidence"):
                    for evidence in detected_issue["evidence"]:
                        if evidence.get("code"):
                            evidence_code = evidence["code"]
                            break
                if evidence_code:
                    payload[detected_issue["id"]] = [evidence_code]
            return [Effect(type=EffectType.ANNOTATE_PATIENT_CHART_DETECTED_ISSUE_RESULTS, payload=json.dumps(payload))]
    ```
##  Watch the Workflow in Action 
##  Conclusion 
By leveraging intuitive tools and streamlined workflows, you can simplify HCC coding and focus on delivering patient-centered care. This approach ensures accuracy, efficiency, and confidence in addressing risk adjustment challenges.

---

# Moving to Canvas Platform

Source: https://docs.canvasmedical.com/guides/moving-to-canvas-platform/

The Canvas CLI signs in to [Canvas Platform](https://platform.canvasmedical.com) with `canvas login` and ships plugins with `canvas deploy`. Canvas Platform hosts each plugin's git repository, deploys a pushed commit to the instances your organization manages, and stores each instance's plugin variables.
> **Warning:** **Support for`credentials.ini` and `canvas install` ends on December 14, 2026.** After that date the Canvas CLI authenticates only through Canvas Platform, and plugins reach an instance only through `canvas deploy`. Move each plugin over before then using the steps below.
##  What changes 
Task| Deprecated| Current  
---|---|---  
Sign in| An OAuth client per instance, saved in `~/.canvas/credentials.ini`| `canvas login` once per machine, in your browser  
Sign in from CI| An instance's `client_id` and `client_secret` as CI secrets| A service account token as `CANVAS_PLATFORM_TOKEN`  
Ship code| `canvas install <dir> --host <instance>` uploads a package| `canvas deploy <package dir> --instance <instance>` pushes a git commit and deploys it  
Plugin name| Any name| `<org prefix>__<package>`, such as `acme__intake`  
Set variables| `canvas install --secret` / `--variable`, or `canvas config set --host`| `canvas config set <name> KEY=VALUE --instance <instance>`  
Uninstall| `canvas uninstall <name> --host <instance>`| `canvas uninstall <name> --instance <instance>`  
Code history| Whatever was last uploaded| Every pushed commit, in the plugin's repository on Canvas Platform  
`canvas install` prints a deprecation warning on every run, and at most once a day any command, `canvas install` included, reminds you about the change.
##  Before you start 
  - Upgrade the Canvas CLI: `pip install --upgrade canvas`, or `uv tool upgrade canvas`.
  - Install git. Canvas Platform hosts each plugin as a git repository.
  - Get the roles you need in your Canvas Platform organization. Pushing plugin code needs the **Plugin developer** role; deploying, configuring and uninstalling need **Deploy manager**. An **Organization admin** grants them.
##  Move a plugin 
The steps below move a plugin named `intake` to the organization whose prefix is `acme`, on the instance `acme-staging`.
###  1\. Sign in 
    ```console
    $ canvas login
    Signed in to https://platform.canvasmedical.com as you@example.com.
      Acme Health (acme): plugin prefix acme__
    ```
`canvas login` lists each organization you belong to and its plugin prefix. The prefix you choose for a plugin decides which organization publishes it. Later, `canvas whoami` shows the same list, along with the platform the CLI is using and what you can do in each organization.
###  2\. Rename the plugin with the prefix 
Rename the plugin to `<org prefix>__<package>` in three places:
  - the manifest `name`: `"name": "acme__intake"`
  - the package folder: `intake/` becomes `acme__intake/`. `canvas deploy` refuses a folder that does not match the manifest `name`, before it commits or pushes anything
  - every import and class path that names the package, including the handler and application paths in `CANVAS_MANIFEST.json`: `intake.handlers.events:Handler` becomes `acme__intake.handlers.events:Handler`
If the plugin declares [`custom_data`](/sdk/canvas_manifest/#custom-data):
  - Leave its `namespace` as it is, so the renamed plugin reads and writes the same tables.
  - Remove `namespace_read_access_key` and `namespace_read_write_access_key` from the manifest's `variables`. Canvas Platform holds each namespace's keys and sends them to every plugin entitled to them, and it refuses a manifest that declares them.
  - Before the first deploy, Canvas Platform needs the keys of a namespace that already exists on the instance. Until it has them, `canvas deploy` stops with a message that the instance already has the namespace. Send the instance name, the namespace name, and both keys (the old plugin holds them as secrets) to your Canvas team through the Canvas Platform Support Form, a support ticket, or a 1Password share, and they record them with Canvas Platform. Never send the keys by email or Slack: they grant access to custom data that can hold PHI.
See [Custom data on Canvas Platform](/sdk/custom-data-sharing-data/#custom-data-on-canvas-platform) for how plugins share a namespace.
Then run [`canvas validate`](/sdk/canvas_cli/#canvas-validate) on the renamed package.
###  3\. Give the plugin its own repository 
Canvas Platform hosts one repository per plugin, rooted at the directory that contains the package:
    ```text
    intake-plugin/            # repository root
    ├── acme__intake/
    │   ├── CANVAS_MANIFEST.json
    │   └── handlers/
    ├── pyproject.toml
    └── tests/
    ```
If the package is not in a git repository yet, `canvas deploy` offers to create one at its parent directory. If the package sits inside a larger repository with other code, move it into a repository of its own first, since `deploy` refuses a package nested deeper than that. Add a `.gitignore` for virtual environments and local secrets, because the repository is what gets deployed.
If the plugin already has its own repository on GitHub or elsewhere, rename that remote before the first deploy. `canvas deploy` points the repository's `origin` remote at Canvas Platform, replacing whatever `origin` pointed to:
    ```console
    $ git remote rename origin github
    ```
Your existing repository stays reachable as `github`, and `origin` becomes the plugin's repository on Canvas Platform.
###  4\. Push the code and store its variables 
Push the code without deploying it, so Canvas Platform knows the plugin:
    ```console
    $ canvas deploy intake-plugin/acme__intake --push-only
    ```
Then store its variable values for the instance. The plugin is not installed there yet, so the values wait for the first deploy:
    ```console
    $ canvas config set acme__intake API_URL=https://api.example.com API_TOKEN=abc123 --instance acme-staging
    ```
A variable's sensitivity comes from the manifest's [`variables`](/sdk/canvas_manifest/#variables) block. `canvas config list intake --host acme-staging` shows which variables the old plugin has set.
###  5\. Switch the instance over 
The renamed plugin is a separate plugin from the one installed under the old name, and both respond to the same events while both are enabled. Disable the old plugin, deploy the new one, then remove the old one once the new one is working:
    ```console
    $ canvas disable intake --host acme-staging
    $ canvas deploy intake-plugin/acme__intake --instance acme-staging
    $ canvas uninstall intake --host acme-staging
    ```
`canvas deploy` waits up to 300 seconds for each instance's outcome and exits non-zero unless every instance succeeds in that time.
> **Warning:** **Uninstalling the old plugin deletes its banner alerts.** Banners on patient charts and claims belong to the plugin that added them. They're hidden while the old plugin is disabled, and `canvas uninstall` deletes them. To keep them, have the renamed plugin read the old plugin's banners with [`BannerAlert`](/sdk/data-banner-alert/) or [`ClaimBannerAlert`](/sdk/data-claim/#claimbanneralert), filtered on `plugin_name='intake'` and `status='active'`, and add them again with [`AddBannerAlert`](/sdk/effect-banner-alerts/) or [`ClaimEffect.add_banner()`](/sdk/effect-claims/#add-banner) before you uninstall the old plugin.
> **Info:** **Protocol cards aren't deleted, but they stop showing.** A patient's chart shows only [protocol cards](/sdk/effect-protocol-cards/) from enabled plugins, so the old plugin's cards disappear when you disable it. Uninstalling it leaves them hidden. The renamed plugin's cards appear as it adds them.
Repeat steps 4 and 5 for each instance that runs the plugin. From now on, ship changes with `canvas deploy`.
##  Move CI 
CI/CD pipelines are supported through service accounts. A service account belongs to your organization rather than to a person, so a pipeline keeps deploying when the person who set it up leaves, and Canvas Platform's audit log names the account behind each deploy. An Organization admin, Plugin developer or Deploy manager creates one on the Credentials page in Canvas Platform. An Organization admin can give it both the Plugin developer and Deploy manager roles the pipeline needs; a Plugin developer or Deploy manager can give only the roles they hold. Its token is shown once and lasts a year; store it as a CI secret, expose it as `CANVAS_PLATFORM_TOKEN`, and delete the instance's `client_id` and `client_secret` from CI:
    ```yaml
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - run: pip install canvas
    - run: canvas deploy intake-plugin/acme__intake --instance acme-staging --yes
      env:
        CANVAS_PLATFORM_TOKEN: ${{ secrets.CANVAS_PLATFORM_TOKEN }}
    ```
`fetch-depth: 0` checks out the full history, which the push to Canvas Platform needs. That push is not forced, so it is refused when Canvas Platform's `main` has a commit the pipeline's checkout lacks, such as one a developer deployed from their machine without pushing it to the repository the pipeline checks out. Once a pipeline deploys a plugin, deploy it only from the pipeline.
`--yes` commits any uncommitted changes with the default message. A deploy that needs consent for custom data access exits non-zero and lists the requests, so answer those from a terminal. [Service accounts for CI/CD](/sdk/canvas_cli/#service-accounts-for-cicd) covers rotating and revoking the token.
##  Other machines and teammates 
Each developer runs `canvas login` once on their own machine. A teammate who has not worked on the plugin yet gets a ready-to-deploy checkout with [`canvas clone`](/sdk/canvas_cli/#canvas-clone):
    ```console
    $ canvas clone acme__intake
    ```
Keep `~/.canvas/credentials.ini` until `canvas logs`, `list`, `enable`, `disable`, `config list` and the `namespace` commands also sign in through Canvas Platform, because they authenticate with it today. [Instance API credentials](/sdk/canvas_cli/#instance-api-credentials-credentialsini-deprecated) lists which commands still use it. Once none do, delete the file and revoke the OAuth clients it named on each instance.

---

# Drive Navigator from your coding agent (MCP)

Source: https://docs.canvasmedical.com/guides/navigator-mcp/

Navigator is Canvas's AI assistant for builders. It answers questions about the Canvas SDK and FHIR API, your own deployed plugins, and recent product updates, with read-only access and strict per-customer scope. You normally talk to Navigator in your Canvas Slack channel, but your developers can also drive it from a coding agent such as [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or Cursor, so you can ask without leaving your editor.
This guide connects your coding agent to Navigator over a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) endpoint. It's the same assistant with the same scope and privacy rules; only the entry point changes.
> **Info:** The MCP endpoint is opt-in per Canvas instance and off by default. If Navigator says it can't set up MCP access, ask your Canvas contact to enable it for your instance.
##  Prerequisites 
  - A Canvas Navigator deployment for your organization, with the MCP endpoint enabled.
  - A coding agent that supports streamable-HTTP MCP servers, such as [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or Cursor.
  - An email address on your Slack profile. Your key is delivered to that address, so Navigator can't issue one without it.
##  1\. Get your API key 
Keys are personal: each developer requests their own, from your Navigator Slack channel.
  1. Ask Navigator for MCP access, for example: _"@Navigator can I get an MCP key?"_ or _"@Navigator how do I use you from Claude Code?"_
  2. Navigator confirms in the channel, then sends you a **direct message** with a 1Password link to your key and the `claude mcp add` command to run.
  3. Open the link in any browser; you don't need a 1Password account. Only the email address on your Slack profile can open it, and 1Password emails you a verification code first. The link opens once and expires; the DM says when. Save the key to your own password manager while you're there.
The key itself never passes through Slack, and Canvas stores only a hash of it, so nobody can look it up for you later. If you miss the link's window or lose the key, ask Navigator for a new one.
A key that sits unused for 90 days, or that is never used within 14 days of being issued, is revoked automatically. If your key leaks, tell your Canvas contact and they'll revoke it.
##  2\. Connect your coding agent 
Run the command from Navigator's DM, pasting your key in place of the placeholder. It has this shape:
    ```shell
    claude mcp add --transport http --scope user navigator https://<your-navigator-endpoint>/mcp \
      --header "Authorization: Bearer PASTE_YOUR_KEY_HERE"
    ```
Use the URL exactly as sent; the endpoint is specific to your Canvas instance.
Using a different MCP client, such as Cursor? Add an HTTP MCP server pointing at the same `/mcp` URL, with an `Authorization: Bearer <your-api-key>` header. A minimal config looks like:
    ```json
    {
      "mcpServers": {
        "navigator": {
          "url": "https://<your-navigator-endpoint>/mcp",
          "headers": {
            "Authorization": "Bearer <your-api-key>"
          }
        }
      }
    }
    ```
Then restart your agent and confirm the connection. In Claude Code, run `/mcp` and check that `navigator` is listed and connected.
Navigator can take a minute or two per answer, since it consults several sources before replying. If your agent times out waiting, raise its MCP tool timeout. In Claude Code, set `MCP_TOOL_TIMEOUT=300000` (five minutes, in milliseconds).
##  3\. Ask Navigator 
Talk to your coding agent in plain language and mention Navigator, for example _"ask Navigator how FHIR group IDs work in Canvas"_. Your agent routes the question to Navigator and relays the answer. Behind the scenes it has two Navigator tools:
  - **`ask`** sends a question to Navigator.
  - **`feedback`** sends a 👍 or 👎, with an optional comment, on Navigator's answers.
Navigator sees only what your agent puts in the question. It has no access to your files, your terminal, or the rest of your conversation with your agent, so when a question depends on your code or an error message, your agent includes that context in the question. Follow-up questions in the same conversation continue the same Navigator session, so Navigator remembers its earlier answers.
Things to ask:
  - _How do I add a plugin that listens for a new appointment?_
  - _Which FHIR resource holds the medication list?_
  - _Why isn't our scheduling plugin firing?_ Navigator reads your own deployed plugin and compares it against the reference implementation.
  - _What does "Create New From Existing Form" do in the Questionnaire Builder?_ When the docs don't cover an on-screen feature, Navigator explains it from the Canvas source for the release your instance runs.
  - _Write a SQL query for patients with an active prescription._ Navigator drafts the query and validates it against your instance's schema, without ever running it.
  - _What shipped in the last two weeks?_
##  Scope and privacy 
Navigator over MCP has the same guardrails as Navigator in Slack:
  - **Per-customer isolation** : Navigator only ever sees your own Canvas instance and plugins, never another customer's.
  - **Read-only** : Navigator answers questions and drafts code and queries; it never writes to your instance or runs the SQL it drafts.
  - **PHI handling** : every reply is screened before it reaches you, and PHI is redacted unless your organization has explicitly opted in under its BAA.
  - **Attributable** : each request is tied to your personal API key.

---

# Note Management External Application Integration Guide

Source: https://docs.canvasmedical.com/guides/note-management-oauth/

This guide demonstrates how to build an external application that integrates with Canvas Medical using OAuth 2.0 authentication to manage notes (lock, sign, unlock, check-in, no-show).
##  Table of Contents 
  1. Overview
  2. OAuth 2.0 Setup
  3. Plugin Architecture
  4. Implementation Details
  5. API Endpoints
* * *
##  Overview 
[Note Management Plugin](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins/note_management_app/note_management_app) demonstrates a complete integration pattern for external applications that need to:
  1. Authorize users via OAuth 2.0 Authorization Code Flow with PKCE
  2. Automatically refresh access tokens
  3. Call Canvas Simple API endpoints to perform note operations
###  Key Components 
  - **Application Handler** : Launches the web application in a new tab
  - **HTML Application** : Single-page application with OAuth flow and note management UI
  - **API Endpoints** : RESTful API for note operations (lock, sign, unlock, check-in, no-show)
* * *
##  OAuth 2.0 Setup 
###  Step 1: Create an OAuth Application in Canvas 
  1. Log in to your Canvas instance as an administrator
  2. Navigate to **Settings > Integrations > OAuth Applications**
  3. Click **Create Application**
  4. Configure the application:
     - **Name** : `Note Management App` (or your preferred name)
     - **Client Type** : `Public` (for browser-based apps that cannot securely store client secrets)
     - **Authorization Grant Type** : `Authorization Code`
     - **Redirect URIs** : Add your application's redirect URI
       - For production: `https://your-instance.canvasmedical.com/plugin-io/api/note_sign_api/app`
     - **Scopes** : Add `offline_access` (this allows the app to receive refresh tokens)
  5. **Save** the application
  6. Copy the **Client ID** \- you'll need this in the next step
###  Step 2. Deploy the Plugin 
Copy the example into a repository of its own and rename the package with your organization's plugin prefix, such as `acme__note_management_app` (see [Moving to Canvas Platform](/guides/moving-to-canvas-platform/#2-rename-the-plugin-with-the-prefix) for the places the name appears). Then deploy it and set the Client ID:
    ```bash
    canvas deploy note_management_app/acme__note_management_app --instance <YOUR_INSTANCE>
    canvas config set acme__note_management_app client_id=<YOUR_CLIENT_ID> --instance <YOUR_INSTANCE>
    ```
###  OAuth Flow Details 
####  Authorization Code Flow with PKCE 
This application implements the OAuth 2.0 Authorization Code Flow with Proof Key for Code Exchange (PKCE), which is the recommended flow for public clients (browser-based applications).
**Why PKCE?**
  - Protects against authorization code interception attacks
  - No client secret needed (suitable for public clients)
  - More secure for browser-based applications
**Flow Steps:**
  1. **Generate Code Verifier and Challenge**
         ```javascript
         // Generate a random string (43-128 characters)
         const codeVerifier = generateRandomString(128);
         // Create SHA-256 hash and base64url encode
         const codeChallenge = await generateCodeChallenge(codeVerifier);
         ```
  2. **Authorization Request**
         ```shell
         GET /auth/authorize/?
           response_type=code&
           client_id={CLIENT_ID}&
           redirect_uri={REDIRECT_URI}&
           scope=offline_access&
           code_challenge={CODE_CHALLENGE}&
           code_challenge_method=S256&
           launch=e30K
         ```
**Parameters:**
     - `response_type=code`: Request an authorization code
     - `client_id`: Your application's client ID
     - `redirect_uri`: Where Canvas will redirect after authorization
     - `scope=offline_access`: Request a refresh token for long-lived access
     - `code_challenge`: Base64url-encoded SHA-256 hash of the code verifier
     - `code_challenge_method=S256`: Indicates SHA-256 hashing
     - `launch=e30K`: Launch context (base64-encoded empty JSON object `{}`)
  3. **User Authorization**
     - User is redirected to Canvas login/authorization page
     - User authenticates and authorizes the application
     - Canvas redirects back to `redirect_uri` with an authorization code
  4. **Token Exchange**
         ```javascript
         POST /auth/token/
         Content-Type: application/x-www-form-urlencoded
         grant_type=authorization_code&
         code={AUTHORIZATION_CODE}&
         redirect_uri={REDIRECT_URI}&
         client_id={CLIENT_ID}&
         code_verifier={CODE_VERIFIER}
         ```
**Response:**
         ```json
         {
           "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
           "refresh_token": "6KHq3fjkSWQ1vaBbF6WHG9...",
           "token_type": "Bearer",
           "expires_in": 36000,
           "scope": "offline_access"
         }
         ```
**Token Lifetimes:**
     - **Access Token** : Valid for 10 hours (36,000 seconds)
     - **Refresh Token** : Non-expiring, single-use token
  5. **Token Refresh**
         ```javascript
         POST /auth/token/
         Content-Type: application/x-www-form-urlencoded
         grant_type=refresh_token&
         refresh_token={REFRESH_TOKEN}&
         client_id={CLIENT_ID}&
         scope=offline_access
         ```
**Response:** Returns new access token and new refresh token
* * *
##  Plugin Architecture 
###  Directory Structure 
    ```shell
    note_sign_api/
    ├── handlers/
    │   ├── __init__.py
    │   ├── api.py              # API endpoints for note operations
    │   ├── application.py       # Application handler
    ├── templates/
    │   └── note_management_app.html  # HTML application
    ├── CANVAS_MANIFEST.json
    └── README.md
    ```
###  Component Overview 
####  1\. Application Handler (`handlers/application.py`) 
The Application handler launches the web application when triggered:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class NoteManagementApplication(Application):
        """External note management application with OAuth integration."""
        def on_open(self) -> Effect:
            """Handle the application open event.
            Launches the note management application in a new window.
            """
            # Build the URL to the API endpoint that serves the HTML
            # Using relative path - Canvas will resolve to the correct instance
            app_url = "/plugin-io/api/note_sign_api/app"
            return LaunchModalEffect(
                url=app_url,
                target=LaunchModalEffect.TargetType.NEW_WINDOW,
            ).apply()
    ```
####  2\. App API Handler (`handlers/api.py` \- AppApi class) 
Serves the HTML application:
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note import Note
    from canvas_sdk.effects.simple_api import HTMLResponse, JSONResponse, Response
    from canvas_sdk.handlers.simple_api import Credentials, SimpleAPI, api
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Note as NoteModel
    class AppApi(SimpleAPI):
        """API handler for serving the note management application."""
        PREFIX = ""
        def authenticate(self, credentials: Credentials) -> bool:
            """Allow access without authentication.
            The OAuth flow will handle authentication within the app.
            """
            return True
        @api.get("/app")
        def note_management_app(self) -> list[Response | Effect]:
            """Serve the note management application HTML."""
            # Get the Canvas instance URL from the request Host header
            host = self.request.headers.get("Host", "localhost:8000")
            # Determine protocol based on host
            if "localhost" in host or "127.0.0.1" in host:
                canvas_instance = f"http://{host}"
            else:
                canvas_instance = f"https://{host}"
            # Render the HTML template with context
            context = {"canvas_instance": canvas_instance}
            return [
                HTMLResponse(
                    render_to_string("templates/note_management_app.html", context),
                    status_code=HTTPStatus.OK,
                )
            ]
    ```
####  3\. Note API Handler (`handlers/api.py` \- NoteApi class) 
Provides RESTful API endpoints for note operations:
    ```python
    from http import HTTPStatus
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.note import Note
    from canvas_sdk.effects.simple_api import HTMLResponse, JSONResponse, Response
    from canvas_sdk.handlers.simple_api import Credentials, SimpleAPI, api
    from canvas_sdk.templates import render_to_string
    from canvas_sdk.v1.data import Note as NoteModel
    class NoteApi(SimpleAPI):
        """API handler for note-related operations."""
        PREFIX = "/notes"
        def authenticate(self, credentials: Credentials) -> bool:
            """Authenticate requests."""
            return self.event.actor.instance is not None
        @api.post("/<id>/lock")
        def lock_note(self) -> list[Response | Effect]:
            """Lock a note."""
            note_id = self.request.path_params["id"]
            try:
                note_instance = NoteModel.objects.get(id=note_id)
            except NoteModel.DoesNotExist:
                return [
                    JSONResponse(
                        {"error": "Note not found."},
                        status_code=404,
                    )
                ]
            note = Note(instance_id=note_instance.id)
            return [note.lock()]
    ```
* * *
##  Implementation Details 
####  Key JavaScript Functions 
#####  PKCE Implementation 
    ```javascript
    // Generate random string for code verifier
    function generateRandomString(length) {
        const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
        let result = '';
        const randomValues = new Uint8Array(length);
        crypto.getRandomValues(randomValues);
        for (let i = 0; i < length; i++) {
            result += charset[randomValues[i] % charset.length];
        }
        return result;
    }
    // Generate code challenge from verifier
    async function generateCodeChallenge(codeVerifier) {
        const encoder = new TextEncoder();
        const data = encoder.encode(codeVerifier);
        const hash = await crypto.subtle.digest('SHA-256', data);
        const base64 = btoa(String.fromCharCode(...new Uint8Array(hash)));
        return base64.replace(//g, '-').replace(/\//g, '_').replace(/=/g, '');
    }
    ```
#####  OAuth Initiation 
    ```javascript
    async function initiateOAuth() {
        // Generate PKCE values
        const codeVerifier = generateRandomString(128);
        const codeChallenge = await generateCodeChallenge(codeVerifier);
        // Store verifier for token exchange
        sessionStorage.setItem('code_verifier', codeVerifier);
        // Build authorization URL
        const authUrl = `${CANVAS_INSTANCE}/auth/authorize/?` +
            `response_type=code` +
            `&client_id=${encodeURIComponent(CLIENT_ID)}` +
            `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
            `&scope=${encodeURIComponent(SCOPES)}` +
            `&code_challenge=${codeChallenge}` +
            `&code_challenge_method=S256` +
            `&launch=${LAUNCH_CONTEXT}`;
        // Redirect to Canvas authorization
        window.location.href = authUrl;
    }
    ```
#####  Token Exchange 
    ```javascript
    async function handleAuthCallback() {
        const urlParams = new URLSearchParams(window.location.search);
        const code = urlParams.get('code');
        if (code) {
            const codeVerifier = sessionStorage.getItem('code_verifier');
            const response = await fetch(`${CANVAS_INSTANCE}/auth/token/`, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/x-www-form-urlencoded',
                },
                body: new URLSearchParams({
                    grant_type: 'authorization_code',
                    code: code,
                    redirect_uri: REDIRECT_URI,
                    client_id: CLIENT_ID,
                    code_verifier: codeVerifier
                })
            });
            const data = await response.json();
            saveTokens(data);
            // Clean up
            window.history.replaceState({}, document.title, window.location.pathname);
            sessionStorage.removeItem('code_verifier');
            updateUI();
        }
    }
    ```
#####  Token Storage and Refresh 
    ```javascript
    function saveTokens(tokenData) {
        localStorage.setItem(ACCESS_TOKEN_KEY, tokenData.access_token);
        localStorage.setItem(REFRESH_TOKEN_KEY, tokenData.refresh_token);
        // Calculate expiry time
        const expiryTime = Date.now() + (tokenData.expires_in * 1000);
        localStorage.setItem(TOKEN_EXPIRY_KEY, expiryTime.toString());
        // Schedule refresh 5 minutes before expiry
        scheduleTokenRefresh(tokenData.expires_in - 300);
    }
    async function refreshAccessToken() {
        const refreshToken = localStorage.getItem(REFRESH_TOKEN_KEY);
        const response = await fetch(`${CANVAS_INSTANCE}/auth/token/`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
            },
            body: new URLSearchParams({
                grant_type: 'refresh_token',
                refresh_token: refreshToken,
                client_id: CLIENT_ID
            })
        });
        const data = await response.json();
        saveTokens(data);
        showSuccess('Access token refreshed automatically');
    }
    ```
#####  API Calls 
    ```javascript
    async function performAction(action) {
        const noteId = document.getElementById('noteId').value.trim();
        const accessToken = localStorage.getItem(ACCESS_TOKEN_KEY);
        const actionMap = {
            'lock': '/lock',
            'sign': '/sign',
            'unlock': '/unlock',
            'lock_sign': '/lock_sign',
            'checkin': '/checkin',
            'noshow': '/noshow'
        };
        const endpoint = actionMap[action];
        const response = await fetch(
            `${CANVAS_INSTANCE}/plugins/note_sign_api/notes/${noteId}${endpoint}`,
            {
                method: 'POST',
                headers: {
                    'Authorization': `Bearer ${accessToken}`,
                    'Content-Type': 'application/json'
                }
            }
        );
        if (!response.ok) {
            // Handle errors, possibly refresh token if 401
            if (response.status === 401) {
                await refreshAccessToken();
            }
        }
    }
    ```
* * *
##  API Endpoints 
###  Base URL 
All plugin API endpoints are prefixed with:
    ```shell
    https://your-instance.canvasmedical.com/plugin-io/api/note_sign_api/
    ```
###  Available Endpoints 
####  1\. Serve Application 
    ```shell
    GET /app
    ```
**Description** : Serves the HTML application
* * *
####  2\. Lock Note 
    ```shell
    POST /notes/<note_id>/lock
    ```
**Description** : Locks a note to prevent further editing
* * *
####  3\. Sign Note 
    ```shell
    POST /notes/<note_id>/sign
    ```
**Description** : Signs a note (if signature is required)
* * *
####  4\. Lock and Sign Note 
    ```shell
    POST /notes/<note_id>/lock_sign
    ```
**Description** : Locks and signs a note in one operation
* * *
####  5\. Unlock Note 
    ```shell
    POST /notes/<note_id>/unlock
    ```
**Description** : Unlocks a previously locked or signed note
* * *
####  6\. Check In 
    ```shell
    POST /notes/<note_id>/checkin
    ```
**Description** : Marks an appointment as checked in
* * *
####  7\. No Show 
    ```shell
    POST /notes/<note_id>/noshow
    ```
**Description** : Marks an appointment as no-show
* * *
##  Security Considerations 
###  1\. Token Storage 
**Current Implementation** : Tokens are stored in `localStorage`
**Considerations** :
  - `localStorage` is vulnerable to XSS attacks
  - For production, consider using:
    - HTTP-only cookies (requires backend support)
    - Session storage (cleared when tab closes)
    - Encrypted storage solutions
###  2\. PKCE Protection 
  - PKCE prevents authorization code interception attacks
  - Code verifier is stored in `sessionStorage` (temporary)
  - Code challenge is sent to authorization server
  - Server verifies verifier matches challenge during token exchange
###  3\. Token Refresh 
  - Refresh tokens are single-use (Canvas rotates them)
  - Access tokens are short-lived (10 hours)
  - Automatic refresh happens before expiry
  - Failed refresh triggers re-authentication
###  4\. API Authentication 
> **⚠️ Important** : The current implementation relies on the OAuth-authenticated user from Canvas. This is a simplified example for demonstration purposes.
**Current Implementation** :
    ```python
    from canvas_sdk.handlers.simple_api import Credentials
    def authenticate(self, credentials: Credentials) -> bool:
        return self.event.actor.instance is not None
    ```
This basic authentication check verifies that there is an authenticated Canvas user making the request.
**Production Recommendations** :
See the official documentation for supported authentication mechanisms: [Canvas SDK Authentication Guide](https://docs.canvasmedical.com/sdk/handlers-simple-api-http/#authentication)
* * *
##  Additional Resources 
  - [Canvas Customer Authentication Documentation](https://docs.canvasmedical.com/api/customer-authentication/)
  - [OAuth 2.0 Authorization Code Flow](https://oauth.net/2/grant-types/authorization-code/)
  - [PKCE RFC 7636](https://tools.ietf.org/html/rfc7636)

---

# How to group items on a patient chart section

Source: https://docs.canvasmedical.com/guides/patient-chart-group-items/

This guide explains how to group items on a patient chart section. With this, you can define custom groups to organize medications, conditions, or detected issues.
Currently, this is supported for the Conditions, Medications, and Detected Issues sections.
##  What you'll learn: 
  - Use the [`PatientChartGroup`](/sdk/patient-chart-group-effect) effect to group items in a section by priority.
  - Group conditions based on ICD-10 code ranges
  - Group detected issues (such as coding gaps) by custom criteria
##  Patient Chart Group 
The `PatientChartGroup` effect allows you to group items in a patient chart section. You can define multiple groups with a name, priority, and the items that belong to each group.
####  3\. The plugin 
Here's an example of a plugin that groups conditions based on their codes - here we are creating a "Psychiatry" group for ICD-10 codes F01-F99 and R45.x and placing all matching conditions in that group.
    ```python
    from canvas_sdk.effects.patient_chart_group import PatientChartGroup
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.group import Group
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.commands.constants import CodeSystems
    class Handler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART__CONDITIONS)
        def compute(self) -> list[Effect]:
            groups: dict[str, Group] = {}
            groups.setdefault("Psychiatry", Group(priority=100, items=[], name="Psychiatry"))
            for condition in self.event.context:
               for coding in condition["codings"]:
                   if coding["system"] == CodeSystems.ICD10 and ("F01" <= coding["code"] <= "F99" or coding["code"].startswith("R45.")):
                       groups["Psychiatry"].items.append(condition)
                       break
            return [PatientChartGroup(items=groups).apply()]
    ```
####  4\. The Output 
Below, you can see how it will appear in the app.
![patient chart group](/assets/images/patient-chart-group.png)
##  Grouping Detected Issues 
You can also group detected issues, such as coding gaps, using the same approach. Here's an example that groups detected issues by their status or other criteria:
    ```python
    from canvas_sdk.effects.patient_chart_group import PatientChartGroup
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.group import Group
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class GroupDetectedIssues(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART__DETECTED_ISSUES)
        def compute(self) -> list[Effect]:
            groups: dict[str, Group] = {}
            groups.setdefault("High Priority", Group(priority=200, items=[], name="High Priority"))
            groups.setdefault("Standard", Group(priority=100, items=[], name="Standard"))
            for detected_issue in self.event.context:
                # Group by custom logic - for example, based on evidence or other attributes
                # Note: The context for detected issues contains only the "id" field
                # You may need to query additional data using the SDK if needed
                # Example: place first 5 in high priority, rest in standard
                if len(groups["High Priority"].items) < 5:
                    groups["High Priority"].items.append(detected_issue)
                else:
                    groups["Standard"].items.append(detected_issue)
            return [PatientChartGroup(items=groups).apply()]
    ```
**Note:** The context structure for detected issues differs from conditions and medications. The `PATIENT_CHART__DETECTED_ISSUES` event context includes only the `id` field for each detected issue. If you need additional information (such as evidence, status, or code) to determine grouping logic, you'll need to query the detected issue data using the Canvas SDK's data models.

---

# Testing Pharmacy Workflows in a Staging Environment

Source: https://docs.canvasmedical.com/guides/pharmacy-staging-testing/

Canvas can point a **non-production (dev or staging)** instance at our staging services so you can build and validate e-prescribing and pharmacy workflows — NewRx, eligibility, benefit, and medication-history requests — against Surescripts staging, without sending real prescriptions or touching production data.
This is a **beta** offering. It is intended for development and testing only; because it uses non-production endpoints, some edge cases may not behave exactly as they do in production.
> **Info:** **Two different things are called "staging" here — keep them separate.**  
> **(1) Your Canvas environment.** This can be enabled on a **non-production** Canvas instance — either a **dev** or a **staging** instance. It is never enabled on production.  
> **(2) Canvas staging services.** Once enabled, that non-production instance is pointed at Canvas's staging services, and e-prescribing routes to **Surescripts staging**. Routing pharmacy to Surescripts staging is tied to switching the instance's other services to staging as well (see the next section).
* * *
##  What you'll learn 
  1. How to request the staging switch for your dev or staging instance
  2. How to create the test prescriber (FHIR Practitioner)
  3. How to create the Surescripts canonical test patients (FHIR Patient)
  4. How to run eligibility, benefit, and medication-history requests against them
* * *
##  1\. Request the staging switch 
Staging setup is performed by Canvas. To get started, [submit a request to Canvas Support](https://portal.usepylon.com/canvas-medical/forms/standard) asking to switch your **dev or staging (non-production)** instance to Canvas staging services. This routes the instance's e-prescribing to **Surescripts staging**.
> **Warning:** **The switch is all-or-nothing — it is not scoped to pharmacy alone.** Pointing a non-production instance at Canvas staging repoints **all** of its backend services to staging: messaging, ontologies, pharmacy, science, web-to-pdf, and the FHIR (Fumage) host. Practically, that means drug/allergy and other lookups resolve against **staging ontologies** , and your FHIR base URL becomes the **staging Fumage host**. Only request this for a dev or staging instance you are comfortable running entirely against Canvas staging services.
As part of the switch, Canvas Support will:
  - Repoint your instance's service endpoints to Canvas staging.
  - Register your test prescriber's Surescripts SPI for staging and map the prescriber to your instance so prescriptions route correctly. (You add the SPI value to the staff profile yourself — see step 2.)
  - Confirm the **staging FHIR base URL** to use for the API calls in this guide.
The examples below use `https://fumage-staging.canvasmedical.com`. Use the exact base URL Canvas Support gives you for your instance.
* * *
##  2\. Create the test prescriber 
Create the prescriber with the [FHIR Practitioner Create](/api/practitioner/#create) endpoint. Use the NPI shown here — Canvas Support maps this NPI to your instance during setup, so it must match.
    ```sh
    curl --request POST \
         --url 'https://fumage-staging.canvasmedical.com/Practitioner' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --data '
    {
        "resourceType": "Practitioner",
        "extension": [
            {
                "url": "http://schemas.canvasmedical.com/fhir/extensions/practitioner-user-username",
                "valueString": "wbest"
            },
            {
                "url": "http://schemas.canvasmedical.com/fhir/extensions/roles",
                "extension": [
                    {
                        "url": "code",
                        "valueCoding": {
                            "system": "http://schemas.canvasmedical.com/fhir/roles",
                            "code": "DO"
                        }
                    }
                ]
            }
        ],
        "identifier": [
            {
                "system": "http://hl7.org/fhir/sid/us-npi",
                "value": "3688523885"
            }
        ],
        "active": true,
        "name": [
            {
                "use": "usual",
                "family": "Best",
                "given": ["Wayne"]
            }
        ],
        "telecom": [
            { "system": "phone", "value": "9149603674", "use": "work", "rank": 1 },
            { "system": "fax",   "value": "9149603674", "use": "work", "rank": 1 },
            { "system": "email", "value": "wayne.best@example.com", "use": "work", "rank": 1 }
        ],
        "address": [
            {
                "use": "work",
                "type": "both",
                "line": ["150 Monument Road", "Suite 500"],
                "city": "Philadelphia",
                "state": "PA",
                "postalCode": "19019",
                "country": "United States"
            }
        ],
        "birthDate": "1966-09-09",
        "qualification": [
            {
                "identifier": [
                    {
                        "system": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-url",
                        "value": "A60695"
                    }
                ],
                "code": { "text": "License" },
                "period": { "start": "2020-06-16", "end": "2035-06-16" },
                "issuer": {
                    "display": "Medical Board of California",
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-short-name",
                            "valueString": "Medical Board of California"
                        },
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/issuing-authority-state",
                            "valueString": "CA"
                        },
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/license-primary",
                            "valueBoolean": true
                        }
                    ]
                }
            }
        ]
    }
    '
    ```
Notes:
  - **Add the SPI manually.** The Surescripts SPI is not a FHIR field, so it cannot be set in the payload above. After you create the practitioner, open the staff profile in Canvas and add the SPI **`5630156655001`** by hand. Canvas maps this SPI to your instance during setup, so prescriptions signed by this prescriber transmit correctly against Surescripts staging.
  - **The`DO` role must exist on your instance.** The payload assigns the `DO` role via the `roles` extension. Staff role codes are configurable per instance, so if `DO` is not defined on yours the create will fail — change it to a prescriber role that does exist on your instance (for example `MD`, `NP`, or `PA`). See the [staff roles article](https://canvas-medical.help.usepylon.com/articles/6649603926-staff-roles) and the `extension` attribute on the [Practitioner API](/api/practitioner/).
  - The `practitioner-user-username` extension (`wbest` above) becomes the prescriber's login username. Sign and send prescriptions **as this prescriber**.
* * *
##  3\. Create the Surescripts test patients 
Surescripts staging only returns data for its **canonical test patients** , and the match is strict — name, date of birth, sex, and address (especially ZIP) must match exactly. Create these three with the [FHIR Patient Create](/api/patient/#create) endpoint using the demographics below verbatim.
Patient| Date of birth| Sex| Address  
---|---|---|---  
Soloman Bergamel| 1970-03-21| M| 1948 Bainbridge St, Philadelphia, PA 19146  
Zachary Delaplaine| 2010-12-01| M| 901 Sauvblanc Blvd, Petaluma, CA 94952  
Kara Whiteside| 1952-10-11| F| 23230 Seaport, Akron, OH 91701  
###  Soloman Bergamel 
    ```sh
    curl --request POST \
         --url 'https://fumage-staging.canvasmedical.com/Patient' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --data '
    {
        "resourceType": "Patient",
        "extension": [
            {
                "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                "valueCode": "M"
            }
        ],
        "active": true,
        "name": [
            { "use": "official", "family": "Bergamel", "given": ["Soloman"] }
        ],
        "telecom": [
            { "system": "phone", "value": "0000000000", "use": "home", "rank": 1 }
        ],
        "gender": "male",
        "birthDate": "1970-03-21",
        "address": [
            {
                "use": "home",
                "type": "both",
                "line": ["1948 Bainbridge St"],
                "city": "Philadelphia",
                "state": "PA",
                "postalCode": "19146"
            }
        ]
    }
    '
    ```
###  Zachary Delaplaine 
    ```sh
    curl --request POST \
         --url 'https://fumage-staging.canvasmedical.com/Patient' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --data '
    {
        "resourceType": "Patient",
        "extension": [
            {
                "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                "valueCode": "M"
            }
        ],
        "active": true,
        "name": [
            { "use": "official", "family": "Delaplaine", "given": ["Zachary"] }
        ],
        "telecom": [
            { "system": "phone", "value": "0000000000", "use": "home", "rank": 1 }
        ],
        "gender": "male",
        "birthDate": "2010-12-01",
        "address": [
            {
                "use": "home",
                "type": "both",
                "line": ["901 Sauvblanc Blvd"],
                "city": "Petaluma",
                "state": "CA",
                "postalCode": "94952"
            }
        ]
    }
    '
    ```
###  Kara Whiteside 
    ```sh
    curl --request POST \
         --url 'https://fumage-staging.canvasmedical.com/Patient' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --data '
    {
        "resourceType": "Patient",
        "extension": [
            {
                "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
                "valueCode": "F"
            }
        ],
        "active": true,
        "name": [
            { "use": "official", "family": "Whiteside", "given": ["Kara"] }
        ],
        "telecom": [
            { "system": "phone", "value": "1111111111", "use": "home", "rank": 1 }
        ],
        "gender": "female",
        "birthDate": "1952-10-11",
        "address": [
            {
                "use": "home",
                "type": "both",
                "line": ["23230 Seaport"],
                "city": "Akron",
                "state": "OH",
                "postalCode": "91701"
            }
        ]
    }
    '
    ```
* * *
##  4\. Run eligibility, benefit, and medication-history requests 
With the prescriber and a canonical test patient in place, you can exercise the three Surescripts information transactions from a plugin using the [Surescripts effects](/sdk/effect-surescripts/). All three canonical patients above return staging responses for these transactions.
> **Warning:** **The Surescripts effects must be enabled by Canvas.** Ask Canvas Support to enable them for your instance in the same request — until then, the effects will not send.
  - **Eligibility** — `SendSurescriptsEligibilityRequestEffect`. The response arrives asynchronously as a `SURESCRIPTS_ELIGIBILITY_RESPONSE` event; parse it with `SurescriptsEligibilityResponse`.
  - **Benefit** — `SendSurescriptsBenefitsRequestEffect` (takes a medication description + NDC). The response arrives as a `SURESCRIPTS_BENEFITS_RESPONSE` event; parse it with `SurescriptsBenefitsResponse`.
  - **Medication history** — `SendSurescriptsMedicationHistoryRequestEffect`. Canvas retrieves the patient's trailing-12-month fill history and writes it to the chart; there is no paired response event.
Each effect takes the `patient_id` of one of the test patients and the `staff_id` of the prescriber you created above. See [Surescripts Effects](/sdk/effect-surescripts/) for full request/response field references and handler examples.
* * *
##  Test sending a prescription (NewRx) 
To test transmitting a prescription, use **Shollenberger Pharmacy** — NCPDP **1655458** (2002 S. McDowell Blvd Ext, Petaluma, CA 94954). It is a Surescripts staging pharmacy, and NewRx messages sent to it transmit successfully.
Select Shollenberger directly on the **Prescribe** command (in the pharmacy field) when you send the prescription. It **does not need to be set as the patient's preferred pharmacy** — choosing it at prescribe time is enough.
Sign and send as the test prescriber you created above so the outgoing message carries the SPI mapped for your instance.
* * *
##  Good to know 
  - This is a **beta** capability for **non-production (dev or staging)** Canvas instances only. Never request it for a production instance.
  - Surescripts staging processes transactions during business hours (roughly 8 AM – 6 PM ET, Mon–Fri); requests outside that window may not receive a response.
  - Because the whole instance runs against Canvas staging services, ontologies (drug/allergy lookups) and other services also resolve against staging while the switch is in place.

---

# Platform Security Overview

Source: https://docs.canvasmedical.com/guides/platform-security-overview/

This page describes how Canvas is deployed, where its trust boundaries sit, and which security controls are in force before any plugin, integration, or custom code is introduced. It is intended for security and compliance teams evaluating Canvas, and for implementers who need to know which controls they inherit and which they own.
Canvas holds HITRUST CSF r2 certification. The certification report, SOC-equivalent artifacts, and the most recent independent penetration test are available under NDA through your Canvas contact.
##  Deployment and tenancy model 
Every Canvas customer runs on a **dedicated instance** : its own set of immutable application containers and its own database. Customer data is separated at the database level rather than by a row- or column-scoped partition inside a shared store, so there is no query path from one customer's application to another customer's data.
Instances are hosted on Aptible, which runs on AWS in `us-east-1`, inside a segregated virtual private cloud. Application containers are rebuilt from a pinned image on each deploy rather than mutated in place.
##  Trust boundaries 
Requests cross five boundaries, each of which enforces its own controls:
Boundary| Responsibility  
---|---  
Edge| TLS termination, IP allow-listing, rate limiting, WAF and DDoS protection  
Core application| Authentication, session handling, role- and object-level authorization  
Plugin runner| Isolated execution of customer plugin code — see [Plugin Security Model](/guides/plugin-security-model/)  
FHIR API| Scoped, token-based access with patient-context enforcement  
Per-customer database| Tenant-isolated persistence, encrypted at rest  
##  Platform controls 
These apply to every instance and are not customer-configurable.
###  Encryption 
Traffic to and between Canvas services is encrypted with TLS. Databases and disk volumes are encrypted at rest with AES-256. Patient documents stored in object storage are encrypted at rest with AES-256 server-side encryption.
###  Identity and authentication 
Canvas supports SSO via SAML. Where an instance uses SSO — the recommended configuration — password policy, multi-factor authentication, session lifetime, and account lifecycle are governed by your identity provider, and Canvas neither stores nor validates those credentials. Deprovisioning a user at your identity provider removes their access to Canvas.
Where an instance uses Canvas-managed credentials instead, passwords are validated against minimum length, similarity to the user's own name and username, entirely-numeric values, and a list of commonly-used passwords.
Failed-login lockout applies to interactive sessions on either path, independent of the identity provider.
###  Authorization 
Access is governed by role-based access control. Permissions are evaluated at two levels:
  - **Model permissions** determine which record types a user may read or modify.
  - **Object permissions** narrow that further to specific records, scoped by patient group.
Both are administered through roles and groups rather than granted to individuals directly.
###  Network 
Each instance's externally reachable endpoints carry IP allow-lists backed by cloud security groups. Internal services are not exposed to the public internet. Administrative access to Canvas infrastructure requires authentication through the corporate identity provider and traverses a VPN.
###  Privileged access 
Access to production containers is restricted by role. Sessions are recorded end to end, and the resulting logs are retained and reviewable.
##  Shared responsibility 
Canvas operates the platform and its controls. The following remain with the customer:
Area| Customer responsibility  
---|---  
Identity| Enforcing MFA, provisioning and deprovisioning users, periodic access review  
Authorization| Assigning roles and groups according to least privilege  
Plugins and extensions| Reviewing and approving code deployed to your instance — see [Plugin Security Model](/guides/plugin-security-model/)  
Credentials| Custody of API keys, OAuth client secrets, and plugin secrets  
Exported data| Protecting data once it leaves Canvas through an API, export, or replica  
> **Info:** Installing a plugin requires a credential your organization controls, so your own review process can gate what reaches production. See Deployment governance in the Plugin Security Model guide.
##  Related 
  - [Plugin Security Model](/guides/plugin-security-model/)
  - [Roles and Permissions](/guides/roles-and-permissions/)
  - [Audit Logging and Telemetry](/guides/audit-logging-and-telemetry/)
  - [Customer Authentication](/api/customer-authentication/)
  - [Authentication Best Practices](/api/authentication-best-practices/)

---

# Plugin Development Tips and Sandbox Limits

Source: https://docs.canvasmedical.com/guides/plugin-development-tips-and-sandbox-limits/

Canvas plugins run inside a restricted Python sandbox, which shapes what you can import and how you can manipulate data. This guide collects practical tips for building, deploying, and troubleshooting plugins, plus the sandbox behaviors that most commonly trip people up.
##  Troubleshooting: is my code actually deployed? 
Before debugging logic, confirm the code running on the instance is the code you think it is:
  1. **Save and deploy your edits.** Editing a file locally does nothing until you push it to the instance with the [Canvas CLI](/sdk/canvas_cli/). Re-deploy after every change you want to test.
  2. **Verify through the logs.** Stream the instance logs with `canvas logs` and add `log.info(...)` statements to confirm your handler is firing and to inspect the values it sees. If you do not see your log lines, the event you expect is not reaching your handler, or the plugin did not load.
    ```python
    from logger import log
    # inside a handler method
    log.info(f"Handler fired for note {self.event.context.get('note')}")
    ```
If a handler fails to load (for example, an import error at install time), only that handler is skipped — other handlers in the same plugin keep running — so check the logs for load-time errors as well as runtime ones. The exception is a helper module whose functions contain code the sandbox refuses. Then none of the plugin's handlers load, as [Helper modules](/sdk/sandboxing-and-allowed-imports/#helper-modules) describes.
##  Deployment does not require IP whitelisting 
Deploying plugins does **not** require any IP allowlisting. You only need the correct OAuth authentication, as described in [Your First Plugin](/guides/your-first-plugin/#2-configure-the-canvas-cli-for-your-instances) and [customer authentication](/api/customer-authentication/).
##  Sharing code between modules in a plugin 
A plugin can import its own modules. If you have several handlers that do nearly the same thing, factor the shared logic into a base class and import it by its full path from the plugin package (here the plugin package is `my_plugin`):
    ```python
    # my_plugin/protocols/base.py
    from canvas_sdk.handlers import BaseHandler
    class SharedBase(BaseHandler):
        def shared_helper(self):
            ...
    ```
    ```python
    # my_plugin/protocols/my_handler.py
    from my_plugin.protocols.base import SharedBase
    class MyHandler(SharedBase):
        ...
    ```
Relative imports such as `from .base import SharedBase` work too. They resolve against the importing module's package, and one that reaches above your plugin package raises `ImportError`. The allowed-imports list applies to third-party and standard-library modules; any module inside your own plugin package is importable.
##  Time zones: use `zoneinfo.ZoneInfo`
`zoneinfo.ZoneInfo` is allowlisted in the sandbox, so it is the recommended way to handle time zones:
    ```python
    from zoneinfo import ZoneInfo
    TIME_ZONE = "US/Eastern"
    TZ = ZoneInfo(TIME_ZONE)
    ```
##  Calling AWS services without Boto3 (e.g. SNS for reminders) 
The Boto3 library is not available in the sandbox, but you can still call AWS HTTP APIs directly. For example, to build custom branded email/SMS reminders you can publish to Amazon SNS with a normal HTTP request to the region's SNS endpoint:
    ```text
    https://sns.us-east-2.amazonaws.com/?Action=Publish
    &TopicArn=arn%3Aaws%3Asns%3Aus-east-2%3A698519295917%3AMy-Topic
    &Subject=My%20first%20message
    &Message=Hello%20world%21
    &Version=2010-03-31
    &AUTHPARAMS
    ```
(See the [AWS SNS Publish API docs](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html).)
These requests must be signed with [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). You can build the signature inside a plugin because `hmac.new` and `hashlib.sha256` are both allowed imports; [this open-source implementation](https://github.com/andrewjroth/requests-auth-aws-sigv4/blob/master/requests_auth_aws_sigv4/__init__.py) shows how. Make the requests with the [`Http`](/sdk/utils/) util and keep your AWS credentials in [secrets](/sdk/secrets/). This is more manual than using Boto3, but it lets you avoid hosting and maintaining a separate proxy service for the AWS calls.
A typical reminders setup is a [CronTask](/sdk/handlers-crontask/) that runs on a schedule, builds the list of appointments needing reminders, and sends the notifications (directly to SNS as above, or to your own endpoint).
##  Sandbox restrictions on dict reads and writes 
The sandbox routes item access and assignment through internal `_safe_getitem` and `_safe_write` checks. Ordinary lookup errors pass straight through them, so a traceback for a missing key or an empty list names the guard even though the cause is your data:
    ```text
    File ".../sandbox.py", in _safe_getitem
        return ob[index]
    KeyError: 0
    ```
Guard your lookups rather than indexing blindly:
  - Read optional keys with `.get(...)` and provide defaults instead of `ob[key]`, so a missing key does not raise.
  - Confirm a collection is non-empty before indexing into it (`ob[0]`).
The guards also raise their own `AttributeError`s for a few patterns:
  - Dictionaries accept item keys that start with `_`. Other objects may not, such as one of your own classes that implements `__getitem__`. Reading `obj["_private"]` from one raises `"_private" is an invalid item name because it starts with "_"`.
  - Some writes to an object that does not come from your plugin raise `Forbidden assignment to a non-module attribute: ...`. These are overwriting an attribute or item that holds a callable, and setting an attribute on something you imported (`SomeImportedClass.attr = ...`).

---

# Plugin Security Model

Source: https://docs.canvasmedical.com/guides/plugin-security-model/

Plugins let you extend Canvas with your own logic. Because that logic runs inside a system holding patient data, the plugin runtime is deliberately constrained. This page describes those constraints and the deployment controls available to you, so your security team can evaluate what plugin code can and cannot do.
##  Execution model 
Plugins do not manipulate Canvas data directly. They **subscribe to events** and **return declarative effects** that the platform interprets and applies.
That indirection is the core of the model. A plugin describes an intended outcome — add a banner, create a command, send a notification — and the platform decides whether and how to carry it out, applying the same validation and permission rules it applies to any other write. A plugin cannot reach past the effect layer to mutate records itself.
##  Runtime isolation 
The plugin runner executes customer code under several layers of containment:
  - **Process and user isolation.** Plugin code runs in a separate operating-system user and process from the core application.
  - **Restricted interpreter.** Code executes in a RestrictedPython sandbox with an explicit allowlist of importable modules. Modules outside that list are rejected at load time, not at run time.
  - **No direct system access.** Plugins have no direct database connection, no filesystem access, and no operating-system access.
  - **Constrained network surface.** Outbound communication is limited to HTTP and HTTPS through the SDK's supported clients. Raw sockets and non-HTTP protocol libraries are not available in the sandbox.
  - **Package integrity.** Plugin packages are checksummed, and the manifest is validated before a plugin is installed.
Because the module allowlist is enforced when the plugin is loaded, a plugin that attempts a disallowed import fails to install rather than failing partway through a patient-facing workflow.
##  Secrets 
Plugins declare the secrets they need in their manifest, and values are supplied per instance. Secret values are **write-only** from the plugin author's perspective: they can be set and used at runtime, but not read back out through the interface used to configure them.
Treat plugin secrets like any other production credential — scope them narrowly, and rotate them on the same cadence as the rest of your estate.
##  API access 
Where a plugin or external application reaches Canvas through the FHIR API, access is scoped by OAuth token, and patient-context enforcement applies to patient-scoped launches. See [Customer Authentication](/api/customer-authentication/) and [Authentication Best Practices](/api/authentication-best-practices/).
##  Deployment governance 
###  Who can install 
Installing or updating a plugin is an authenticated operation: it requires a client credentials OAuth token carrying the plugin scope for your instance. Canvas refuses a token that a user obtains by approving the scope on their own consent screen. Controlling who holds that credential is the primary control over what reaches your production environment, and it is a control your organization owns.
###  Installing from your own pipeline 
Most organizations keep plugin source in their own repository and install from their own continuous-integration pipeline rather than from individual workstations. Under that arrangement the installing credential lives in CI, and your existing review process — pull-request approval, required checks, protected branches — is what gates production.
Canvas recommends this pattern where your change-management policy requires documented human review before code runs in production.
> **Info:** Plugins built through Canvas Studio follow their own staged workflow, with explicit approval steps before a project is published.
###  Environment separation 
Instances are provisioned per environment, and release channels let you promote a plugin through a lower environment before it reaches production. Deploys are pinned to a specific commit, so what you reviewed is what runs.
###  Change tracking 
Plugin deployment activity is tracked, and plugin runtime activity is instrumented per plugin. Combined with the audit trail described in [Audit Logging and Telemetry](/guides/audit-logging-and-telemetry/), this gives you a record of both what changed and what the plugin did.
##  Recommended practices 
  - Hold the installing credential in CI rather than on workstations, so your pull-request review is what gates production.
  - Scope plugin secrets to the minimum required, and rotate them on your normal cadence.
  - Exercise plugins in a lower environment before promoting to production.
##  Related 
  - [Platform Security Overview](/guides/platform-security-overview/)
  - [Roles and Permissions](/guides/roles-and-permissions/)
  - [Audit Logging and Telemetry](/guides/audit-logging-and-telemetry/)
  - [Your First Plugin](/guides/your-first-plugin/)
  - [Plugin Logs](/sdk/plugin-logs/)

---

# Populating Command Fields

Source: https://docs.canvasmedical.com/guides/populating-command-fields/

When a provider works with a command in the Canvas UI — Assess Condition, Prescribe, Allergy, Refer, and the rest — most fields are backed by an interactive control. You start typing "type 2 diabetes" and the chart autocompletes to an ICD-10 code, you pick a pharmacy from a searchable list, and you choose a severity from a dropdown. The UI does the lookup for you and stores the underlying code, id, or enum value on the command.
When you build those same commands with the [commands module](/sdk/commands/) in a plugin, there is no interactive control. A command field takes the **raw value** — an FDB code, a database id, an ICD-10 code, an enum member — and it is your plugin's job to supply the correct one. This guide shows you where those values come from so your automated charting behaves like a provider working in the UI.
> **Info:** Rule of thumb: if a field is an autocomplete, search box, or dropdown in the UI, it is not free text in the SDK — you must look up the value first.
##  The three sources of command values 
Every value that a UI control would supply comes from one of three places:
In the UI it looks like…| In the SDK you get the value from…| Example  
---|---|---  
A **dropdown** of fixed choices| An **enum** under [Command Constants](/sdk/commands/#command-constants) or the command class| `AllergyCommand.Severity`, `AssigneeType`, `PulseRhythm`  
An **autocomplete of things already on the chart** (or a reference table)| A **[data module](/sdk/data/)** query| An existing `Condition` to assess, a `Staff` key, a `TaskLabel`  
An **autocomplete that searches a terminology** (medications, codes, contacts)| A **[utils HTTP helper](/sdk/utils/)** (Ontologies / Pharmacy / Science)| Search FDB for a drug, ICD-10 for a diagnosis, a pharmacy by name  
The rest of this guide walks through each source.
##  1\. Enums and dropdowns → Command Constants 
Fixed-choice fields map to Python enums. Import the enum and pass a member — don't pass a bare string, and don't invent values. The shared enums are documented under [Command Constants](/sdk/commands/#command-constants); command-specific enums are listed in each command's section.
    ```python
    from canvas_sdk.commands import AllergyCommand
    allergy = AllergyCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        allergy_id="e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
        severity=AllergyCommand.Severity.MODERATE,  # a dropdown in the UI
    )
    ```
Each enum's documentation lists both the member name and the stored value, so you can map an external system's value onto the correct member.
##  2\. Chart records and reference tables → data modules 
Many fields reference something that already exists in Canvas: a condition on the patient's problem list, a staff member, a questionnaire, a lab partner. In the UI these are autocompletes scoped to the chart or to a reference table. In the SDK you query the matching [data module](/sdk/data/) and pass the id it returns.
    ```python
    from canvas_sdk.commands import AssessCommand
    from canvas_sdk.v1.data import Condition
    patient_id = "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
    # The UI would let the provider pick from conditions already on the chart.
    # In a plugin, query for it and pass its id.
    condition = (
        Condition.objects.for_patient(patient_id).committed().active().first()
    )
    assess = AssessCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        condition_id=condition.id,
        status=AssessCommand.Status.STABLE,
    )
    ```
The description of each command field tells you which data module it points to and whether the record has to already be on **that patient's** chart. Common cases:
  - **Existing chart items** — the condition to assess or resolve, the medication to stop or change, the goal to close, the reports to review. Query the data module `for_patient(...)` and use the returned id.
  - **Reference tables** — a [Staff](/sdk/data-staff/#staff) key for an ordering provider, a [Questionnaire](/sdk/data-questionnaire/#questionnaire) to answer, a [LabPartner](/sdk/data-labs/) and its tests, a [TaskLabel](/sdk/data-task/#tasklabel) to apply, a [Vaccine](/sdk/data-vaccine/#vaccine) and its [lots](/sdk/data-vaccine/#vaccinelot) for an immunization. These aren't patient-scoped, but the value still has to match an existing record.
##  3\. Terminology search → utils HTTP helpers 
The richest autocompletes in the UI search a clinical terminology in real time: FDB for medications and allergens, ICD-10 for diagnoses, SNOMED for family/surgical history, a pharmacy directory, an imaging catalog. Those searches are exposed through the [utils](/sdk/utils/) HTTP clients so your plugin can run the same lookup and pass the resulting code.
Command field| Helper  
---|---  
Prescribe / MedicationStatement / Refill / AdjustPrescription medication (`fdb_code`, `new_fdb_code`)| [Searching for medications](/sdk/utils/#searching-for-medications) (Ontologies)  
Allergy allergen| [Searching for allergens](/sdk/utils/#searching-for-allergens) (Ontologies)  
Assess and Diagnose ICD-10 codes (`icd10_code`)| [Looking up clinical codes](/sdk/utils/#looking-up-clinical-codes) (Ontologies)  
Family History, Surgical History, Instruct concepts| [Searching clinical concepts](/sdk/utils/#searching-clinical-concepts) (Ontologies)  
Prescribe pharmacy (`pharmacy`)| [Searching for pharmacies](/sdk/utils/#searching-for-pharmacies) (Pharmacy)  
ImagingOrder image code| [Searching for imaging codes](/sdk/utils/#searching-for-imaging-codes) (Science)  
Refer / ImagingOrder / care-team service providers (including imaging centers)| [Searching for contacts and service providers](/sdk/utils/#searching-for-contacts-and-service-providers) (Science)  
For example, the UI autocompletes a diagnosis; a plugin searches ICD-10 and passes the code it finds:
    ```python
    import json
    from urllib.parse import urlencode
    from canvas_sdk.utils.http import ontologies_http
    from canvas_sdk.commands import AssessCommand
    response = ontologies_http.get(
        f"/icd/condition/?{urlencode({'search': 'type 2 diabetes'})}"
    )
    first = json.loads(response.text)[0]
    assess = AssessCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        icd10_code=first["icd10_code"],
    )
    ```
See the [utils](/sdk/utils/) reference for the parameters and response shape of each endpoint.
##  Putting it together 
A single command often draws on more than one source. A Prescribe command, for instance, combines a terminology search, a directory search, a reference-table id, and an enum:
    ```python
    from canvas_sdk.commands import PrescribeCommand
    from canvas_sdk.v1.data import Staff
    fdb_code = "..."               # from the medication search (utils)
    ncpdp_id = "..."               # from the pharmacy search (utils)
    staff = Staff.objects.first()  # the prescriber
    prescribe = PrescribeCommand(
        note_uuid="8f4b1e2c-9a3d-4c7e-b1f6-2d5a8c0e3b47",
        fdb_code=fdb_code,               # utils: medication search
        icd10_codes=["E119"],            # from the patient's active conditions
        pharmacy=ncpdp_id,               # utils: pharmacy search
        prescriber_id=staff.id,          # data module: Staff reference table
        substitutions=PrescribeCommand.Substitutions.ALLOWED,  # enum
        quantity_to_dispense=30,
    )
    ```
##  Interaction screening for medication commands 
In the Canvas UI, when a provider stages a medication command (such as Prescribe), Canvas automatically runs **drug–allergy** and **drug–drug** interaction screening and shows the results to the provider. When you originate or commit medication commands with the SDK — outside that interactive flow — this screening does **not** run automatically.
If you want the same safety net, you can opt in to running the checks yourself against the patient's allergy and medication lists using the ontologies screening endpoints, then act on the results before the command is committed:
Check| Helper  
---|---  
Drug–allergy| [Screening for drug–allergy interactions](/sdk/utils/#screening-for-drugallergy-interactions) (Ontologies)  
Drug–drug| [Screening for drug–drug interactions](/sdk/utils/#screening-for-drugdrug-interactions) (Ontologies)  
This is opt-in: only add it if your workflow charts medications programmatically and you want to reproduce the interaction warnings a provider would see in the UI.
##  Tips 
  - **Check the field description first.** Each command field in the [Commands reference](/sdk/commands/#commands) says whether it wants a code, an id, or an enum — and links to the data module or utils endpoint that supplies it.
  - **Match the UI's scoping.** If a field references something on the chart, query it `for_patient(...)` so you don't attach another patient's record.
  - **Handle "no match."** A search or query can come back empty. Decide what your plugin should do (skip the field, raise, or fall back) rather than passing a guess.
  - **Don't hard-code codes you can't verify.** Terminologies change; look values up so you stay in sync with what the chart would offer.

---

# How to add additional profile fields

Source: https://docs.canvasmedical.com/guides/profile-additional-fields/

This guide explains how to create additional fields that will appear on the patient profile demographics form. With this, you can define custom fields, and the information will be stored as patient metadata.
##  What you'll learn: 
  - Use the [`PatientMetadataCreateForm`](/sdk/patient-metadata-create-form-effect) effect to display additional fields on the patient profile.
  - Use the [`FormField`](/sdk/patient-metadata-create-form-effect/#formfield) class to create fields
##  Patient Metadata Create form plugin 
####  1\. FormField 
To create the form, we need to specify which items will be included. For this, we use the [`FormField`](/sdk/patient-metadata-create-form-effect/#formfield) class, where we can define our inputs and their attributes.
    ```python
    from canvas_sdk.effects.patient_metadata import InputType, FormField
    FormField(
        key='musicGenre',
        label='Preferred music genre',
        type=InputType.TEXT,
        required=False,
        editable=True,
    )
    ```
####  2\. PatientMetadataCreateFormEffect 
The next step is to add these fields to the effect so they can be used to build the form.
    ```python
    from canvas_sdk.effects.patient_metadata import PatientMetadataCreateFormEffect, InputType, FormField
    PatientMetadataCreateFormEffect(form_fields=[
        FormField(
            key='musicGenre',
            label='Preferred music genre',
            type=InputType.TEXT,
            required=False,
            editable=True,
        ),
        ...,
    ])
    ```
####  3\. The plugin 
Here's an example of a complete plugin showcasing the different input types.
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.patient_metadata import PatientMetadataCreateFormEffect, InputType, FormField
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    # Inherit from BaseHandler to properly get registered for events
    class Handler(BaseHandler):
        RESPONDS_TO = EventType.Name(EventType.PATIENT_METADATA__GET_ADDITIONAL_FIELDS)
        def compute(self) -> list[Effect]:
            form = PatientMetadataCreateFormEffect(form_fields=[
                FormField(
                    key='musicGenre',
                    label='Preferred music genre',
                    type=InputType.TEXT,
                    required=False,
                    editable=True,
                ),
                FormField(
                    key='occupation',
                    label='Occupation',
                    type=InputType.SELECT,
                    required=False,
                    editable=True,
                    options=["Engineer", "Teacher", "Other"]
                ),
                FormField(
                    key='date',
                    label='Date',
                    type=InputType.DATE,
                    required=False,
                    editable=True,
                ),
            ])
            return [form.apply()]
    ```
####  4\. The Output 
And that's it! Below, you can see how it will appear in the app — these fields will be stored as patient metadata.
![medication widget](/assets/images/additional-fields.png)

---

# Roles and Permissions

Source: https://docs.canvasmedical.com/guides/roles-and-permissions/

Access in Canvas is governed by role-based access control. This page explains how authorization is evaluated, describes the roles every instance is provisioned with, and outlines how to extend them for your organization.
##  How authorization works 
Canvas evaluates two independent levels of permission on every request.
**Model permissions** determine which record types a user may act on, and which actions are allowed on each: view, add, change, or delete. A user who lacks the view permission on a record type cannot read it anywhere in the application, including through the API.
**Object permissions** narrow that further to specific records. Object scope is expressed through **patient groups** : a user may hold a permission on a record type in general but only exercise it for patients within the groups assigned to them. This is how an organization restricts a clinician to a panel, a site, or a program rather than the whole patient population.
Both levels are always evaluated together. A user must satisfy the model permission and the object permission — and be an active user — for access to be granted.
> **Info:** Permissions are granted to roles, never directly to individuals. Adding or removing a user's access means changing their role assignments, which makes access reviews a question of who holds which role rather than an audit of per-user exceptions.
Some capabilities are gated by **named feature permissions** rather than by a record type — printing, revenue, data integration, campaigns, the questionnaire builder, patient activation, and prescription cancellation among them. These behave identically in evaluation; they simply gate a feature rather than a model.
##  Default roles 
Every Canvas instance is provisioned with the roles below. They are grouped here by what they are for; in the admin console they appear as a flat list.
###  Broad functional roles 
Role| Grants  
---|---  
Administrative| Organization and practice-location configuration, staff records, note types, letter and questionnaire templates, and revenue configuration  
Clinical| Clinical configuration and care-team management, lab and imaging report templates, protocol versions, and reporting  
###  Record access, split by read and write 
These are deliberately separate so that read access can be granted without write access.
Role| Grants  
---|---  
Clinical read| View clinical records — notes, patients, lab and imaging reports, prescriptions, referrals, messages, and related clinical documents  
Clinical write| Create and modify clinical records, including notes, plans, prescriptions, referrals, and reasons for visit  
Profile read| View patient demographics, contacts, identification cards, and payment methods  
Profile write| Modify patient demographics, coverage, consents, contacts, authorizations, and payment details  
Document Read| View patient administrative documents  
Document Write| Modify patient administrative documents  
###  Feature and workflow access 
Role| Grants  
---|---  
Patient Create| Create new patient records  
Schedule write| Create and modify appointments  
Tasking Access| View and update tasks  
Printing Access| Print from the chart  
Revenue access| The revenue module and authorization management  
Data integration Access| The data integration module  
Patient Data Integration Access| Patient-level data integration tasks  
Questionnaire Builder Access| The questionnaire builder  
###  Security-sensitive roles 
Treat these as privileged. They should be assigned narrowly and reviewed on a defined cadence.
Role| Grants  
---|---  
Staff Permissions Access| Manage roles, groups, staff permissions, and patient-group membership — in effect, the ability to grant access to others  
Emergency Access| Break-glass access, recorded against a dedicated emergency-access record  
Admin Lockout| View and clear failed-login lockouts  
Lead| Manage multi-factor authentication devices for users, including TOTP, email, and SMS  
> **Warning:** Staff Permissions Access is the role that can change other users' access, and Lead can manage their MFA devices. Both warrant the tightest assignment and the most frequent review of any role in the list.
Turning emergency access on or off requires the Emergency Access role.
Your instance may include additional roles introduced in later releases, or roles created by your own administrators.
##  Patient groups 
Patient groups appear alongside roles in the admin console but behave differently: they carry no model permissions of their own. Their purpose is object scoping — assigning a user to a patient group determines which patients their permissions apply to.
Every instance is provisioned with an **All Patients** group. Narrower groups are created per organization to reflect panels, sites, programs, or any other division that should bound a user's reach.
##  Extending the defaults 
The default roles are a starting point, not a fixed set. Administrators with Staff Permissions Access can create additional roles, and adjust the permissions on existing ones, to match how the organization actually works. Both are done through the admin console.
When you do, a few practices keep the model reviewable:
  - Prefer creating a **new role** over broadening an existing one, so the default set stays a recognizable baseline.
  - Grant **read and write separately** where the split exists, rather than defaulting to both.
  - Scope by **patient group** wherever a user does not legitimately need the full population.
  - Review assignments to the security-sensitive roles above on a defined cadence.
##  Reviewing access 
Because permissions are held by roles rather than individuals, an access review is a review of role membership. The admin console lists the staff assigned to each role and the patient groups scoping them.
Changes to roles, permissions, and staff records are captured in the audit trail — see [Audit Logging and Telemetry](/guides/audit-logging-and-telemetry/) for what is recorded and how to export it.
> **Info:** Canvas can provide a complete role-to-model permission matrix for your instance on request, for use in a security review or access-control audit. Contact your Canvas representative.
##  Related 
  - [Platform Security Overview](/guides/platform-security-overview/)
  - [Audit Logging and Telemetry](/guides/audit-logging-and-telemetry/)
  - [Plugin Security Model](/guides/plugin-security-model/)

---

# Creating, Implementing, and Extending an AI Scribe Parser

Source: https://docs.canvasmedical.com/guides/scribe-ai-parser/

The [AI Scribe Parser Plugin](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions/ai-scribe) was designed to help streamline clinical documentation by parsing structured transcripts into commands. With healthcare providers increasingly adopting AI-driven solutions, this guide provides developers with the insights and instructions needed to integrate and extend our example plugin to meet diverse documentation needs. In this guide, you'll learn how to:
  - Intercept [`CLIPBOARD_COMMAND__POST_INSERTED_INTO_NOTE`](/sdk/events/#clipboard-command).
  - Use `ScribeParser` (or custom parsers) to process transcripts.
  - Generate commands for each section.
  - Add or replace section parsers for custom sections.
  - Implement a fully custom parser for alternate formats.
##  Understanding the Transcript Parsing Flow. 
The workflow is triggered by pasting a transcript into a note. Doing so will automatically insert the content in the form of a clipboard command. We can then respond to that event and transform the content into the appropriate commands.
###  Input Transcript Example 
Our example transcript includes many structured sections. The sections listed below were flagged as being formatted in a way that makes them easy to translate into Canvas commands.
  - Chief complaint
  - History of present illness
  - Past medical history
  - Vitals
  - Plan
Each section contains specific information that can be parsed. For example:
  - The **Vitals** section includes data like weight, heart rate, and blood pressure, which can be converted into a `VitalsCommand`.
  - The **Assessment** section provides diagnoses and clinical impressions, which can be mapped to an `AssessCommand`.
**Complete Example**
    ```plaintext
    Chief complaint
    - Concern about potential diabetes
    - Hypertension
    History of present illness
    - Patient named Ken, age and gender not mentioned
    - Has sleep apnea, uses CPAP machine
    - Has hyperlipidemia
    - Has hypertension, on medication but doesn't remember the names
    - No other symptoms or issues reported
    - No shortness of breath or pain reported
    Past medical history
    - Sleep apnea
    - Hyperlipidemia
    - Hypertension
    Family history
    No known family history of hypertension
    Social history
    Travels a lot
    Current medications
    Medication for hypertension, names not provided
    Vitals
    - Weight: 244 lbs
    - Height: 5'10"
    - Heart rate: 80
    - Oxygen saturation: 94%
    - Blood pressure: 167/106
    Lab results
    A1C: 5.2 (Normal range, neither prediabetic nor diabetic)
    Physical exam
    CARDIOVASCULAR: Heart sounds good.
    LUNGS: Lungs sound good.
    Assessment
    - Hypertension, not well controlled
    - Sleep apnea, using CPAP machine
    - Hyperlipidemia
    - Elevated BMI, potential for weight loss intervention
    - No diabetes or prediabetes
    Plan
    - Recommendation for weight loss services
    - Recommendation to address hypertension, either at this clinic or with primary care
    - Potential adjustment of hypertension medication
    - Offered subscription program with unlimited office visits and access to a nutritionist
    - Potential telemedicine consultations due to patient's frequent travel
    Appointments
    No specific appointment made, patient to contact clinic after discussing with wife
    ICD-10 codes (3)
    - Sleep apnea, unspecified [G47.30]
    - Hyperlipidemia, unspecified [E78.5]
    - Essential (primary) hypertension [I10]
    ```
###  AI Scribe Plugin Architecture 
Once the content is pasted in, the plugin does the rest. Here's how.
####  1\. Handler Class 
The `Handler` class intercepts events and processes the transcript using a parser.
    ```python
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects import Effect
    from canvas_sdk.events import EventType
    class ScribeParser: ...  # explained in section 2 below, "ScribeParser"
    class Handler(BaseHandler):
        """A Plugin for interpreting transcripts."""
        RESPONDS_TO = EventType.Name(EventType.CLIPBOARD_COMMAND__POST_INSERTED_INTO_NOTE)
        def compute(self) -> list[Effect]:
            """Parse the transcript and generate effects to originate commands."""
            transcript = self.context["fields"]["text"]
            parser = ScribeParser()
            parsed_transcript = parser.parse(transcript, self.context)
            note_uuid = self.context["note"]["uuid"]
            effects = []
            for commands in parsed_transcript.values():
                for command in commands:
                    command.note_uuid = note_uuid
                    effects.append(command.originate(line_number=1))
            effects.reverse()
            return effects
    ```
####  2\. ScribeParser 
The `ScribeParser` delegates the parsing of each transcript section to specific section parsers.
    ```python
    from ai_scribe.parsers.base import TranscriptParser
    # explained in section 3 below, "Section Parsers"
    class ChiefComplaintParser: ...
    class HistoryOfPresentIllnessParser: ...
    class PastMedicalHistoryParser: ...
    class PlanParser: ...
    class VitalsParser: ...
    class ScribeParser(TranscriptParser):
        """A parser for scribe transcripts."""
        section_parsers = {
            "chief_complaint": ChiefComplaintParser(),
            "history_of_present_illness": HistoryOfPresentIllnessParser(),
            "past_medical_history": PastMedicalHistoryParser(),
            "vitals": VitalsParser(),
            "plan": PlanParser(),
        }
        def parse(self, transcript: str, context: dict) -> dict:
            """Parse the transcript into commands grouped by sections."""
            parsed_sections = {}
            for section, parser in self.section_parsers.items():
                parsed_sections[section] = parser.parse(transcript, context)
            return parsed_sections
    ```
####  3\. Section Parsers 
Each section parser extracts relevant information from its section and produces commands.
    ```python
    from typing import Any, Sequence
    from ai_scribe.parsers.base import CommandParser, ParsedContent
    from canvas_sdk.commands.commands.plan import PlanCommand
    class PlanParser(CommandParser):
        """Parses the plan section of a transcript."""
        def parse(self, content: ParsedContent, context: Any = None) -> Sequence[PlanCommand]:
            """Parses the plan section of a transcript."""
            return [PlanCommand(narrative=line) for line in content["arguments"]]
    ```
##  Extending the Parser 
###  1\. Adding a New Section Parser 
Suppose you want to parse the "Appointments" section into a `TaskCommand` for follow-up tasks.
####  Define the Parser 
    ```python
    from typing import Sequence, Any
    from canvas_sdk.commands import TaskCommand
    from ai_scribe.parsers.base import CommandParser, ParsedContent
    class AppointmentsParser(CommandParser):
        """Parses the 'Appointments' section of a transcript."""
        def parse(self, content: ParsedContent, context: Any = None) -> Sequence[TaskCommand]:
            """Parses the Appointments section and generates TaskCommands."""
            tasks = []
            for line in content["arguments"]:
                tasks.append(TaskCommand(title=line))
            return tasks
    ```
####  Register the Parser 
Add the `AppointmentsParser` to the `section_parsers` dictionary.
    ```python
    class AppointmentsParser: ... # defined above
    class ScribeParser:
        """A parser for transcripts."""
        section_parsers = {
            "appointments": AppointmentsParser()
        }
    ```
###  2\. Pre-filling a Questionnaire 
A section parser can also return a [Questionnaire](/sdk/commands/#questionnaire) command with its answers already filled in. Responses you record on the command, with `question.add_response(...)` or the `answers` parameter, go in with its `originate()` effect, so the handler above needs no change. This parser looks up a "Wound Assessment" questionnaire and answers each question from the transcript, matching questions by label:
    ```python
    from typing import Any, Sequence
    from ai_scribe.parsers.base import CommandParser, ParsedContent
    from canvas_sdk.commands.commands.questionnaire import QuestionnaireCommand
    from canvas_sdk.v1.data.questionnaire import Questionnaire
    class WoundAssessmentParser(CommandParser):
        """Parses the wound assessment section of a transcript."""
        def parse(
            self, content: ParsedContent, context: dict[str, Any] | None = None
        ) -> Sequence[QuestionnaireCommand]:
            """Parse the section and create a QuestionnaireCommand with populated responses."""
            wound_data = self.parse_wound_data(content.get("arguments", []))
            wound_questionnaire = Questionnaire.objects.get(name="Wound Assessment")
            questionnaire_command = QuestionnaireCommand(
                questionnaire_id=str(wound_questionnaire.id),
            )
            for question in questionnaire_command.questions:
                question.add_response(
                    text=str(wound_data.get(question.label.lower().replace(" ", "_"), ""))
                )
            # The handler sets note_uuid and originates the command, responses included.
            return [questionnaire_command]
        def parse_wound_data(self, lines: list) -> dict:
            wound_data = {}
            for line in lines:
                label, value = line.split(": ")
                label = label.strip("- ").lower().replace(" ", "_")
                wound_data[label] = value
            return wound_data
    ```
The keys `parse_wound_data` produces must match the questionnaire's labels after the same normalization: lowercase, with spaces as underscores. Register the parser in `section_parsers` the same way as above.
###  3\. Customizing the Entire Parser 
To replace `ScribeParser`, define your custom parser.
    ```python
    from ai_scribe.parsers.base import (
        ParsedContent,
        TranscriptParser,
        TranscriptParserOutput,
    )
    class CustomParser(TranscriptParser):
        """Custom parser for alternative transcript formats."""
        def parse(self, transcript: str, context: dict) -> dict:
            """Parse the transcript and produce commands."""
            # Implement custom parsing logic
            ...
    ```
Replace the parser in the `Handler` class:
    ```python
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.effects import Effect
    class CustomParser: ... # defined above
    class Handler(BaseHandler):
        """Handler using a custom parser."""
        def compute(self) -> list[Effect]:
            transcript = self.context["fields"]["text"]
            parser = CustomParser()  # Use custom parser
            parsed_transcript = parser.parse(transcript, self.context)
            note_uuid = self.context["note"]["uuid"]
            effects = []
            for commands in parsed_transcript.values():
                for command in commands:
                    command.note_uuid = note_uuid
                    effects.append(command.originate(line_number=1))
            effects.reverse()
            return effects
    ```
##  Watch the Workflow in Action 
##  Conclusion 
With robust parsing capabilities and extensibility, this example plugin equips developers to support clinicians in reclaiming their time for what matters most: patient care. By following the steps in this guide, developers can ensure seamless integration into clinical workflows, while also tailoring the tool to suit specific needs.

---

# How to set a default homepage for the provider application

Source: https://docs.canvasmedical.com/guides/set-default-homepage/

This guide explains how to set a default homepage for the provider application. By setting a default homepage, you can control which page users see when they first log in to the provider application, ensuring they have quick access to the most relevant information or features.
##  What you'll learn: 
  - Use the [`Application`](/sdk/data-application) model to get a specific application.
  - Use the [`DefaultHomepageEffect`](/sdk/default-homepage-effect) to set the default homepage.
##  Default homepage plugin 
####  1\. Set an application as the homepage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.default_homepage import DefaultHomepageEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from canvas_sdk.v1.data import Application
    class Homepage(BaseHandler):
        """Handler for homepage configuration events."""
        RESPONDS_TO = EventType.Name(EventType.GET_HOMEPAGE_CONFIGURATION)
        def compute(self) -> list[Effect]:
            """Set an application as the default homepage."""
            application = Application.objects.filter(name="custom_homepage").first()
            return [DefaultHomepageEffect(application_identifier=application.identifier).apply()]
    ```
####  2\. Set a specific page as the homepage 
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.default_homepage import DefaultHomepageEffect
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    class Homepage(BaseHandler):
        """Handler for homepage configuration events."""
        RESPONDS_TO = EventType.Name(EventType.GET_HOMEPAGE_CONFIGURATION)
        def compute(self) -> list[Effect]:
            """Set the Patients page as the default homepage."""
            return [DefaultHomepageEffect(page=DefaultHomepageEffect.Pages.PATIENTS).apply()]
    ```

---

# Staying on Top of Tasks

Source: https://docs.canvasmedical.com/guides/staying-on-top-of-tasks/

Many Canvas users work in multiple systems. If you have a system that deals with tasks that are ultimately completed in Canvas, you'll want to manage the full task lifecycle from that external system. Using Canvas' [FHIR API](/api/) and the [Canvas SDK](/sdk/), you can have your system create tasks in Canvas, and get notified when your users complete them.
![](/assets/images/guides/staying-on-top-of-tasks/flow.png)
##  Creating Tasks with the FHIR API 
Your system can originate Tasks in Canvas using our FHIR [Task Create endpoint](/api/task/#create). The id of the task you create can be found in the `location` response header. It comes back as the FHIR Task Read URL, but you can parse the id from it. See the example below. Remember, this code is hitting the Canvas API from _your_ system, not from within Canvas.
    ```python
    import requests
    import json
    payload = json.dumps({
      "resourceType": "Task",
      "status": "requested",
      "intent": "unknown",
      "description": "Send a thank you card to the office admin team.",
      "requester": {
        "reference": "Practitioner/abc123"
      }
    })
    url = "https://fumage-api-test-clinic.canvasmedical.com/Task"
    headers = {
      'Content-Type': 'application/json',
      'Authorization': 'not-a-real-token'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    # find the id of the task we just created
    task_location = response.headers['location']  # http://fumage-api-test-clinic.canvasmedical.com/Task/b6426693-eb5b-4702-9f90-4728972c7f16
    task_id = task_location.split("/Task/")[1]  # b6426693-eb5b-4702-9f90-4728972c7f16
    ```
You can then take that task id and persist it in your application for tracking its status. While some choose to poll for status changes, a better way to keep track of the state of a task is by creating a webhook. We can do that with the Canvas SDK.
##  Creating a Task completion webhook with the Canvas SDK 
> **Info:** Webhook plugins are discussed in more detail in [Creating Webhooks with the Canvas SDK](/guides/creating-webhooks-with-the-canvas-sdk/).
Implementing webhooks in a plugin gives you ultimate control over the payload and headers in your request. We use the python [requests](https://requests.readthedocs.io/en/latest/) library under the hood, so there's an extremely good chance anything you require for your request is supported.
In this example, we listen for either the `TASK_COMPLETED` or the `TASK_CLOSED` events, and send an HTTP POST with the id of the task that was either completed or closed, along with whether it was completed or closed. The target of the event is the id of the task, so the event comes with all the information we need here. You can substitute any of the Canvas SDK's supported [events](/sdk/events/) to extend this example to other record types.
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.utils import Http
    from logger import log
    class TaskResolutionWebhook(BaseHandler):
        RESPONDS_TO = [
            EventType.Name(EventType.TASK_COMPLETED),
            EventType.Name(EventType.TASK_CLOSED),
        ]
        def compute(self):
            task_disposition = 'closed'
            if self.event.type == EventType.TASK_COMPLETED:
                task_disposition = 'completed'
            url = "https://webhook.site/ee7aed78-b652-4d9e-b858-04465c409d15"
            payload = {
                "task_id": self.target,
                "disposition": task_disposition,
            }
            http = Http()
            response = http.post(url, json=payload)
            if response.ok:
                log.info("Successfully notified API of task update!")
            else:
                log.info("Notification unsuccessful. =[")
            return []
    ```
Once installed, the url you specified in the code will receive an HTTP POST request whenever a user marks a task as completed or closed. Your application can listen for those requests and update your internal status of that task.

---

# Submit a Full Vital Panel through Canvas FHIR API

Source: https://docs.canvasmedical.com/guides/submit-vitals-via-fhir/

Inside of the Canvas' [Vital Command](https://canvas-medical.help.usepylon.com/articles/9426091672-command-vitals) there are many vital signs supported to document.
![Protocol framework](/assets/images/vitals/vital-empty.png)
The Canvas [FHIR Observation Create](/api/observation/#create) endpoint supports writing some of the vital signs in the command. This guide will show you all the vitals that can be documented in the Create interaction.
* * *
##  What you'll learn 
In this guide, you will learn how to do the following:
  1. Create a vital panel via FHIR
  2. Submit various vital signs into the same panel via FHIR
  3. Perform a FHIR Observation Search to view the completed panel
* * *
###  1\. Setup and Authentication 
This guide will demonstrate many FHIR API calls into Canvas. Before we can make a FHIR request, we need to setup some imports, reusable variables, and authenticate into the instance we want to work with.
Here is your starting point:
    ```python
    import requests
    url = "https://fumage-example.canvasmedical.com/Observation"
    headers = {
        "accept": "application/json",
        "Authorization": "Bearer <token>",
        "content-type": "application/json"
    }
    ```
But there are two places above to update:
  1. The `url` will show `https://fumage-example.canvasmedical.com/Observation`. You will need to replace `example` with the name of the Canvas instance you are using.
  2. One of the `header` elements will be `'Authorization': 'Bearer <token>'`. You will need to create this `<token>` following our steps laid out in [Customer Authentication](/api/customer-authentication)
###  2\. Understanding our Observation Payload 
Before we start creating the vital panel and the associated vital signs, take some time to familiarize yourself with the [FHIR Observation Create](/api/observation/#create) endpoint. Each payload to create an observation requires `status`, `code`, and `subject`.
In this guide the `status` will always be `final` and the `subject` will always appear as:   
`"subject": { "reference": "Patient/$patient_id" }`.  
When completing these steps yourself, you will want to change the `{patient_id}` to match a patient in the instance you are using (e.g `"Patient/ee8672f3497e4a83937b9e71d0a704a5"`).
The `code` attribute is the real magic that tells Canvas which vital you are creating. The coding will always be a LOINC code.
Another thing to note is an optional `effectiveDateTime` attribute. This allows you to specify the time the vital was taken. But if omitted, it will default to the time of creation.
###  3\. Create a Vital Panel 
First we will need to create the panel object to be able to save all the individual vital signs to. The important attribute is the `code.coding[0][code]` being `85353-1` to represent a vital panel.
Here is the payload for how to create a Vital Panel (remember to set the patient_id and also update the effectiveDateTime):
    ```python
    import requests
    url = "https://fumage-example.canvasmedical.com/Observation"
    headers = {
        "accept": "application/json",
        "Authorization": "Bearer <token>",
        "content-type": "application/json"
    }
    patient_id = "<a patient ID from your instance>"
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "85353-1",
                    "display": "Vital Panel"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
On a successful create, when the `response.status_code` equal 201. We can fetch the ID of the newly created observation in the `response.headers['location']` attribute. The value will always be in the format `{url}/{id}/_history/1`. We need to extract the `id` from the value.
However, if the request failed it will throw an error to see what went wrong. It will also display the Correlation ID that can be given to Customer Support for help with further debugging.
    ```python
    if response.status_code == 201:
        panel_id = response.headers['location'].replace(f"{url.replace('https', 'http')}/", '').replace('/_history/1', '')
    else:
        raise Exception(f"Failed to perform {response.url}. \n Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be a Data Import note placed on that patient's timeline based on the date passed in the `effectiveDateTime` attribute with an empty Vitals Command:
![Protocol framework](/assets/images/vitals/vital-panel-in-import-note.png)
###  4\. Creating Individual Vital Signs 
Now that we have created a Vital Panel, we will be able to use this panel_id when creating the individual vital signs to be associated with the same command by passing the `derivedFrom` attribute in the payload:
    ```python
    payload = {
        # ...
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ],
        # ...
    }
    ```
Now we are ready to create the following vital signs in the panel that are supported via FHIR Observation Create:
  - Height
  - Weight
  - Waist Circumference
  - Body Temperature
  - Blood Pressure
  - Pulse Rhythm
  - Pulse Rate
  - Respiration Rate
  - Oxygen Saturation
  - Notes
####  Add Height 
Height is denoted by the LOINC code `8302-2`. Since its value is numeric, we will be able to pass the value and units through the `valueQuantity` attribute. By default if no `valueQuantity.unit` is specified, it will default to using inches, but `cm` is also supported, it will just convert it to inches on the UI and when a Read/Search is performed.
Here is a payload to create a height of 69.0 inches:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "8302-2",
                    "display": "Height"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueQuantity": {
            "value": 69.0,
            "unit": "in",
        },
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Height observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be height of `69.0 in` added in that Vitals Command:
![Protocol framework](/assets/images/vitals/height.png)
####  Add Weight 
Weight is denoted by the LOINC code `29463-7`. Since its value is numeric, we will be able to pass the value and units through the `valueQuantity` attribute. By default if no `valueQuantity.unit` is specified, it will default to using ounces, but `lb` or `kg` is also supported, it will just convert it to `oz` when a Read/Search is performed. The UI will display it in `lbs` and leftover `oz`.
Here is a payload to create a weight of 176.4 lbs:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "29463-7",
                    "display": "Weight"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueQuantity": {
            "value": 176.4,
            "unit": "lb",
        },
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Weight observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be weight of `176 lbs 6.4 oz` added in that Vitals Command:
![Protocol framework](/assets/images/vitals/weight.png)
####  Add Waist Circumference 
Waist Circumference is denoted by the LOINC code `29463-7`. Since its value is numeric, we will be able to pass the value and units through the `valueQuantity` attribute. By default if no `valueQuantity.unit` is specified, it will default to using centimeters, but `in` is also supported, it will just convert it to `cm` on the UI or when a Read/Search is performed.
Here is a payload to create a waist circumference of `98.2 cm`:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "56086-2",
                    "display": "Waist Circumference"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueQuantity": {
            "value": 98.2,
            "unit": "cm",
        },
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Waist Circumference observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be waist circumference of `98.2 cm` added in that Vitals Command:
![Protocol framework](/assets/images/vitals/waist-circumference.png)
####  Add Body Temperature 
Body Temperature is denoted by the LOINC code `8310-5`. Since its value is numeric, we will be able to pass the value and units through the `valueQuantity` attribute. The only unit accepted for body temperature is `°F` and if omitted it will be default.
Here is a payload to create a temperature of `98.4 °F`:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "8310-5",
                    "display": "Body Temperature"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueQuantity": {
            "value": 98.4,
            "unit": "°F",
        },
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Body Temperature observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be temperature of `98.4 °F` added in that Vitals Command:
![Protocol framework](/assets/images/vitals/body-temperature.png)
####  Add Blood Pressure 
Blood Pressure is denoted by the LOINC code `85354-9`. In the Vital's command blood pressure is a string value that combines the systolic and diastolic components with a `/`. So the payload will pass the `valueString` component in order for the blood pressure to appear correctly in the Vitals Command.
Since blood pressure is made up of two values, the payload will also define a `component` attribute list to pass the systolic (LOINC code `8480-6`) and diastolic (LOINC code `8462-4`) values. These two values are numeric, so they will have the `valueQuantity` attributes where the unit will be `mmHg`
Here is a payload to create a Blood Pressure of `122/68`:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "85354-9",
                    "display": "Blood Pressure"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueString": "122/68",
        "component": [
            {
                "code": {
                    "coding": [
                        {
                            "system": "http://loinc.org",
                            "code": "8480-6",
                            "display": "Systolic blood pressure"
                        }
                    ]
                },
                "valueQuantity": {
                    "value": 122,
                    "unit": "mmHg"
                }
            },
            {
                "code": {
                    "coding": [
                        {
                            "system": "http://loinc.org",
                            "code": "8462-4",
                            "display": "Diastolic blood pressure"
                        }
                    ]
                },
                "valueQuantity": {
                    "value": 68,
                    "unit": "mmHg"
                }
            }
        ],
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Blood Pressure observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be blood pressure of `122/68` added in that Vitals Command:
![Protocol framework](/assets/images/vitals/blood-pressure.png)
####  Add Pulse Rate 
Pulse Rate is denoted by the LOINC code `8867-4`. Since its value is numeric, we will be able to pass the value and units through the `valueQuantity` attribute. The only unit accepted for pulse rate is `bpm` and if omitted it will be default.
Here is a payload to create a pulse rate of `115 bpm`:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "8867-4",
                    "display": "Pulse"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueQuantity": {
            "value": 115,
            "unit": "bpm",
        },
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Pulse Rate observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be pulse rate of `115 bpm` added in that Vitals Command:
![Protocol framework](/assets/images/vitals/pulse-rate.png)
####  Add Pulse Rhythm 
Pulse Rhythm is denoted by the LOINC code `8884-9`. Canvas accepts only three different string values for pulse rhythm: `Regular`, `Irregularly Irregular`, or `Regulary Irregular`. This value will be passed in the `valueString` attribute.
Here is a payload to create a pulse rhythm of `Regular`:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "8884-9",
                    "display": "Pulse Rhythm"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueString": "Regular",
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Pulse rhythm observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be pulse rhythm of `Regular` added in that Vitals Command:
![Protocol framework](/assets/images/vitals/pulse-rhythm.png)
####  Add Respiration Rate 
Respiration Rate is denoted by the LOINC code `9279-1`. Since its value is numeric, we will be able to pass the value and units through the `valueQuantity` attribute. The only unit accepted for respiration rate is `bpm` and if omitted it will be default.
Here is a payload to create a respiration rate of `15 bpm`:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "9279-1",
                    "display": "Respiration Rate"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueQuantity": {
            "value": 15,
            "unit": "bpm",
        },
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Respiration Rate observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be respiration rate of `15 bpm` added in that Vitals Command:
![Protocol framework](/assets/images/vitals/respiration-rate.png)
####  Add Oxygen Saturation 
Oxygen Saturation is denoted by either LOINC code `2708-6` or `59408-5`. Canvas saves the oxygen saturation with both codings. Since its value is numeric, we will be able to pass the value and units through the `valueQuantity` attribute. The only unit accepted for Oxygen Saturation is `%` and if omitted it will be default.
Here is a payload to create a Oxygen Saturation of `98%`:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "2708-6",
                    "display": "Oxygen Saturation Arterial"
                },
                {
                    "system": "http://loinc.org",
                    "code": "59408-5",
                    "display": "Oxygen Saturation"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueQuantity": {
            "value": 98,
            "unit": "%",
        },
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Oxygen Saturation observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now be Oxygen Saturation of `98%` added in that Vitals Command:
![Protocol framework](/assets/images/vitals/oxygen-saturation.png)
####  Add Notes 
Adding a Note is denoted by the LOINC code `80339-5`. Since this value is free text, a `valueString` attribute can be used.
Here is a payload to create an internal Note:
    ```python
    payload = {
        "resourceType": "Observation",
        "status": "final",
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "80339-5",
                    "display": "Note"
                }
            ]
        },
        "subject": {
            "reference": f"Patient/{patient_id}"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "valueString": "Last Blood sugar was 78",
        "derivedFrom": [
            {
                "reference": f"Observation/{panel_id}",
                "type": "Observation"
            }
        ]
    }
    response = requests.post(url, json=payload, headers=headers)
    if response.status_code == 201:
        print(f"Oxygen Saturation observation id = {response.headers['location'].replace(f'{url}/', '').replace('/_history/1', '')}")
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
Looking in the Canvas UI, there will now will be a Note added in that Vitals Command:
![Protocol framework](/assets/images/vitals/note.png)
###  5\. Perform FHIR Observation Read and Search 
A full Vital Panel has been completed! Let's now perform a FHIR Observation Read using the `panel_id` to see all the observation members of this panel now:
    ```python
    from pprint import pprint
    response = requests.get(f"{url}/{panel_id}", headers=headers)
    if response.status_code == 200:
        pprint(response.json())
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
The output will look like:
    ```json
    {
        "resourceType": "Observation",
        "id": "64ef9722-87c9-4b51-96d5-5812f15654d2",
        "status": "final",
        "category": [
            {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                        "code": "vital-signs",
                        "display": "Vital Signs"
                    }
                ]
            }
        ],
        "code": {
            "coding": [
                {
                    "system": "http://loinc.org",
                    "code": "85353-1",
                    "display": "Vital Signs Panel"
                }
            ]
        },
        "subject": {
            "reference": "Patient/b23295011ddf4df799976866c84d79d3",
            "type": "Patient"
        },
        "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
        "issued": "2024-04-19T18:13:03.574074+00:00",
        "dataAbsentReason": {
            "coding": [
                {
                    "system": "http://terminology.hl7.org/CodeSystem/data-absent-reason",
                    "code": "not-performed",
                    "display": "Not Performed"
                }
            ]
        },
        "hasMember": [
            {
                "reference": "Observation/a21ee97f-dd35-4266-afaf-3e1b0a537668",
                "type": "Observation",
                "display": "Height"
            },
            {
                "reference": "Observation/c9898fa2-e78e-48b0-8c7b-7ab8c99f0d30",
                "type": "Observation",
                "display": "Weight"
            },
            {
                "reference": "Observation/a70a2979-d820-42e4-a0c6-cdbd80d7468f",
                "type": "Observation",
                "display": "Waist Circumference"
            },
            {
                "reference": "Observation/794c1f41-a564-4f4c-b56e-6ab5ee40ad0e",
                "type": "Observation",
                "display": "Body Temperature"
            },
            {
                "reference": "Observation/4fe8ba77-14aa-4d4a-b7eb-eaa0020a741f",
                "type": "Observation",
                "display": "Blood Pressure"
            },
            {
                "reference": "Observation/8a7c9a2b-3b06-4ede-bb98-620788cf2071",
                "type": "Observation",
                "display": "Pulse"
            },
            {
                "reference": "Observation/53a6e624-d7a6-4eef-8e05-9d98c889d820",
                "type": "Observation",
                "display": "Pulse Rhythm"
            },
            {
                "reference": "Observation/3ef9d6d0-68db-46ce-b30d-ca7081da14b7",
                "type": "Observation",
                "display": "Respiration Rate"
            },
            {
                "reference": "Observation/e08993a5-1d62-4bb2-ae00-c30bcd8e66bf",
                "type": "Observation",
                "display": "Oxygen Saturation Arterial"
            },
            {
                "reference": "Observation/49c4871d-ce6c-4281-86aa-27a8dd03ccf8",
                "type": "Observation",
                "display": "Note"
            }
        ]
    }
    ```
And finally let's perform a FHIR Observation Search to see all the vital signs that are for that patient using the derived from search parameter:
    ```python
    from pprint import pprint
    response = requests.get(f"{url}?patient=Patient/{patient_id}&category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs&derived-from=Observation/{panel_id}&_count=20", headers=headers)
    if response.status_code == 200:
        pprint(response.json())
    else:
        raise Exception(f"Failed to perform {response.url}. \n Fumage Correlation ID: {response.headers['fumage-correlation-id']} \n {response.text}")
    ```
The response will look like:
    ```json
    {
        "resourceType": "Bundle",
        "type": "searchset",
        "total": 10,
        "link": [
            {
                "relation": "self",
                "url": "/Observation?category=vital-signs&derived-from=Observation%2F64ef9722-87c9-4b51-96d5-5812f15654d2&patient=Patient%2Fb23295011ddf4df799976866c84d79d3&_count=50&_offset=0"
            },
            {
                "relation": "first",
                "url": "/Observation?category=vital-signs&derived-from=Observation%2F64ef9722-87c9-4b51-96d5-5812f15654d2&patient=Patient%2Fb23295011ddf4df799976866c84d79d3&_count=50&_offset=0"
            },
            {
                "relation": "last",
                "url": "/Observation?category=vital-signs&derived-from=Observation%2F64ef9722-87c9-4b51-96d5-5812f15654d2&patient=Patient%2Fb23295011ddf4df799976866c84d79d3&_count=50&_offset=0"
            }
        ],
        "entry": [
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "a21ee97f-dd35-4266-afaf-3e1b0a537668",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "8302-2",
                                "display": "Height"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:04.487846+00:00",
                    "valueQuantity": {
                        "value": 69.0,
                        "unit": "in",
                        "system": "http://unitsofmeasure.org",
                        "code": "[in_i]"
                    },
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "c9898fa2-e78e-48b0-8c7b-7ab8c99f0d30",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "29463-7",
                                "display": "Weight"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:05.094527+00:00",
                    "valueQuantity": {
                        "value": 176.4,
                        "unit": "lb",
                        "system": "http://unitsofmeasure.org",
                        "code": "[lb_av]"
                    },
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "a70a2979-d820-42e4-a0c6-cdbd80d7468f",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "56086-2",
                                "display": "Waist Circumference"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:05.741607+00:00",
                    "valueQuantity": {
                        "value": 98.2,
                        "unit": "cm",
                        "system": "http://unitsofmeasure.org",
                        "code": "cm"
                    },
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "794c1f41-a564-4f4c-b56e-6ab5ee40ad0e",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "8310-5",
                                "display": "Body Temperature"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:06.216429+00:00",
                    "valueQuantity": {
                        "value": 98.4,
                        "unit": "°F",
                        "system": "http://unitsofmeasure.org",
                        "code": "[degF]"
                    },
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "4fe8ba77-14aa-4d4a-b7eb-eaa0020a741f",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "85354-9",
                                "display": "Blood Pressure"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:06.801703+00:00",
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ],
                    "component": [
                        {
                            "code": {
                                "coding": [
                                    {
                                        "system": "http://loinc.org",
                                        "code": "8480-6",
                                        "display": "Systolic blood pressure"
                                    }
                                ]
                            },
                            "valueQuantity": {
                                "value": 122.0,
                                "unit": "mmHg",
                                "system": "http://unitsofmeasure.org",
                                "code": "mm[Hg]"
                            }
                        },
                        {
                            "code": {
                                "coding": [
                                    {
                                        "system": "http://loinc.org",
                                        "code": "8462-4",
                                        "display": "Diastolic blood pressure"
                                    }
                                ]
                            },
                            "valueQuantity": {
                                "value": 68.0,
                                "unit": "mmHg",
                                "system": "http://unitsofmeasure.org",
                                "code": "mm[Hg]"
                            }
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "8a7c9a2b-3b06-4ede-bb98-620788cf2071",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "8867-4",
                                "display": "Pulse"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:07.375137+00:00",
                    "valueQuantity": {
                        "value": 115.0,
                        "unit": "bpm",
                        "system": "http://unitsofmeasure.org",
                        "code": "/min"
                    },
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "53a6e624-d7a6-4eef-8e05-9d98c889d820",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "8884-9",
                                "display": "Pulse Rhythm"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:07.860791+00:00",
                    "valueString": "Regular",
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "3ef9d6d0-68db-46ce-b30d-ca7081da14b7",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "9279-1",
                                "display": "Respiration Rate"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:08.331239+00:00",
                    "valueQuantity": {
                        "value": 15.0,
                        "unit": "bpm",
                        "system": "http://unitsofmeasure.org",
                        "code": "/min"
                    },
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "e08993a5-1d62-4bb2-ae00-c30bcd8e66bf",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "2708-6",
                                "display": "Oxygen Saturation Arterial"
                            },
                            {
                                "system": "http://loinc.org",
                                "code": "59408-5",
                                "display": "Oxygen Saturation"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:08.847291+00:00",
                    "valueQuantity": {
                        "value": 98.0,
                        "unit": "%",
                        "system": "http://unitsofmeasure.org",
                        "code": "%"
                    },
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ]
                }
            },
            {
                "resource": {
                    "resourceType": "Observation",
                    "id": "49c4871d-ce6c-4281-86aa-27a8dd03ccf8",
                    "status": "final",
                    "category": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                                    "code": "vital-signs",
                                    "display": "Vital Signs"
                                }
                            ]
                        }
                    ],
                    "code": {
                        "coding": [
                            {
                                "system": "http://loinc.org",
                                "code": "80339-5",
                                "display": "Note"
                            }
                        ]
                    },
                    "subject": {
                        "reference": "Patient/b23295011ddf4df799976866c84d79d3",
                        "type": "Patient"
                    },
                    "effectiveDateTime": "2024-03-29T08:50:24.883809+00:00",
                    "issued": "2024-04-19T18:13:09.336889+00:00",
                    "valueString": "Last Blood sugar was 78",
                    "derivedFrom": [
                        {
                            "reference": "Observation/64ef9722-87c9-4b51-96d5-5812f15654d2",
                            "type": "Observation"
                        }
                    ]
                }
            }
        ]
    }
    ```

---

# Tailoring the Chart to the Patient

Source: https://docs.canvasmedical.com/guides/tailoring-the-chart-to-the-patient/

Different patients have different needs, and your tools should reflect that. EMRs are able to be used in a wide variety of scenarios. In order to be able to do just about anything, your EMR is packed to the gills with features and options. While you might need all of these features for all of your patients, you almost certainly don't need _every_ feature for _each_ of your patients.
This guide shows a few examples of using a patient's data to customize their chart so the EMR features most relevant to them are front-and-center, while minimizing or hiding what you don't need in the moment. Tailoring the interface based on the patient in front of you creates a focused environment for you to deliver care without irrelevant options getting between you and your patient.
> **Info:** This guide assumes pre-existing knowledge of the Canvas SDK. If you're starting from scratch, you may want to read and implement [Your First Plugin (with Claude Code)](/guides/your-first-plugin-with-claude-code/) before working through this exercise.
##  Chart Customizations for Pediatric Patients 
We will make two simple changes to the charting interface when the selected patient is a child:
  1. Move the Immunization list to the top of the patient summary
  2. Prevent adult-only diagnosis choices from appearing in searches
First, we'll need to initialize a new plugin.
The Canvas CLI gives you a great head start when creating a plugin. Run `canvas init`, and answer the prompt to name your plugin.
    ```sh
    $ canvas init
      [1/1] project_name (My Cool Plugin): Pediatric Patient Chart Customizations
    Project created in /Users/andrew/src/canvas-plugins/pediatric-patient-chart-customizations
    Registered acme__pediatric_patient_chart_customizations with Canvas Platform.
    ```
This output shows the location of our freshly generated plugin project. If you're signed in to Canvas Platform with [`canvas login`](/sdk/canvas_cli/#signing-in-to-canvas-platform), `canvas init` names the package with your organization's prefix, such as `acme__pediatric_patient_chart_customizations`, and registers it with Canvas Platform. It also makes the project folder a git repository that [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy) pushes to.
In the package directory, you'll see a default class (`acme__pediatric_patient_chart_customizations/handlers/event_handlers.py`) provided as a starting point for your code.
    ```sh
    $ tree acme__pediatric_patient_chart_customizations/
    acme__pediatric_patient_chart_customizations/
    ├── CANVAS_MANIFEST.json
    ├── README.md
    └── handlers
        ├── __init__.py
        └── event_handlers.py
    2 directories, 4 files
    ```
You can use this file as a starting point, or you can start fresh with a new file. At minimum, I recommend renaming `event_handlers.py` to something more descriptive, and you'll need to update the references to the file in `CANVAS_MANIFEST.json` as well.
###  Move Immunizations to the Top of the Patient Summary 
I've created a new file, `handlers/pediatric_chart_layout.py`, and I've updated my `CANVAS_MANIFEST.json` to reflect it.
    ```sh
    $ tree acme__pediatric_patient_chart_customizations/
    acme__pediatric_patient_chart_customizations/
    ├── CANVAS_MANIFEST.json
    ├── README.md
    └── handlers
        ├── __init__.py
        └── pediatric_chart_layout.py
    2 directories, 4 files
    ```
Here is a pretty empty class with some comments that will guide our development:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    class PediatricChartLayout(BaseHandler):
        """
        This event handler rearranges the patient summary section to focus on the
        parts most relevant to pediatric patients when it detects that the patient
        for the current chart is <= 17 years old.
        """
        # This event fires when a patient chart's summary section is loading.
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION)
        def compute(self):
            """
            Check to see if the patient is <= 17 years old. If so, move their
            immunization list to the top of the patient summary.
            """
            # Look up the patient whose chart is being loaded right now
            # See if the patient is younger than 18 years old
            # If they are not younger than 18, do nothing
            # If they are younger than 18, re-arrange the layout of their summary
            # sections to put immunizations at the top.
            # BaseHandler subclasses must return a list, but it can be empty. It
            # is empty here since we aren't doing anything just yet.
            return []
    ```
Pretty straightforward logic. Do nothing or do something based on their age.
####  Looking Up the Patient 
In order to determine if we are on a pediatric chart, we'll need to know the patient and their birth date. We can use the [Patient class](/sdk/data-patient/) in the [Data Module](/sdk/data/) for this.
The `PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION` event is accompanied by the id of the patient whose chart is being loaded. You can find it using `self.target`. The patient is the target of the event.
    ```python
    import arrow
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.v1.data.patient import Patient
    class PediatricChartLayout(BaseHandler):
        """
        This event handler rearranges the patient summary section to focus on the
        parts most relevant to pediatric patients when it detects that the patient
        for the current chart is <= 17 years old.
        """
        # This event fires when a patient chart's summary section is loading.
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION)
        def compute(self):
            """
            Check to see if the patient is <= 17 years old. If so, move their
            immunization list to the top of the patient summary.
            """
            eighteen_years_ago = arrow.now().shift(years=-18).date().isoformat()
            patient_is_pediatric = Patient.objects.filter(
                id=self.target, birth_date__gt=eighteen_years_ago).exists()
            # If the patient is not pediatric, do not alter the layout.
            if not patient_is_pediatric:
                return []
            # TODO: Alter the layout
            return []
    ```
In the code above, you'll see I didn't actually retrieve the patient's information. Since I don't plan to use any of the data from the patient record, I instead let the database answer the question: "Does the patient with this id have a birth date more recent than 18 years ago?" This is a performance optimization. The less data transmitted, the faster your plugins execute, and the faster your charts load. This is not strictly necessary, but over time and with enough plugins installed the inefficiencies could add up. If you'd like you could alternately retrieve the patient and make a direct comparison to their `birth_date` attribute.
####  Altering the Layout 
When loading the patient's summary, the front-end consults a list of sections to retrieve data for and render. Our plugin influences this list, and it does so using the [`PatientChartSummaryConfiguration`](https://github.com/canvas-medical/canvas-plugins/blob/main/canvas_sdk/effects/patient_chart_summary_configuration.py) effect. Using the list of possible sections, we construct the ordered list of sections we want to see. In this example we're just moving one to the top, but you could also omit sections to hide them entirely if there are sections you do not use or need for your [Care Model](https://www.canvasmedical.com/articles/care-modeling-the-secret-to-success-in-care-delivery).
    ```python
    import arrow
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    from canvas_sdk.effects.patient_chart_summary_configuration import PatientChartSummaryConfiguration
    from canvas_sdk.v1.data.patient import Patient
    class PediatricChartLayout(BaseHandler):
        """
        This event handler rearranges the patient summary section to focus on the
        parts most relevant to pediatric patients when it detects that the patient
        for the current chart is <= 17 years old.
        """
        # This event fires when a patient chart's summary section is loading.
        RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION)
        def compute(self):
            """
            Check to see if the patient is <= 17 years old. If so, move their
            immunization list to the top of the patient summary.
            """
            eighteen_years_ago = arrow.now().shift(years=-18).date().isoformat()
            patient_is_pediatric = Patient.objects.filter(
                id=self.target, birth_date__gt=eighteen_years_ago).exists()
            # If the patient is not pediatric, do not alter the layout.
            if not patient_is_pediatric:
                return []
            layout = PatientChartSummaryConfiguration(sections=[
              PatientChartSummaryConfiguration.Section.IMMUNIZATIONS,
              PatientChartSummaryConfiguration.Section.SOCIAL_DETERMINANTS,
              PatientChartSummaryConfiguration.Section.GOALS,
              PatientChartSummaryConfiguration.Section.CONDITIONS,
              PatientChartSummaryConfiguration.Section.MEDICATIONS,
              PatientChartSummaryConfiguration.Section.ALLERGIES,
              PatientChartSummaryConfiguration.Section.CARE_TEAMS,
              PatientChartSummaryConfiguration.Section.VITALS,
              PatientChartSummaryConfiguration.Section.SURGICAL_HISTORY,
              PatientChartSummaryConfiguration.Section.FAMILY_HISTORY,
            ])
            return [layout.apply()]
    ```
Once you deploy the plugin with [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy), pediatric patients will have their immunization section at the top of their summary. Adult patients will continue to have social determinants as their initial section.
###  Prevent adult-only diagnosis choices from appearing in searches 
Some diagnosis codes are restricted to adult patients. CMS provides a [list](https://www.cms.gov/Medicare/Coding/OutpatientCodeEdit/Downloads/ICD-10-IOCE-Code-Lists.pdf) of these "Adult Diagnoses". We can reference this list and filter them out of the diagnosis search results for pediatric patients. This increases the quality of your search and makes it easier for you to find the right choice.
I've created a new file, `handlers/pediatric_condition_search.py`, and I've updated my `CANVAS_MANIFEST.json` to reflect it.
Here's the updated plugin file structure:
    ```sh
    $ tree acme__pediatric_patient_chart_customizations/
    acme__pediatric_patient_chart_customizations/
    ├── CANVAS_MANIFEST.json
    ├── README.md
    └── handlers
        ├── __init__.py
        ├── pediatric_chart_layout.py
        └── pediatric_condition_search.py
    2 directories, 5 files
    ```
And here's the updated `CANVAS_MANIFEST.json`:
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "acme__pediatric_patient_chart_customizations",
        "description": "Customizations for pediatric patients",
        "components": {
            "handlers": [
                {
                    "class": "acme__pediatric_patient_chart_customizations.handlers.pediatric_chart_layout:PediatricChartLayout",
                    "description": "Moves the immunization section to the top of the patient summary on pediatric charts.",
                    "data_access": {
                        "event": "",
                        "read": [],
                        "write": []
                    }
                },
                {
                    "class": "acme__pediatric_patient_chart_customizations.handlers.pediatric_condition_search:PediatricConditionSearch",
                    "description": "Filters the condition search to eliminate adult-only conditions on pediatric charts.",
                    "data_access": {
                        "event": "",
                        "read": [],
                        "write": []
                    }
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
And here's the very basic outline we'll start out with:
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    ADULT_ONLY_ICD_CODES = {
        # There are many, many more. Limiting this example for brevity.
        # ...
        "Z561",   # Change of job
        "Z5682",  # Military deployment status
        # ...
    }
    class PediatricConditionSearch(BaseHandler):
        """
        Filter condition searches for pediatric patients.
        """
        RESPONDS_TO = [
            EventType.Name(EventType.DIAGNOSE__DIAGNOSE__POST_SEARCH),
            EventType.Name(EventType.MEDICAL_HISTORY__PAST_MEDICAL_HISTORY__POST_SEARCH),
        ]
        def compute(self):
            """
            Remove condition search results representing codings that are resevered
            for adults if the patient is <= 15 years old.
            """
            # This event's target is the command we are searching within. Look up
            # the patient id from the command, and use that to look up the patient.
            # If the patient is not pediatric, do not alter the search.
            # If the patient is pediatric, loop through the search results, and
            # compare the codings of the options with our list of adult-only
            # diagnosis codes. If it's an adult only code, remove it from the
            # list.
            return []
    ```
Using the list provided by CMS, we can create a set of ICD-10 codes that should be restricted to adults. According to CMS, these diagnoses are only relevant to patients 15 or older.
While the layout altering class responded to a single event, we're listening for two different events here: diagnose command search and past medical history command search. Both of these commands include a diagnosis code search box, so we'll want to affect both. We wouldn't want to impact a family history command diagnosis search, since the family members recorded there are often adults.
####  Looking Up the Patient 
In the previous example, the target of the `PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION` event was the patient. For the events we're responding to here, the target is the [command](/sdk/data-command/) that the search is occurring within. In order to determine if the patient is young enough for our code to be invoked, we'll first look up the patient's id from the command, then assess their age in a similar manner as before.
    ```python
    import arrow
    from canvas_sdk.v1.data.command import Command
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    ADULT_ONLY_ICD_CODES = {
        # There are many, many more. Limiting this example for brevity.
        # ...
        "Z561",   # Change of job
        "Z5682",  # Military deployment status
        # ...
    }
    class PediatricConditionSearch(BaseHandler):
        """
        Filter condition searches for pediatric patients.
        """
        RESPONDS_TO = [
            EventType.Name(EventType.DIAGNOSE__DIAGNOSE__POST_SEARCH),
            EventType.Name(EventType.MEDICAL_HISTORY__PAST_MEDICAL_HISTORY__POST_SEARCH),
        ]
        def compute(self):
            """
            Remove condition search results representing codings that are resevered
            for adults if the patient is <= 15 years old.
            """
            # This event's target is the command we are searching within. Look up
            # the patient id from the command.
            patient_id = Command.objects.filter(id=self.target).values_list('patient__id', flat=True).first()
            fifteen_years_ago = arrow.now().shift(years=-15).date().isoformat()
            patient_is_pediatric = Patient.objects.filter(
                id=patient_id, birth_date__gt=fifteen_years_ago).exists()
            # If the patient is not pediatric, do not alter the search.
            # If the patient is pediatric, loop through the search results, and
            # compare the codings of the options with our list of adult-only
            # diagnosis codes. If it's an adult only code, remove it from the
            # list.
            return []
    ```
Once again you see some code that optimizes for performance over readability. If you're not familiar with the Django ORM, this code:
    ```python
    patient_id = Command.objects.filter(id=self.target).values_list('patient__id', flat=True).first()
    ```
Is equivalent to this code, which you may find more readable:
    ```python
    command = Command.objects.get(id=self.target)
    patient_id = command.patient.id
    ```
However you get to the patient's id is up to you. Once you have it, the code is nearly identical to the previous example, the only difference being the age we're targeting. We are asking the database "Does the patient with this id have a birth date more recent than 15 years ago?"
####  Altering the Layout 
Now that we know when we should act, we need to write the code for filtering the list of search results. When the search is performed, the raw results are sent to our code before being ultimately delivered to the dropdown box in the front-end. We have the opportunity to modify that list before it hits the dropdown. While we're focused on removing irrelevant choices, you could also add labels to certain ones you wish to highlight or alter the search order to guide users to preferred options.
Our code loops through the ICD-10 codes associated with the search results, checks for their presence in the set of adult ICD-10 codes, and only includes them in the post-processed set if they are not in the adult code list. The raw search results are in the event's context object under the `results` key.
Here's the full code:
    ```python
    import json
    import arrow
    from canvas_sdk.v1.data.command import Command
    from canvas_sdk.v1.data.patient import Patient
    from canvas_sdk.effects import Effect, EffectType
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers.base import BaseHandler
    ADULT_ONLY_ICD_CODES = {
        # There are many, many more. Limiting this example for brevity.
        # ...
        "Z561",   # Change of job
        "Z5682",  # Military deployment status
        # ...
    }
    class PediatricConditionSearch(BaseHandler):
        """
        Filter condition searches for pediatric patients.
        """
        RESPONDS_TO = [
            EventType.Name(EventType.DIAGNOSE__DIAGNOSE__POST_SEARCH),
            EventType.Name(EventType.MEDICAL_HISTORY__PAST_MEDICAL_HISTORY__POST_SEARCH),
        ]
        def compute(self):
            """
            Remove condition search results representing codings that are resevered
            for adults if the patient is <= 15 years old.
            """
            results = self.context.get("results")
            if results is None:
                return [Effect(type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS, payload=json.dumps(None))]
            # This event's target is the command we are searching within. Look up
            # the patient id from the command.
            patient_id = Command.objects.filter(id=self.target).values_list('patient__id', flat=True).first()
            fifteen_years_ago = arrow.now().shift(years=-15).date().isoformat()
            patient_is_pediatric = Patient.objects.filter(
                id=patient_id, birth_date__gt=fifteen_years_ago).exists()
            # If the patient is not pediatric, do not alter the search.
            if not patient_is_pediatric:
                return [Effect(type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS, payload=json.dumps(None))]
            # Create our container for modified search results
            post_processed_results = []
            # Loop through the ICD 10 codes associated with the results
            for result in self.context["results"]:
                for coding in result.get("extra", {}).get("coding", []):
                    if not coding.get("system") in ("http://hl7.org/fhir/sid/icd-10", "ICD-10"):
                        continue
                    # If the ICD 10 code is not in the list of Adult-only codes,
                    # we can add this result to what will ultimately be returned.
                    if coding.get("code") not in ADULT_ONLY_ICD_CODES:
                        post_processed_results.append(result)
                        break
            # Return our modified search results
            return [
                Effect(
                    type=EffectType.AUTOCOMPLETE_SEARCH_RESULTS,
                    payload=json.dumps(post_processed_results),
                )
            ]
    ```
Once deployed, certain diagnosis codes will not clutter up search results in commands for pediatric patients, but will continue to show as expected for patients over the age of 15.
##  Watch the Workflow in Action 
View and deploy the Pediatric Patient Chart Customization Extension [here](https://www.canvasmedical.com/extensions/pediatric-patient-chart-customizations).
##  Conclusion 
Age is one differentiator that changes the relevance of EMR features, but there are many, many others. Using the Canvas SDK can help keep clinicians focused, with the features they need front-and-center and the ones they don't need out of the way.

---

# Using AttributeHubs for Plugin State

Source: https://docs.canvasmedical.com/guides/using-attribute-hubs-for-plugin-state/

Plugins that run on a schedule often need to remember where they left off. A lab sync needs a cursor so it doesn't re-fetch results. A reminder system needs to track which patients have already been contacted. A data pipeline needs a lock so overlapping runs don't collide.
[AttributeHubs](/sdk/custom-data-attribute-hubs/) are a natural fit for this kind of state. A single hub can hold a mix of strings, numbers, booleans, timestamps, and JSON structures — no schema definition required. In this guide you'll build a plugin that periodically syncs lab results from an external vendor and uses one AttributeHub to manage its sync cursor, run lock, configuration, and operational statistics.
> **Info:** This guide assumes you have the Canvas CLI installed and signed in to Canvas Platform with `canvas login`, that your organization's plugin prefix is `my_org` (substitute your own), and that you're familiar with plugin basics. If you're starting from scratch, work through [Your First Plugin](/guides/your-first-plugin/) first.
##  What we're building 
The plugin has two components:
  1. **A cron handler** that runs every 10 minutes and processes a batch of lab results. This guide uses generated demo data so you can deploy it immediately and see it work. In production, you'd swap in a real API call to your lab vendor — only the `fetch_results` method changes.
  2. **A single AttributeHub** that stores all of the sync state: cursor position, run lock, processing stats, and a mapping of the vendor's test codes to LOINC codes.
The hub demonstrates several AttributeHub value types working together:
Attribute| Type| Purpose  
---|---|---  
`last_sync_cursor`| datetime| Timestamp of the most recent result fetched  
`is_running`| boolean| Lock flag to prevent overlapping runs  
`last_run_at`| datetime| When the sync last completed  
`results_synced`| integer| Running total of results processed  
`batch_size`| integer| How many results to pull per run  
`code_mapping`| JSON (dict)| Vendor test codes → LOINC codes  
`failed_accessions`| JSON (list)| Accession numbers that failed processing  
##  Initialize the plugin 
    ```sh
    $ canvas init
      [1/1] project_name (My Cool Plugin): Lab Sync
    Project created in /Users/you/lab-sync
    Registered my_org__lab_sync with Canvas Platform.
    ```
    ```sh
    cd lab-sync
    ```
Remove the placeholder handler since we'll create our own:
    ```sh
    rm my_org__lab_sync/handlers/event_handlers.py
    ```
##  Configure the manifest 
Replace the contents of `my_org__lab_sync/CANVAS_MANIFEST.json`:
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "my_org__lab_sync",
        "description": "Syncs lab results from an external vendor on a schedule",
        "components": {
            "handlers": [
                {
                    "class": "my_org__lab_sync.handlers.sync_labs:SyncLabs",
                    "description": "Cron job that pulls lab results from an external vendor"
                }
            ]
        },
        "variables": [],
        "custom_data": {
            "namespace": "my_org__lab_sync",
            "access": "read_write"
        },
        "tags": {},
        "license": "",
        "readme": "./README.md"
    }
    ```
Replace `my_org` in the namespace with your organization's name.
##  Build the sync handler 
Create `my_org__lab_sync/handlers/sync_labs.py`. This version uses generated demo data so you can install it and see every code path exercised immediately. The `fetch_results` method is the only part you'd replace with a real API call in production — everything else stays the same.
    ```python
    from datetime import datetime, timezone, timedelta
    from canvas_sdk.effects import Effect
    from canvas_sdk.handlers.cron_task import CronTask
    from canvas_sdk.v1.data import AttributeHub
    from logger import log
    # Default vendor test code → LOINC mapping. In practice this might come from
    # the vendor's API or a configuration endpoint.
    DEFAULT_CODE_MAPPING = {
        "CBC": "58410-2",
        "BMP": "51990-0",
        "HBA1C": "4548-4",
        "TSH": "3016-3",
        "LIPID": "57698-3",
    }
    # Demo data: test codes to cycle through. Includes "UNKNOWN_PANEL" to exercise
    # the failure/unmapped-code path.
    DEMO_TEST_CODES = ["CBC", "HBA1C", "UNKNOWN_PANEL", "TSH", "BMP", "LIPID"]
    def get_sync_state():
        """Load or create the sync state hub with sensible defaults."""
        hub, created = AttributeHub.objects.get_or_create(
            type="lab_sync_state",
            id="singleton",
        )
        if created:
            hub.set_attributes({
                "is_running": False,
                "results_synced": 0,
                "batch_size": 50,
                "code_mapping": DEFAULT_CODE_MAPPING,
                "failed_accessions": [],
            })
            log.info("Initialized lab sync state hub with defaults")
        return hub
    class SyncLabs(CronTask):
        SCHEDULE = "*/10 * * * *"  # Every 10 minutes
        def execute(self) -> list[Effect]:
            hub = get_sync_state()
            # Check the run lock to prevent overlapping syncs
            if hub.get_attribute("is_running"):
                log.info("Lab sync already in progress, skipping")
                return []
            # Acquire the lock
            hub.set_attribute("is_running", True)
            try:
                results = self.fetch_results(hub)
                self.process_results(hub, results)
            finally:
                # Always release the lock, even if something fails
                hub.set_attributes({
                    "is_running": False,
                    "last_run_at": datetime.fromisoformat(self.target),
                })
            return []
        def fetch_results(self, hub):
            """Generate demo lab results.
            In a real plugin, this method would call the vendor's API using
            canvas_sdk.utils.Http. The demo generates 3 results per run with
            timestamps after the current cursor so the sync always has work to do.
            """
            cursor = hub.get_attribute("last_sync_cursor") or ""
            synced_count = hub.get_attribute("results_synced") or 0
            # Use the synced count to cycle through demo test codes so each run
            # produces different results.
            now = datetime.now(timezone.utc)
            results = []
            for i in range(3):
                code_index = (synced_count + i) % len(DEMO_TEST_CODES)
                collected_at = (now + timedelta(seconds=i)).replace(microsecond=0)
                results.append({
                    "accession_number": f"DEMO-{synced_count + i + 1:04d}",
                    "test_code": DEMO_TEST_CODES[code_index],
                    "collected_at": collected_at,
                })
            return results
        def process_results(self, hub, results):
            """Process fetched results and update sync state."""
            if not results:
                log.info("No new lab results to process")
                return
            code_mapping = hub.get_attribute("code_mapping") or {}
            failed = hub.get_attribute("failed_accessions") or []
            synced_count = hub.get_attribute("results_synced") or 0
            latest_cursor = hub.get_attribute("last_sync_cursor")
            for result in results:
                accession = result.get("accession_number", "")
                vendor_code = result.get("test_code", "")
                loinc_code = code_mapping.get(vendor_code)
                if not loinc_code:
                    log.info(
                        f"No LOINC mapping for vendor code '{vendor_code}' "
                        f"(accession {accession}), skipping"
                    )
                    failed.append(accession)
                    continue
                # In a real plugin, you would create an Observation here using
                # canvas_sdk.effects.observation.Observation with the mapped LOINC code.
                log.info(
                    f"Processed result {accession}: {vendor_code} → {loinc_code}"
                )
                synced_count += 1
                result_timestamp = result.get("collected_at")
                if latest_cursor is None or result_timestamp > latest_cursor:
                    latest_cursor = result_timestamp
            hub.set_attributes({
                "last_sync_cursor": latest_cursor,
                "results_synced": synced_count,
                "failed_accessions": failed,
            })
            log.info(
                f"Lab sync complete: {len(results)} fetched, "
                f"{synced_count} total synced, {len(failed)} failed"
            )
    ```
##  Anatomy of the plugin 
###  State initialization 
The `get_sync_state` function uses `get_or_create` to ensure the state hub exists. On first run, it seeds the hub with default values:
    ```python
    hub, created = AttributeHub.objects.get_or_create(
        type="lab_sync_state",
        id="singleton",
    )
    if created:
        hub.set_attributes({
            "is_running": False,
            "results_synced": 0,
            "batch_size": 50,
            "code_mapping": DEFAULT_CODE_MAPPING,
            "failed_accessions": [],
        })
    ```
Because this plugin only needs one state hub, we use the fixed id `"singleton"`. The `type` and `id` together form a unique key, so every invocation loads the same hub.
Notice the variety of types in one hub: a boolean lock, integer counters and configuration, a dict for code mappings, and a list for tracking failures. Timestamp attributes like `last_sync_cursor` and `last_run_at` start as `None` (unset) and are populated with `datetime` objects once the first run completes. `set_attributes` maps each Python type to the appropriate database column automatically.
###  Run lock 
The `is_running` boolean prevents overlapping syncs. Since the cron runs every 10 minutes, a slow API response could cause the next invocation to start before the previous one finishes. The lock pattern is straightforward:
    ```python
    if hub.get_attribute("is_running"):
        log.info("Lab sync already in progress, skipping")
        return []
    hub.set_attribute("is_running", True)
    try:
        # ... do work ...
    finally:
        hub.set_attributes({
            "is_running": False,
            "last_run_at": datetime.fromisoformat(self.target),
        })
    ```
The `finally` block ensures the lock is released even if processing raises an exception. Without it, a crash would leave `is_running` as `True` permanently, and the sync would never run again. Note that `self.target` is an ISO 8601 string, so we parse it into a `datetime` before storing it — this way AttributeHub stores it in the `timestamp_value` column rather than as text.
###  Cursor-based pagination 
Each run picks up where the last one left off by reading `last_sync_cursor`. In a production plugin, this cursor would be sent to the vendor API so it only returns newer results. After processing a batch, the cursor advances to the timestamp of the most recent result:
    ```python
    cursor = hub.get_attribute("last_sync_cursor") or ""
    # ... fetch and process results ...
    hub.set_attribute("last_sync_cursor", latest_cursor)
    ```
On the very first run, the cursor is an empty string. Each subsequent run advances the cursor to the most recent result's timestamp, so a real vendor API call would only return results newer than the cursor.
###  Code mapping as JSON 
The `code_mapping` attribute is a Python dict stored as JSON in the database. It maps the vendor's proprietary test codes to standard LOINC codes:
    ```python
    code_mapping = hub.get_attribute("code_mapping") or {}
    # ...
    loinc_code = code_mapping.get(vendor_code)
    ```
This mapping doesn't belong in a CustomModel column because its keys vary by vendor. A different lab system would have entirely different test codes. Storing it as a JSON attribute means the mapping can be updated at runtime — for example, through a separate admin API endpoint — without any schema changes.
###  Failure tracking 
Failed accession numbers accumulate in the `failed_accessions` list attribute. This gives operators visibility into which results couldn't be processed, without building a separate error-tracking table:
    ```python
    failed = hub.get_attribute("failed_accessions") or []
    # ...
    failed.append(accession)
    # ...
    hub.set_attribute("failed_accessions", failed)
    ```
In a production plugin you might periodically clear this list after the failures have been investigated, or cap its length to prevent unbounded growth.
##  Deploy and test 
Deploy the plugin:
    ```sh
    canvas deploy my_org__lab_sync --instance YOUR_INSTANCE
    ```
Stream the logs to watch the sync run:
    ```sh
    canvas logs --host YOUR_INSTANCE
    ```
Within 10 minutes you should see the first run initialize the state hub and process the demo batch:
    ```text
    INFO Initialized lab sync state hub with defaults
    INFO Processed result DEMO-0001: CBC → 58410-2
    INFO Processed result DEMO-0002: HBA1C → 4548-4
    INFO No LOINC mapping for vendor code 'UNKNOWN_PANEL' (accession DEMO-0003), skipping
    INFO Lab sync complete: 3 fetched, 2 total synced, 1 failed
    ```
The first two results mapped successfully. The third — `UNKNOWN_PANEL` — had no entry in `code_mapping`, so it was added to the `failed_accessions` list. On the next run, the demo cycles to different test codes and the accession numbers continue incrementing, so you can watch the cursor, counters, and failure list evolve over successive runs.
##  Inspecting and updating state 
Because all sync state lives in a single AttributeHub, you can inspect or adjust it through a SimpleAPI endpoint or a plugin-based application. For example, to reset the cursor and re-sync from scratch:
    ```python
    hub = AttributeHub.objects.get(type="lab_sync_state", id="singleton")
    hub.set_attributes({
        "last_sync_cursor": "",
        "results_synced": 0,
        "failed_accessions": [],
    })
    ```
To add a new code mapping without redeploying:
    ```python
    hub = AttributeHub.objects.get(type="lab_sync_state", id="singleton")
    mapping = hub.get_attribute("code_mapping")
    mapping["VITAMIN_D"] = "1989-3"
    hub.set_attribute("code_mapping", mapping)
    ```
This is one of the practical benefits of storing configuration as AttributeHub attributes — it's data you can change at runtime, not code you have to redeploy.
##  Connecting to a real vendor 
To swap the demo data for a real lab vendor API, replace `fetch_results` with an HTTP call using `canvas_sdk.utils.Http`. The rest of the plugin stays exactly the same.
    ```python
    from canvas_sdk.utils import Http
    def fetch_results(self, hub):
        """Pull a batch of results from the vendor API."""
        base_url = self.secrets["LAB_VENDOR_BASE_URL"]
        api_key = self.secrets["LAB_VENDOR_API_KEY"]
        cursor = hub.get_attribute("last_sync_cursor") or ""
        batch_size = hub.get_attribute("batch_size")
        http = Http()
        response = http.get(
            f"{base_url}/results",
            headers={
                "Authorization": f"Bearer {api_key}",
                "X-Since": cursor,
                "X-Limit": str(batch_size),
            },
        )
        if not response.ok:
            log.info(
                f"Lab vendor API returned {response.status_code}, "
                f"skipping this run"
            )
            return []
        return response.json().get("results", [])
    ```
You'll also need to add the secrets to your manifest and set their values with `canvas config set`:
    ```json
    "variables": [
        {"name": "LAB_VENDOR_API_KEY", "sensitive": true},
        {"name": "LAB_VENDOR_BASE_URL", "sensitive": false}
    ],
    ```
    ```sh
    canvas deploy my_org__lab_sync --instance YOUR_INSTANCE
    canvas config set my_org__lab_sync \
        LAB_VENDOR_API_KEY=your-api-key \
        LAB_VENDOR_BASE_URL=https://api.labvendor.example.com/v1 \
        --instance YOUR_INSTANCE
    ```
The vendor's response must include a `results` array of objects with at minimum `accession_number`, `test_code`, and `collected_at` fields to match what `process_results` expects.
##  When to use a CustomModel instead 
A single state hub works well when your plugin manages a handful of values that are read and written as a group. Consider switching to [CustomModels](/sdk/custom-data-custom-models/) when:
  - You need to **store one record per entity** (e.g., sync status per patient). A separate hub per patient works up to a point, but a CustomModel with a foreign key to Patient gives you proper relationships and efficient queries.
  - You need to **query by attribute value** across many records. Finding all hubs where `results_synced > 100` requires a JOIN to the attribute table per condition. A CustomModel with an indexed integer column handles this natively.
  - Your **state has grown into a stable schema**. If you find yourself always reading and writing the same set of attributes, that's a sign the data has matured into a schema worth formalizing.
For a deeper comparison, see [Design Considerations](/sdk/custom-data-design-considerations/).

---

# Writing Commands Over HTTP

Source: https://docs.canvasmedical.com/guides/writing-commands-over-http/

Writing to a patient's chart from outside Canvas — from a custom charting surface, a scribe, an intake form, a back-office tool — used to mean building the API yourself: a [SimpleAPI](/sdk/handlers-simple-api/) route per command, reading a JSON body, mapping keys onto command fields, deciding what a bad value returns, building the effect. Every team that needed it built the same one.
**Canvas has now built it for you.** `CommandAPI` is that endpoint, templated: it reads the body onto a command, validates it against that command, and emits the effects. All you add is the part that should be yours — who may call it, and what they are allowed to write.
That remainder is most of this guide, because it is the part no template can decide: authentication tells you _who_ is calling, not whether that person may write to _this note_.
##  What you'll learn 
  - How to expose one command as an HTTP endpoint with [`CommandAPI`](/sdk/handlers-simple-api-commands/)
  - The request and response shape every operation shares
  - How to check that the caller may actually write to _this note_ , which authentication alone does not tell you
  - How to serve every command from a single endpoint
##  Your first command endpoint 
`CommandAPI` is a `SimpleAPI`, so it brings the request handling. You declare a scheme, a prefix and your routes — here a staff session guards the endpoint, and one `POST` writes a History of Present Illness. Which scheme to use is a decision of its own:
    ```python
    from canvas_sdk.commands import HistoryOfPresentIllnessCommand
    from canvas_sdk.commands.api import CommandAPI
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import Response
    from canvas_sdk.handlers.simple_api import StaffSessionAuthMixin, api
    class HistoryOfPresentIllnessAPI(StaffSessionAuthMixin, CommandAPI):
        PREFIX = "/v1"
        @api.post("/hpi")
        def insert(self) -> list[Response | Effect]:
            return self.originate(HistoryOfPresentIllnessCommand)
        @api.patch("/hpi/<command_id>")
        def update(self) -> list[Response | Effect]:
            return self.edit(HistoryOfPresentIllnessCommand, self.request.path_params["command_id"])
        @api.delete("/hpi/<command_id>")
        def remove(self) -> list[Response | Effect]:
            return self.action(
                HistoryOfPresentIllnessCommand, self.request.path_params["command_id"], "delete"
            )
    ```
That is the whole endpoint. Posting to it:
    ```sh
    curl -X POST "https://example.canvasmedical.com/plugin-io/api/my_plugin/v1/hpi" \
      -H "Content-Type: application/json" \
      -d '{
            "note_id": "fd05f99a-7abe-4bcd-be94-adf09937af2a",
            "values": {"narrative": "Patient reports a headache for three days."}
          }'
    ```
    ```json
    { "command_uuid": "2588aa22-f5b4-4335-b4fe-aea69cdfb3f3", "committed": false }
    ```
> **Warning:** A route handler cannot be named `originate`, `edit` or `action` — those are the methods you are calling. Name handlers for the HTTP verb they serve, as above.
##  The three operations 
Everything `CommandAPI` does is one of three calls, and between them they cover the life of a command: `originate` puts a new one in a note, `edit` revises it while it is still staged, and `action` runs whatever finishes it — committing it, sending it, or entering it in error. Each returns the effects and the response together, so a route handler stays a single `return`.
The body each call accepts, the status it answers with, and every error shape are documented in [Commands API](/sdk/handlers-simple-api-commands/#methods). What is left to you is a handful of decisions no reference can make:
**Staged, or committed in the same request.** `originate` leaves the command staged unless you ask otherwise. Staged is usually right — your endpoint proposes and the provider completes, which is also how the chart behaves. Commit in the same request when nobody needs to check the entry, such as a reading from a device, and not when a clinician should see it before it counts. Bear in mind that [several commands cannot be committed at all](/sdk/effects/#commands) and are finished by sending or signing instead.
**Whose id the command has.** By default Canvas names it and hands the id back. Pass `command_id` and you name it, which earns its keep when the thing you are writing already has an identity on your side: you can ask whether it reached the chart by that id instead of keeping a mapping, and a retry becomes safe, because posting the same id twice is refused rather than writing a second command. It has to be a genuine UUID — [Choosing the command's id](/sdk/handlers-simple-api-commands/#choosing-the-commands-id) covers how to produce one, including when your own identifier is not a UUID.
**What you want to remember about the entry.** `metadata` attaches a flat map that Canvas stores and never interprets. Use it for what the entry meant on your side — the submission it came from, the version of your mapping — so that months later a chart entry can be traced back to its origin.
**How much a caller learns from a rejection.** Every refusal has the same shape, and every field at fault is reported at once rather than one per round trip. Build against that and a form can mark all its bad fields from a single response, rather than walking its user through them one at a time.
##  Checking that the caller may write to this note 
This is the part worth thinking about, because three questions look alike and are not:
  - **Authentication** — _who is calling?_ `CommandAPI` does not pick this for you, but the schemes are provided: `StaffSessionAuthMixin`, `PatientSessionAuthMixin`, `APIKeyAuthMixin` and `BasicAuthMixin`, each declared by listing it before `CommandAPI` in the bases. Declare none and the endpoint refuses every request rather than admitting anyone. `StaffSessionAuthMixin` answers "a logged-in staff member", and nothing more — see [authentication mixins](/sdk/handlers-simple-api-http/#authentication-mixins) for what each needs.
  - **Authorization** — _may this caller do this to this note?_ The mixin cannot answer that, because it never sees the note.
  - **Attribution** — _who will the chart say wrote it?_ This follows from how the caller authenticated, which makes the scheme you pick a clinical decision and not only a security one. A session-backed request is attributed to the logged-in user, and so is one carrying an access token from the [Authorization Code flow](/api/customer-authentication#authorization-code). A shared secret identifies nobody, so `APIKeyAuthMixin` and `BasicAuthMixin` requests are recorded as **Canvas Bot** — fine for a device feed, wrong for anything a clinician should be seen to have written. See [Acting as a Canvas user](/sdk/handlers-simple-api-http/#acting-as-a-canvas-user).
An endpoint gated only on "is staff" lets any staff member write any command to any note. That may be exactly right — it is roughly what the chart itself allows — but decide it rather than inherit it.
###  Reading who the caller is 
Canvas does the identifying; turning it into something you can check is yours.
When a request arrives with a real session behind it, Canvas sets two headers on it — `canvas-logged-in-user-type` and `canvas-logged-in-user-id`. Neither can be forged: plugin-io strips both if they arrive from the client and sets them only from a session it has verified itself.
Nothing in the SDK turns them into a record, so write the one line that does. There is no built-in `caller()` — this is a helper on your own handler:
    ```python
    from canvas_sdk.v1.data.staff import Staff
    def caller(self) -> Staff | None:
        """The staff member behind this request, or None when there is no staff session."""
        if self.request.headers.get("canvas-logged-in-user-type") != "Staff":
            return None
        return Staff.objects.filter(id=self.request.headers.get("canvas-logged-in-user-id")).first()
    ```
The header carries the staff **key** , which is what `Staff.id` holds — a 32-character UUID with no dashes — so it matches on `id` rather than `dbid`.
Whether those headers are there at all depends on the scheme you chose, and so does who the chart credits for the write:
Scheme| Identifies a person| The command is attributed to  
---|---|---  
`StaffSessionAuthMixin`| yes — a staff member| that staff member  
`PatientSessionAuthMixin`| yes — a patient| that patient  
An [Authorization Code](/api/customer-authentication#authorization-code) access token| yes| the staff member who authorized it  
`APIKeyAuthMixin`| no — a shared key| Canvas Bot  
`BasicAuthMixin`| no — a shared secret| Canvas Bot  
The bottom two authenticate a _system_ , not a person, so there is no logged-in user to read and nothing for the chart to credit. If your endpoint needs a named clinician on the entry, that rules them out.
###  Only the note's author, and only while the note is open 
Canvas already refuses a command bound for a note that has been deleted or cancelled, or that is signed and no longer writable — `canvas_core` validates the note as the effect is applied, inside the transaction, so nothing lands.
What it cannot do is tell your caller.
> **Danger:** Nothing in canvas-plugins reads the note's state, and command effects are applied after your response has already gone back. A closed note therefore answers `201` with a `command_uuid` and then writes no command. Checking before you write is the only way the caller ever finds out.
The check is also where you add the rule Canvas has no opinion on: any staff member may write to any note. If your surface is meant for the note's own provider, that is yours to enforce.
So make both decisions before you write, and return the refusal yourself:
    ```python
    from http import HTTPStatus
    from canvas_sdk.commands import PlanCommand
    from canvas_sdk.commands.api import CommandAPI
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import StaffSessionAuthMixin, api
    from canvas_sdk.v1.data.note import Note, NoteStateChangeEvent, NoteStates
    # The states in which a note still accepts documentation.
    OPEN_STATES = (
        NoteStates.NEW,
        NoteStates.PUSHED,
        NoteStates.UNLOCKED,
        NoteStates.RESTORED,
        NoteStates.UNDELETED,
        NoteStates.CONVERTED,
    )
    class PlanAPI(StaffSessionAuthMixin, CommandAPI):
        PREFIX = "/v1"
        @api.post("/plan")
        def insert(self) -> list[Response | Effect]:
            # A body that will not parse is not authorized against — `originate` refuses it with a
            # 400 of its own, and nothing is written in the meantime.
            try:
                body = self.request.json()
            except ValueError:
                return self.originate(PlanCommand)
            note_id = body.get("note_id", "") if isinstance(body, dict) else ""
            if denial := self.refuse(str(note_id)):
                return [denial]
            return self.originate(PlanCommand)
        def refuse(self, note_id: str) -> JSONResponse | None:
            """A response to send instead of writing, or None when the caller may proceed."""
            # One query for the two scalars the decision needs.
            note = Note.objects.filter(id=note_id).values("dbid", "provider__id").first()
            if note is None:
                return JSONResponse({"error": "unknown note"}, status_code=HTTPStatus.NOT_FOUND)
            staff_id = self.request.headers.get("canvas-logged-in-user-id") or ""
            if not staff_id or str(note["provider__id"]) != staff_id:
                return JSONResponse(
                    {"error": "only the note's author can write to it"},
                    status_code=HTTPStatus.FORBIDDEN,
                )
            state = (
                NoteStateChangeEvent.objects.filter(note_id=note["dbid"])
                .order_by("created")
                .values_list("state", flat=True)
                .last()
            )
            if state not in OPEN_STATES:
                return JSONResponse(
                    {"error": "this note no longer accepts documentation"},
                    status_code=HTTPStatus.CONFLICT,
                )
            return None
    ```
Two things worth copying from that shape. It reads the note **once** , with `.values()`, because the check runs on every write. And it answers different refusals differently — `404` for a note that is not there, `403` for the wrong caller, `409` for a closed note — so the caller can tell "you may not" from "not any more".
`OPEN_STATES` is deliberately stricter than Canvas's own rule, which refuses only deleted, cancelled and signed notes. Listing the states you accept, rather than the ones you reject, means a state added to Canvas later is refused until you have decided what it should mean for your endpoint.
> **Warning:** Authorize against the same `note_id` that `originate` will write to — the one in the request body. Take it from anywhere else, such as a path parameter or query string, and a caller can present a note they own to your check while the body names a note they do not: `POST /v1/plan?note_id=<mine>` with `{"note_id": "<someone else's>"}` would pass and then write to the wrong chart.
###  Narrowing who reaches the endpoint at all 
When the rule is about the person rather than the note, put it in `authenticate` — the request never reaches your handler. Start from the [staff session mixin](/sdk/handlers-simple-api-http/#staff-session), which turns away anyone who isn't signed-in staff, and add your rule after it:
    ```python
    from canvas_sdk.handlers.simple_api import SessionCredentials, StaffSessionAuthMixin
    from canvas_sdk.v1.data.staff import Staff
    class PlanAPI(StaffSessionAuthMixin, CommandAPI):
        def authenticate(self, credentials: SessionCredentials) -> bool:
            """Only active staff who are providers may write commands here."""
            super().authenticate(credentials)
            return Staff.objects.filter(
                id=credentials.logged_in_user["id"], active=True, primary_practice_location__isnull=False
            ).exists()
    ```
Which of the two you use is a real choice. `authenticate` is cheaper and applies to every route, but it cannot see the note. A per-request check can, and it can explain itself in the response. Rules about the _caller_ belong in the first; rules about the _note_ belong in the second.
##  Serving every command from one endpoint 
Nothing ties an endpoint to a single command — the command is an argument. Put the command in the path and look it up, and one endpoint serves the lot.
Two things are worth getting right before you write it.
**Key the lookup on each command's own`Meta.key`.** That is the value `CommandAPI` uses when it looks a command up by id, so deriving the path segment from it keeps the URL and the lookup naming the same schema. It also saves you transcribing keys that are not guessable from the class name — `hpi`, `reasonForVisit`, `structuredAssessment`, `chartSectionReview`, `exam`, `ros`.
**Allow actions per command, not from one shared set.** [Not every command accepts every action](/sdk/effects/#commands): Prescribe and Refill are finished by sending rather than committing, Lab Order takes `send`, Imaging Order and Refer take `delegate` and `sign`, Order DME takes `sign`, and Reason for Visit takes none of them. This matters more than it looks — see the warning below.
    ```python
    from http import HTTPStatus
    from canvas_sdk.commands import (
        AllergyCommand,
        AssessCommand,
        HistoryOfPresentIllnessCommand,
        LabOrderCommand,
        PlanCommand,
        PrescribeCommand,
    )
    from canvas_sdk.commands.api import CommandAPI
    from canvas_sdk.commands.base import _BaseCommand
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.simple_api import JSONResponse, Response
    from canvas_sdk.handlers.simple_api import StaffSessionAuthMixin, api
    # Keyed on Meta.key, so the path segment always matches the schema CommandAPI looks up.
    COMMANDS: dict[str, type[_BaseCommand]] = {
        command.Meta.key: command
        for command in (
            AllergyCommand,
            AssessCommand,
            HistoryOfPresentIllnessCommand,
            LabOrderCommand,
            PlanCommand,
            PrescribeCommand,
        )
    }
    # What each command is actually finished with. Nothing infers this for you.
    STAGED_ACTIONS = {"commit", "delete", "enter_in_error"}
    ACTIONS: dict[str, set[str]] = {
        AllergyCommand.Meta.key: STAGED_ACTIONS,
        AssessCommand.Meta.key: STAGED_ACTIONS,
        HistoryOfPresentIllnessCommand.Meta.key: STAGED_ACTIONS,
        PlanCommand.Meta.key: STAGED_ACTIONS,
        LabOrderCommand.Meta.key: {"delete", "send", "enter_in_error"},
        PrescribeCommand.Meta.key: {"delete", "review", "send", "enter_in_error"},
    }
    def unknown_command() -> Response:
        """The one response every route shares, so a bad path reads the same way throughout."""
        return JSONResponse(
            {"error": "no such command", "commands": sorted(COMMANDS)},
            status_code=HTTPStatus.NOT_FOUND,
        )
    class ChartingAPI(StaffSessionAuthMixin, CommandAPI):
        PREFIX = "/commands"
        @api.post("/<schema>")
        def create(self) -> list[Response | Effect]:
            command = COMMANDS.get(self.request.path_params["schema"])
            if command is None:
                return [unknown_command()]
            return self.originate(command)
        @api.put("/<schema>/<command_id>")
        def update(self) -> list[Response | Effect]:
            command = COMMANDS.get(self.request.path_params["schema"])
            if command is None:
                return [unknown_command()]
            return self.edit(command, self.request.path_params["command_id"])
        @api.post("/<schema>/<command_id>/<action>")
        def act(self) -> list[Response | Effect]:
            schema = self.request.path_params["schema"]
            command = COMMANDS.get(schema)
            if command is None:
                return [unknown_command()]
            action = self.request.path_params["action"]
            allowed = ACTIONS.get(schema, set())
            if action not in allowed:
                return [
                    JSONResponse(
                        {"error": f"{schema} does not accept that action", "allowed": sorted(allowed)},
                        status_code=HTTPStatus.BAD_REQUEST,
                    )
                ]
            return self.action(command, self.request.path_params["command_id"], action)
    ```
That is the whole surface: `POST /commands/hpi` creates, `PUT /commands/hpi/<id>` revises, `POST /commands/hpi/<id>/commit` finishes. Adding a command is two lines — one in `COMMANDS`, one in `ACTIONS`.
> **Warning:** Gating the actions is not defensive tidiness, it is the difference between a write landing and silently not landing. Every command class inherits `commit()`, so `POST /commands/prescribe/<id>/commit` would build a valid effect and answer `200` — and Canvas would then refuse to apply it, because Prescribe has no COMMIT. The caller is told the write succeeded when it did not. An action absent from `ACTIONS` is refused before any effect is built.
Two smaller things the shape buys you:
  - **One`404` for an unknown command, everywhere.** `unknown_command()` is a plain function rather than a method, because `CommandAPI` reserves `originate`, `edit` and `action`, and SimpleAPI raises at class-definition time if a subclass shadows a base method.
  - **The`<schema>` segment is also your allow-list.** A command absent from `COMMANDS` is unreachable, so adding `CommandAPI` to a plugin does not expose every command in the SDK — only the ones you named.
##  Where to go next 
  - [Commands](/sdk/commands/) — every command and its fields
  - [Populating Command Fields](/guides/populating-command-fields/) — where a field's _value_ comes from when there is no autocomplete to pick it for you
  - [Commands API](/sdk/handlers-simple-api-commands/) — the reference for `CommandAPI`
  - [SimpleAPI](/sdk/handlers-simple-api/) — routing, authentication schemes, and responses

---

# Your First Application

Source: https://docs.canvasmedical.com/guides/your-first-application/

This guide will walk you through the process of installing, initializing, and customizing embeddable applications in Canvas.
##  What Are Applications in Canvas? 
Applications in Canvas are embeddable plugins that enhance the functionality of the Canvas platform. They allow developers to create custom features accessible directly from within the Canvas interface, such as interactive tools, data visualizations, or workflow integrations. These applications can be configured to appear globally or within specific contexts, such as the patient chart page.
##  Step 1: Install and Configure the Canvas CLI 
Follow the instructions in the [Canvas documentation](https://docs.canvasmedical.com/guides/your-first-plugin/#1-install-the-canvas-cli) to install and configure the Canvas CLI. Once complete, ensure that you can successfully run `canvas` commands from your terminal.
##  Step 2: Initialize an Application 
To create a new application, run the following command:
    ```bash
    canvas init application
    ```
This will generate a boilerplate application along with a [`CANVAS_MANIFEST.json`](/sdk/canvas_manifest/#applications) file. Signed in to Canvas Platform, `canvas init` names the package with your organization's prefix, such as `acme__my_cool_application`, and registers it with Canvas Platform.
##  Step 3: Understanding the `CANVAS_MANIFEST.json` File 
The `CANVAS_MANIFEST.json` file describes your application and its components. Below is an example of a manifest and a description of the customizable properties:
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "acme__my_cool_application",
        "description": "Edit the description in CANVAS_MANIFEST.json",
        "url_permissions": [
            {
                "url": "https://my-application.com",
                "permissions": []
            }
        ],
        "components": {
            "applications": [
                {
                    "class": "acme__my_cool_application.applications.my_application:MyApplication",
                    "name": "My Application",
                    "description": "An Application that does xyz...",
                    "scope": "global",
                    "icon": "assets/python-logo.png",
                    "menu_position": "top",
                    "menu_order": "100",
                    "show_in_panel": false,
                    "panel_priority": 100
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
###  Customizable Properties 
  1. **name** : The display name of the application.
  2. **description** : A brief description of the application.
  3. **icon** : The icon for the application. This can be a URL to an image or a path inside the plugin package.
  4. **scope** :
     - `global`: The app will appear across all contexts.
     - `patient_specific`: The app will appear only in the patient chart page.
     - `provider_menu_item`: The app button will be displayed on the provider's menu.
     - `portal_menu_item`: The app button will be displayed on the patient portal menu.
  5. **url_permissions** : The allowed urls and permissions for the application. This is used for security purposes. For more info check the [Application Handler](/sdk/
handlers-applications).
  6. **menu_position** : Determines where the menu item will be placed within the menu (this configuration applies only to the providers menu)
     - `top`: The item will be placed on the top section.
     - `bottom`: The item will be placed in the bottom section - this section should display items that open in a new window.
  7. **menu_order** : How the items will be ordered in the menu. e.g 100, 200
  8. **show_in_panel** : If you want to increase your application's visibility and display it alongside other panel buttons (instead of in the applications drawer), you can set this attribute. A panel icon has no label, so Canvas shows the application's `name` in a tooltip when a user hovers over it
  9. **panel_priority** : How the applications will be ordered in the panel section. e.g 100, 200
##  Step 4: Overriding the Application Behavior 
Developers must extend the `Application` class and override the `on_open` method to define the behavior when the app icon is clicked. Below is an example implementation:
    ```python
    from canvas_sdk.effects import Effect
    from canvas_sdk.effects.launch_modal import LaunchModalEffect
    from canvas_sdk.handlers.application import Application
    class MyApplication(Application):
        """An embeddable application that can be registered to Canvas."""
        def on_open(self) -> Effect:
            """Handle the on_open event."""
            # Implement this method to handle the application on_open event.
            return LaunchModalEffect(
                url="http://localhost:8000",
                target=LaunchModalEffect.TargetType.DEFAULT_MODAL
            ).apply()
    ```
###  Key Details 
  - **`on_open` Method**:
    - Called when the user clicks on the app icon.
    - Should return a `LaunchModalEffect` that specifies:
      - **url** : The URL to open.
      - **target** : The display target.
###  Target Options 
  - `DEFAULT_MODAL`: Opens the URL in a modal centered on the screen.
  - `NEW_WINDOW`: Opens the URL in a new browser window.
  - `PAGE`: Opens the URL as a page in the app
  - `RIGHT_CHART_PANE`: Opens the URL in the right-hand pane of the patient chart.
  - `RIGHT_CHART_PANE_LARGE`: Opens the URL in an enlarged right-hand pane of the patient chart.
When opened in a patient's chart, both right chart pane targets stay open while the user moves around the same patient's chart. They close when the user opens a different patient or leaves the chart.
##  Step 5: Deploying the Application 
Sign in with [`canvas login`](/sdk/canvas_cli/#signing-in-to-canvas-platform) if you haven't, then validate and deploy your application to an instance:
    ```bash
    canvas validate <path/to/application>
    canvas deploy <path/to/application> --instance <instance>
    ```
`<path/to/application>` is the package folder that holds `CANVAS_MANIFEST.json`, named with your organization's prefix, such as `acme__my_cool_application`. See [`canvas deploy`](/sdk/canvas_cli/#canvas-deploy).

---

# Your First Plugin (with Claude Code)

Source: https://docs.canvasmedical.com/guides/your-first-plugin-with-claude-code/

Canvas plugins let you customize the EHR — reacting to events, reading patient data, and returning effects that alter workflows. This guide uses an AI-assisted approach powered by Claude Code and the Canvas Plugin Assistant (CPA), getting you from idea to deployed plugin in minutes.
> **Info:** Haven't yet advanced to AI-assisted coding? See [Your First Plugin (Manual)](/guides/your-first-plugin/) to build your plugin by hand.
##  Background: AI-Assisted Plugin Development 
[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) is Anthropic's agentic coding tool — it can read, write, and execute code autonomously in your terminal. Rather than copying and pasting snippets from documentation or typing code by hand, you can describe what you want in plain English and Claude Code does the programming with your supervision.
Claude Code supports a plugin marketplace. We built the Canvas Plugin Assistant (CPA) Claude Code plugin (yes, a plugin to make plugins!) with deep knowledge of the Canvas SDK, common plugin patterns, and best-practice workflows in plugin development.
CPA accelerates the entire plugin development lifecycle — from brainstorming requirements and scaffolding code, to running tests and deploying to your instance and rapidly cycling through user acceptance testing and enhancements.
Together, Claude Code with CPA lets developers go from an idea to a working, deployed plugin through natural conversation at warp speed.
##  Prerequisites 
  - Python 3.12+ installed
  - A Canvas instance with admin access
  - The Canvas CLI signed in to Canvas Platform with `canvas login`. See [Signing in to Canvas Platform](/sdk/canvas_cli/#signing-in-to-canvas-platform)
  - Instance API credentials in `~/.canvas/credentials.ini`, which `/cpa:deploy` uses to install the plugin and stream its logs. See [Instance API credentials](/sdk/canvas_cli/#instance-api-credentials-credentialsini-deprecated); this method is deprecated, and support ends on December 14, 2026
  - [Claude Code installed](https://docs.anthropic.com/en/docs/claude-code/overview)
##  1\. Install the Canvas Plugin Assistant and Set Up Your Environment 
Follow the installation and setup instructions in the [Canvas Plugin Assistant README](https://github.com/canvas-medical/coding-agents/tree/main/canvas-plugin-assistant). Once complete, run `/cpa:check-setup` to verify everything is ready.
##  2\. Describe Your First Plugin 
Run `/cpa:new-plugin` to start building. CPA will ask clarifying questions via an interactive chip interface. Describe what you want in plain English. You can find examples of what's possible [here](https://github.com/Medical-Software-Foundation/canvas/tree/main/extensions), [here](https://github.com/canvas-medical/canvas-plugins/tree/main/example-plugins), and [here](https://www.canvasmedical.com/plugins). For example:
> I want a plugin that adds a button to the note header. When clicked, the button should inject a Reason for Visit command into the note with the text "hello world".
Here's what happens next:
  1. **Brainstorm** — CPA asks follow-up questions to refine your requirements
  2. **Specification** — CPA generates a `plugin-spec.md` for your review. Read through it and approve or request changes
  3. **Scaffold** — CPA creates the [plugin project structure](/guides/your-first-plugin/#4-navigate-the-structure-of-a-plugin), manifest, and handler files
  4. **Implement** — CPA writes the protocol/handler code based on the spec
  5. **Test** — CPA generates and runs tests to verify the plugin works correctly
At any point, if you have more detail and direction to give, in any format (other markdown files, PDF files, images), you can simply instruct Claude to read those files and use them in formulating the plan.
##  3\. Deploy and Test 
When you're at the point of completion where you need to try the plugin yourself, run:
    ```text
    /cpa:deploy
    ```
CPA validates the plugin, bumps the version, deploys it to your Canvas instance, and starts log monitoring so you can see output in real time.
To test our example first plugin, open a patient chart in your Canvas instance, create a new note, and click the button in the note header. You should see a Reason for Visit command appear with the text "hello world".
##  4\. Next Steps: Keep Iterating in Conversation with Claude 
The real power of AI-assisted development is iterating. Now that your plugin is deployed, enhance it with follow-up prompts:
###  Make it dynamic and patient-specific 
Ask CPA to update the plugin so the RFV text follows the classic clinical one-liner format, pulling patient data dynamically from the Canvas data module:
> Update the plugin so instead of "hello world", the RFV text is a clinical one-liner: "{patient first and last name} is a {age} year old {sex} presenting with ___". Pull the patient data dynamically.
###  Handle existing RFV 
Ask CPA to handle the case where the note already has a Reason for Visit command — editing the existing one instead of creating a duplicate:
> Update the plugin to check if the note already has a Reason for Visit command. If it does, edit the existing one instead of creating a new one.
###  Ask Claude to check logs and troubleshoot 
The `/cpa:deploy` command will start a subagent called `deploy-uat`, which runs a background task to access the `canvas logs` stream. Ask Claude to look at them anytime you need help troubleshooting. You can also of course view logs in the shell manually with:
    ```bash
    uv run canvas logs <your-instance>
    ```
###  Keep going 
Continue exploring the [SDK documentation](/sdk/) and browse other [guides](/guides/) to see what's possible with Canvas plugins. When you're ready to harden your plugin for production, run `/cpa:coverage` to check test coverage and improve tests, `/cpa:security-review` to audit for common security issues, and `/cpa:database-performance-review` to ensure efficient data retrieval. When you feel everything is ready to finalize, use the `/cpa:wrap-up` command.

---

# Your First Plugin (Manual)

Source: https://docs.canvasmedical.com/guides/your-first-plugin/

Plugins are your tool for customizing the Canvas experience. By using the modules of the Canvas SDK, you can react to [events](/sdk/events/) emitted from the EHR, request additional [data](/sdk/data/) if needed, and respond with [effects](/sdk/effects/) that alter workflows and add or change data in Canvas. You can also use [utils](/sdk/utils/) to do things like call out to web services with our provided HTTP client.
> **Warning:** This guide is for manual coding. Want a faster, AI-assisted approach? Check out [Your First Plugin (with Claude Code)](/guides/your-first-plugin-with-claude-code/), which uses an AI assistant to guide you through building and deploying your plugin.
##  Video 
The video below showcases a Canvas engineer working through this guide step-by-step.
##  1\. Install the Canvas CLI 
To install the Canvas CLI, simply `pip install canvas`. Python 3.11–3.14 (`>=3.11, <3.15`) is required. You can find additional detail on the features of the Canvas CLI [here](/sdk/canvas_cli/).
##  2\. Sign in to Canvas Platform 
The Canvas CLI deploys plugins through [Canvas Platform](https://platform.canvasmedical.com). Sign in once on your machine:
    ```sh
    $ canvas login
    Signed in to https://platform.canvasmedical.com as you@example.com.
      Acme Health (acme): plugin prefix acme__
    ```
`canvas login` opens your browser and lists each organization you belong to with its plugin prefix. Every plugin you publish is named with that prefix, such as `acme__paperwork_eviscerator`. Publishing a plugin needs the Plugin developer role in the organization, and deploying it needs Deploy manager.
Run `canvas whoami` at any time to check which platform you are signed in to and as whom. If you run `canvas init` while signed out, it says so and creates a plugin that `canvas deploy` refuses, so sign in first.
> **Info:** Configuring the CLI with OAuth client credentials in `~/.canvas/credentials.ini` is deprecated, and support ends on December 14, 2026. See [Moving to Canvas Platform](/guides/moving-to-canvas-platform/).
##  3\. Initialize a new plugin 
The Canvas CLI gives you a great head start when creating a plugin. Simply run `canvas init`, and answer the prompt to name your plugin.
    ```sh
    $ canvas init
      [1/1] project_name (My Cool Plugin): Paperwork Eviscerator
    Project created in /Users/andrew/src/canvas-plugins/paperwork-eviscerator
    Registered acme__paperwork_eviscerator with Canvas Platform.
    ```
This output shows the location of our freshly generated plugin project. `canvas init` names the package with your organization's prefix, registers it with Canvas Platform, and makes the project folder a git repository that `canvas deploy` pushes to. If you belong to several organizations, it asks which one publishes the plugin.
##  4\. Navigate the structure of a plugin 
Let's take a look at what was generated for us.
    ```sh
    $ tree paperwork-eviscerator/
    paperwork-eviscerator/
    ├── acme__paperwork_eviscerator
    │    ├── CANVAS_MANIFEST.json
    │    ├── OVERVIEW.md
    │    ├── README.md
    │    └── handlers
    │         ├── __init__.py
    │         └── event_handlers.py
    ├── pyproject.toml
    └── tests
        ├── __init__.py
        └── test_models.py
    5 directories, 10 files
    ```
###  CANVAS_MANIFEST.json 
The CANVAS_MANIFEST.json is particularly important. It is used during the installation of the plugin. See the [Canvas Manifest](/sdk/canvas_manifest/) reference for every field it can contain.
    ```json
    {
        "sdk_version": "0.1.4",
        "plugin_version": "0.0.1",
        "name": "acme__paperwork_eviscerator",
        "description": "Edit the description in CANVAS_MANIFEST.json",
        "components": {
            "handlers": [
                {
                    "class": "acme__paperwork_eviscerator.handlers.event_handlers:Handler",
                    "description": "A handler that does xyz...",
                    "data_access": {
                        "event": "",
                        "read": [],
                        "write": []
                    }
                }
            ],
            "commands": [],
            "content": [],
            "effects": [],
            "views": []
        },
        "variables": [
            {"name": "my_secret_code", "sensitive": true}
        ],
        "tags": {},
        "references": [],
        "license": "",
        "diagram": false,
        "readme": "./README.md"
    }
    ```
The name, plugin version, and description are all surfaced in your Canvas instance when viewing installed plugins.
Only handlers declared here are invoked by the plugin runner. If they are not declared, they will be ignored.
Secrets can be declared (though not defined) here. Any secrets declared here will be initialized on plugin install, and can be set with [`canvas config set`](/sdk/canvas_cli/#canvas-config-set).
###  README.md 
Share details about the purpose of your plugins and how it works in this README file.
###  OVERVIEW.md 
This file is the overview on your plugin's page in the Canvas Platform plugin catalog, written for the person deciding whether to install it. Canvas Platform renders it as markdown. Delete it to leave the plugin without an overview. See [Catalog](/sdk/canvas_manifest/#catalog) in the Canvas Manifest reference.
###  handlers/event_handlers.py 
This file contains the handler class declared in the manifest file. We've included some sample content and copious comments for inspiration.
    ```python
    from canvas_sdk.events import EventType
    from canvas_sdk.handlers import BaseHandler
    from logger import log
    # Inherit from BaseHandler to properly get registered for events
    class Handler(BaseHandler):
        """
        You should put a helpful description of this handler's behavior here.
        """
        # Name the event type you wish to run in response to
        RESPONDS_TO = EventType.Name(EventType.ASSESS_COMMAND__CONDITION_SELECTED)
        NARRATIVE_STRING = "I was inserted from my plugin's handler."
        def compute(self):
            """
            This method gets called when an event of the type RESPONDS_TO is fired.
            """
            # This class is initialized with several pieces of information you can
            # access.
            #
            # `self.event` is the event object that caused this method to be
            # called.
            #
            # `self.target` is an identifier for the object that is the subject of
            # the event. In this case, it would be the identifier of the assess
            # command. If this was a patient create event, it would be the
            # identifier of the patient. If this was a task update event, it would
            # be the identifier of the task. Etc, etc.
            #
            # `self.context` is a python dictionary of additional data that was
            # given with the event. The information given here depends on the
            # event type.
            #
            # `self.secrets` is a python dictionary of the secrets you defined in
            # your CANVAS_MANIFEST.json and set values for in the uploaded
            # plugin's configuration page: <emr_base_url>/admin/plugin_io/plugin/<plugin_id>/change/
            # Example: self.secrets['WEBHOOK_URL']
            # You can log things and see them using the Canvas CLI's log streaming
            # function.
            log.info(self.NARRATIVE_STRING)
            # Craft a payload to be returned with the effect(s).
            payload = {
                "note": {"uuid": self.context["note"]["uuid"]},
                "data": {"narrative": self.NARRATIVE_STRING},
            }
            # Return zero, one, or many effects.
            # Example:
            # return [Effect(type=EffectType.LOG, payload=json.dumps(payload))]
            return []
    ```
##  5\. Listen for an Event 
Set the `RESPONDS_TO` value to the [Event Type](/sdk/events/#event-types-and-context) you're interested in.
##  6\. Return an Effect 
Form an [Effect](/sdk/effects/#effect-types) to return to your Canvas instance.
##  7\. Deploy and use your plugin 
When your plugin is just the way you'd like it, validate it and deploy it. Navigate to the root of your plugin project (i.e. `paperwork-eviscerator/`) and run:
    ```sh
    $ canvas validate acme__paperwork_eviscerator
    $ canvas deploy acme__paperwork_eviscerator --instance buttered-popcorn-dev
    ```
`canvas deploy` commits your changes after you confirm, pushes them to Canvas Platform, and deploys that commit to the instance, where the plugin is installed and enabled. Replace `buttered-popcorn-dev` with your instance; without `--instance`, `deploy` targets the only instance you can deploy to, or lists the choices. As you make changes to your plugin, run the same command to deploy the new code.
##  8\. Tail the logs 
To view logs and to surface any errors with your plugin, run `canvas logs --host buttered-popcorn-dev` (replace with your Canvas instance name). This will tail the logs for all plugins installed on that instance.
`canvas logs` connects to the instance with the [instance API credentials](/sdk/canvas_cli/#instance-api-credentials-credentialsini-deprecated) in `~/.canvas/credentials.ini` until it moves to your Canvas Platform sign-in, before December 14, 2026.

---

# EHI Export

Source: https://docs.canvasmedical.com/documentation/ehi-export/

Canvas supports the **export of electronic health information (EHI)** based on FHIR Bulk Data Access.
##  Creating a Single Patient Export 
###  In the UI 
To generate a single patient export, navigate to `Fhir bulk data exports` in your admin settings.
Click on `ADD FHIR BULK DATA EXPORT` to pull up the tool. Select the appropriate Oauth application from the dropdown. These are typically created by your team as a part of implementation. Support can also help to create one if needed. Export type defaults to 'Patient'. Search for the patient and click `Start Export`.
The export will generate links to the output files for each resource. Clicking each will download the files locally.
> **Warning:** This functionality is permission based. If you do not have access and need it, please reach out to your internal administrators. They can work with our support team to ensure the permissions are assigned to the necessary groups.
###  Using the API 
You can initiate a single patient export by issuing a request like the one below:  
`GET https://fumage-<instance-name>.canvasmedical.com/Patient/<id>/$export`
The export can read only what the token that started it can read. It uses that token's scopes and, for a [patient scoped token](/api/customer-authentication/#patient-scoped-tokens), its patient. The token must be unexpired when you send the request.
##  Creating a Population Export 
Canvas also supports exporting EHI for a group of patients or all patients. To request an export, please contact [support](https://portal.usepylon.com/canvas-medical/forms/standard) and provide the following information:
  - Your instance name (the url of your instance)
  - Your username
  - Your role
  - The group of patients, or specify all patients
  - The purpose of the export.
> **Info:** Please note that population exports may take a significant time to process depending on the amount of data in your instance.
The Canvas team can initiate the bulk export on your behalf. The output will be availble within the `ADD FHIR BULK DATA EXPORT` table.
##  Format 
EHI is exported as standard FHIR R4 resources in Newline Delimited JSON format, as outlined by the [FHIR Bulk Data Access pattern](https://hl7.org/fhir/uv/bulkdata/STU1.0.1/).   
###  Resources 
The resources in scope for the response are:
  - The patient resource itself.
  - Any resource that is associated with the patient.
The table below lists the Canvas resources included in the patient recordset:
Resource  
---  
[AllergyIntolerance](/api/allergyintolerance)  
[Appointment](/api/appointment)  
[CarePlan](/api/careplan)  
[CareTeam](/api/careteam)  
[Claim](/api/claim)  
[Communication](/api/communication)  
[Condition](/api/condition)  
[Consent](/api/consent)  
[Coverage](/api/coverage)  
[CoverageEligibilityResponse](/api/coverageeligibilityresponse)  
[Device](/api/device)  
[DiagnosticReport](/api/diagnosticreport)  
[DocumentReference](/api/documentreference)  
[Encounter](/api/encounter)  
[Goal](/api/goal)  
[Immunization](/api/immunization)  
[Media](/api/media)  
[MedicationDispense](/api/medicationdispense)  
[MedicationRequest](/api/medicationrequest)  
[MedicationStatement](/api/medicationstatement)  
[Observation](/api/observation)  
[Patient](/api/patient)  
[Procedure](/api/procedure)  
[Provenance](/api/provenance)  
[QuestionnaireResponse](/api/questionnaireresponse)  
[RelatedPerson](/api/relatedperson)  
[ServiceRequest](/api/servicerequest)  
[Specimen](/api/specimen)  
[Task](/api/task)

---