Patient

Last updated: 1 Sep 2026

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:

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:

from canvas_sdk.v1.data.patient import Patient

patients = Patient.objects.filter(first_name="Bob", last_name="Loblaw", birth_date="1960-09-22")

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.

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 the original url or title), use the photo property:

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)

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:

from canvas_sdk.v1.data.patient import Patient

patient = Patient.objects.get(id="d7af3e356368446c85b40a5d6ff7288e")
educational_materials = patient.education_material.all()

Attributes #

Patient #

Field Name	Type
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[]
billing_line_items	BillingLineItem
business_line	BusinessLine
care_team_memberships	CareTeamMembership[]
change_medications	ChangeMedication[]
conditions	Condition[]
coverages	Coverage[]
dependent_coverages	Coverage[]
detected_issues	DetectedIssue[]
devices	Device[]
external_identifiers	PatientExternalIdentifier[]
identification_cards	PatientIdentificationCard[]
imaging_orders	ImagingOrder[]
imaging_results	ImagingReport[]
imaging_reviews	ImagingReview[]
interviews	Interview[]
lab_orders	LabOrder[]
lab_reports	LabReport[]
lab_reviews	LabReview[]
medications	Medication[]
metadata	PatientMetadata[]
observations	Observation[]
photos	PatientPhoto[]
preferred_pharmacy	JSON
preferred_pharmacies	JSON
protocol_overrides	ProtocolOverride[]
settings	PatientSetting
subscribed_coverages	Coverage[]
tasks	Task[]
telecom	PatientContactPoint[]
contacts	PatientContactPerson[]
related_contacts	PatientContactPerson[] — contacts on other patients that reference this one
user	CanvasUser[]
patient_groups	PatientGroup[]
chart_section_reviews	ChartSectionReview[]
visual_exam_findings	VisualExamFinding[]
vital_sign_readings	VitalSignReading[]
assessments	Assessment[]
patient_visits	ExternalVisit[]
patient_events	ExternalEvent[]
medication_statements	MedicationStatement[]
diagnostic_reports	DiagnosticReport[]
medication_history_medications	MedicationHistoryMedication[]
medication_history_responses	MedicationHistoryResponse[]
payments	BulkPatientPosting[]
protocol_currents	ProtocolCurrent[]
stopped_medications	StopMedicationEvent[]
banner_alerts	BannerAlert[]
immunizations	Immunization[]
immunization_statements	ImmunizationStatement[]
integration_tasks	IntegrationTask[]
installment_plans	InstallmentPlan[]
uncategorized_clinical_document_reviews	UncategorizedClinicalDocumentReview[]
patient_consent	PatientConsent[]
goals	Goal[]
updategoals	UpdateGoal[]
instructions	Instruction[]
appointments	Appointment[]
notes	Note[]
prescriptions	Prescription[]
refill_requests	RefillRequest[]
referral_reviews	ReferralReview[]
referral_reports	ReferralReport[]
invoices	Invoice[]
education_material	EducationalMaterial[]
procedures	Procedure[]
family_histories	FamilyHistory[]
histories_of_present_illness	HistoryOfPresentIllness[]
plans	Plan[]
follow_ups	FollowUp[]
reasons_for_visit	ReasonForVisit[]
removed_allergies	RemoveAllergyEvent[]
resolved_conditions	ResolveConditionEvent[]

PatientAddress #

Field Name	Type
id	UUID
dbid	Integer
line1	String
line2	String
city	String
district	String
state_code	String
postal_code	String
use	AddressUse
type	AddressType
longitude	Float
latitude	Float
start	Date
end	Date
country	String
state	AddressState
patient	Patient

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
system	ContactPointSystem
value	String
use	String
use_notes	String
rank	Integer
state	ContactPointState
patient	Patient
has_consent	Boolean
last_verified	DateTime
verification_token	String
opted_out	Boolean

from canvas_sdk.v1.data.patient import Patient
from logger import log

patient_id = "d7af3e356368446c85b40a5d6ff7288e"
patient = Patient.objects.get(id=patient_id)
patient_contacts = patient.telecom.all()

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

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

PatientMetadata #

Field Name	Type
id	UUID
dbid	Integer
created	DateTime
modified	DateTime
patient	Patient
key	String
value	String

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	String
title	String

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

PatientIdentificationCard #

Represents a patient identification card image (e.g., driver’s license, insurance card).

Field Name	Type
dbid	Integer
created	DateTime
modified	DateTime
patient	Patient
image	String
title	String
active	Boolean
image_url	String (property) — presigned S3 URL

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 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[]

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. 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
name	String
code	String
system	String
protected	Boolean

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

Computed Properties #

Patient #

• full_name: The full name of the patient, combining first, middle, and last names.
• preferred_pharmacy: The patient’s preferred pharmacy for medication fulfillment.
• preferred_full_name: The patient’s preferred full name, if different from the legal name.
• preferred_first_name: The patient’s preferred first name, if different from the legal first name.
• primary_phone_number: The patient’s primary contact number.
• photo: The patient’s first uploaded avatar PatientPhoto, if any.
• photo_url: A presigned URL for the patient’s avatar photo, or the default avatar URL when no photo is set.