CareTeam

Last updated: 25 Jun 2026

Introduction #

The CareTeam model represents a collection of Staff that are responsible for the care of a 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:

>>> 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 instance can be used:

>>> 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 on the Canvas instance. An external membership has no staff. Instead, its organizational_entity links to an OrganizationalEntity that describes the external provider. When that entity is a ServiceProvider, 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.

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

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

>>> 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
system	String
version	String
code	String
display	String
user_selected	BooleanField
active	Boolean
care_teams	CareTeamMembership[]

CareTeamMembership #

Field Name	Type
id	UUID
dbid	Integer
created	DateTime
modified	DateTime
patient	Patient
staff	Staff
role	CareTeamRole
organizational_entity	OrganizationalEntity
status	CareTeamMembershipStatus
lead	Boolean
role_code	String
role_system	String
role_display	String

For external (non-staff) members, staff is empty and organizational_entity links to the external provider.

Properties #

Name	Type	Description
service_provider	ServiceProvider | None	The external provider for this membership, resolved through its organizational_entity; None for internal members.

Enumeration types #

CareTeamMembershipStatus #

Value	Label
proposed	Proposed
active	Active
suspended	Suspended
inactive	Inactive
entered-in-error	Entered in Error