Patient

Last updated: 20 May 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)

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[]
conditions	Condition[]
coverages	Coverage[]
dependent_coverages	Coverage[]
detected_issues	DetectedIssue[]
devices	Device[]
external_identifiers	PatientExternalIdentifier[]
identification_cards	PatientIdentificationCard[]
imaging_orders	ImagingOrder[]
imaging_reports	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
protocol_overrides	ProtocolOverride[]
settings	PatientSetting
subscribed_coverages	Coverage[]
tasks	Task[]
telecom	PatientContactPoint[]
user	CanvasUser[]
patient_groups	PatientGroup[]

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

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.