Staff

Last updated: 2 Oct 2026

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:

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:

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, 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:

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:

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:

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.

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.

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.

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
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
npi_number	String
nadean_number	String
group_npi_number	String
bill_through_organization	Boolean
tax_id	String
tax_id_type	TaxIDType
spi_number	String
personal_meeting_room_link	URL
language	Language
language_secondary	Language
schedule_column_ordering	Integer
state	JSON
user	CanvasUser
signature	String
supervising_team	Staff[]
default_supervising_provider	Staff
notes	Note[]
supervised_notes	Note[]
creator_tasks	Task[]
assignee_tasks	Task[]
comments	TaskComment[]
care_team_memberships	CareTeamMembership[]
teams	Team[]
telecom	StaffContactPoint[]
external_identifiers	StaffExternalIdentifier[]
metadata	StaffMetadata[]
addresses	StaffAddress[]
photos	StaffPhoto[]
roles	StaffRole[]
licenses	StaffLicense[]
letters	Letter[]
imaging_orders	ImagingOrder[]
immunizations_given	Immunization[]
supervising_prescriptions	Prescription[]
refill_requests	RefillRequest[]
default_patients	Patient[]
medication_history_responses	MedicationHistoryResponse[]
transmissions_delivered	MessageTransmission[]
integration_task_reviews	IntegrationTaskReview[]
assignee_note_tasks	NoteTask[]
appointment_set	Appointment[]
prescription_set	Prescription[]
note_set	Note[]
prescription_change_requests	PrescriptionChangeRequest[]
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
value	String
use	String
use_notes	String
rank	Integer
state	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
type	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

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

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