Patient Facility Address

Last updated: 5 Oct 2026

The PatientFacilityAddress effect enables the creation, updating, and deletion of patient facility address records within Canvas. Patient facility addresses link patients to healthcare facilities, with optional room number information. The address details are automatically populated from the linked facility.

You can either reference an existing facility by ID, or create a new facility inline by providing the facility details.

Build a PatientFacilityAddress with the attributes you want to set, then return one of its methods from your handler: create(), update(), or delete().

Methods #

create() → Effect #

Creates a patient facility address.

patient_id is required, and must be the id of an existing patient.
Supply either facility_id for an existing facility, or the fields to create a new facility (facility_name, facility_city, facility_state_code, and facility_postal_code), but not both. See Facility Reference Options.
id must not be set.

update() → Effect #

Updates an existing patient facility address.

id is required, and must be the id of an existing patient facility address.

delete() → Effect #

Deletes an existing patient facility address.

id is required, and must be the id of an existing patient facility address.

Attributes #

Attribute	Type	Description	Required
`id`	`str` or `UUID`	ID of the patient facility address	For `update()` and `delete()`
`patient_id`	`str` or `UUID`	ID of the patient	For `create()`
`facility_id`	`str` or `UUID`	ID of an existing facility to link	For `create()`, unless creating a new facility
`facility_name`	`str`	Name of new facility to create	When creating a new facility
`facility_npi_number`	`str`	NPI number for new facility	No
`facility_phone_number`	`str`	Phone number for new facility	No
`facility_fax_number`	`str`	Fax number for new facility	No
`facility_active`	`bool`	Whether the new facility is active	No
`facility_line1`	`str`	Street address line 1 for new facility	No
`facility_line2`	`str`	Street address line 2 for new facility	No
`facility_city`	`str`	City for new facility	When creating a new facility
`facility_district`	`str`	District for new facility	No
`facility_state_code`	`str`	State code for new facility (e.g., “CA”, “NY”)	When creating a new facility
`facility_postal_code`	`str`	Postal code for new facility	When creating a new facility
`room_number`	`str`	Room number at the facility	No
`address_type`	`AddressType` or `str`	Type of address: “physical” or “both”. Defaults to “physical”.	No

Facility Reference Options #

When creating a patient facility address, you must either:

Reference an existing facility by providing facility_id
Create a new facility inline by providing facility creation fields (facility_name, facility_city, facility_state_code, facility_postal_code)

Required Fields for Inline Facility Creation #

When creating a new facility inline, the following fields are required:

facility_name
facility_city
facility_state_code
facility_postal_code

Address Type #

The address_type field accepts the following values:

Value	Description
`physical`	Physical/street address (default)
`both`	Both physical and mailing address

Validation #

The effect validates:

Create: patient_id is required and must reference an existing patient
Create: Either facility_id or facility creation fields must be provided (not both)
Create: If facility_id is provided, it must reference an existing facility
Create: If creating a new facility, all required facility fields must be provided
Update/Delete: id is required and must reference an existing patient facility address
Update: If updating facility, same rules apply as create (facility_id OR creation fields)
address_type must be “physical” or “both” if provided

Example Usage #

Creating with Existing Facility #

from canvas_sdk.effects.patient_facility_address import PatientFacilityAddress, AddressType
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        effect = PatientFacilityAddress(
            patient_id="patient-uuid-here",
            facility_id="facility-uuid-here",
            room_number="101A",
            address_type=AddressType.PHYSICAL,
        )
        return [effect.create()]

Creating with New Facility #

from canvas_sdk.effects.patient_facility_address import PatientFacilityAddress, AddressType
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        effect = PatientFacilityAddress(
            patient_id="patient-uuid-here",
            facility_name="Downtown Medical Center",
            facility_line1="123 Main Street",
            facility_line2="Suite 400",
            facility_city="Boston",
            facility_state_code="MA",
            facility_postal_code="02101",
            facility_phone_number="617-555-1234",
            facility_npi_number="1234567890",
            room_number="Room 205",
            address_type=AddressType.PHYSICAL,
        )
        return [effect.create()]

Updating an Existing Address #

from canvas_sdk.effects.patient_facility_address import PatientFacilityAddress
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        # Update to use a different existing facility
        effect = PatientFacilityAddress(
            id="existing-address-uuid",
            facility_id="new-facility-uuid",
            room_number="202B",
        )
        return [effect.update()]

Deleting an Address #

from canvas_sdk.effects.patient_facility_address import PatientFacilityAddress
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        effect = PatientFacilityAddress(
            id="existing-address-uuid",
        )
        return [effect.delete()]

Notes #

The address details (line1, line2, city, state, country, postal_code) displayed for a patient facility address are automatically populated from the linked facility’s address information.
When a facility’s address is updated, all linked patient facility addresses are automatically updated to match. This synchronization happens asynchronously and applies to line1, line2, city, district, state_code, postal_code, and country fields. Non-address changes to the facility (such as name, NPI number, or phone number) do not trigger this cascade.
When creating a new facility inline, the facility is created first, then linked to the patient facility address.
Room number is optional and can be used to specify the patient’s specific room within the facility.