Note

Last updated: 16 Jul 2025

Introduction #

The Note model represents clinical notes that appear on a patient’s chart. A Note can contain multiple commands.

Basic usage #

Retrieve a specific note #

To get a note by identifier, use the get method on the Note model manager:

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:

from canvas_sdk.v1.data.patient import Patient

patient = Patient.objects.get(id="fd2ecd87c26044a6a755287f296dd17f")
patient_notes = patient.notes.all()

Retrieve the audit history for a note #

The audit history for a note can be found using the NoteStateChangeEvent model. You can access this model directly or through the state_history relation on the note object.

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 model to check if the current note state is ‘Locked’. (See: NoteState for an explanation of the different note states you might encounter)

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

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)

from canvas_sdk.v1.data.note import Note, CurrentNoteStateEvent, NoteStates

open_note_states = [
    NoteStates.NEW,
    NoteStates.PUSHED,
    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 and check the state attribute.

from canvas_sdk.v1.data.note import Note, CurrentNoteStateEvent

note = Note.objects.first()

current_note_state = CurrentNoteStateEvent.objects.get(note=note).state

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:

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.

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)

All of the commands in a Note can be found by using the commands attribute:

from canvas_sdk.v1.data.note import Note

note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")
commands_in_note = Note.commands.all()

Attributes #

Note #

Field Name	Type	Notes
id	UUID
dbid	Integer
created	DateTime
modified	DateTime
patient	Patient
note_type_version	NoteType
title	String
body	JSON
originator	CanvasUser
provider	Staff
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

NoteType #

Field Name	Type
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

NoteStateChangeEvent #

Field Name	Type
id	UUID
dbid	Integer
created	DateTime
modified	DateTime
note	Note
originator	CanvasUser
state	NoteState
note_state_document	String
note_state_html	String

CurrentNoteStateEvent #

Field Name	Type
id	UUID
dbid	Integer
state	NoteState
note	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
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