Claim

Last updated: 2 Oct 2026

Introduction #

This module defines the data models used to manage healthcare claim workflows.

Basic usage #

To retrieve a claim by its identifier:

from canvas_sdk.v1.data.claim import Claim

claim = Claim.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130003")

To access diagnosis codes for a claim:

from canvas_sdk.v1.data.claim import Claim

claim = Claim.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130003")
diagnosis_codes = claim.diagnosis_codes.all().order_by("rank")

for diagnosis in diagnosis_codes:
    print(f"Rank {diagnosis.rank}: {diagnosis.code} - {diagnosis.display}")

To access banner alerts for a claim:

from canvas_sdk.v1.data.claim import Claim

claim = Claim.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130003")
active_alerts = claim.banner_alerts.filter(status="active")

for alert in active_alerts:
    print(f"[{alert.intent}] {alert.narrative}")

When a claim is created #

A claim is created for an appointment or note only when the note’s type is billable. A note type with is_billable set to False, such as the built-in Chart review type, produces a note and no claim, so check the flag rather than assuming every appointment produces a claim.

The flag lives on NoteType, reached through the note’s note_type_version attribute. To read the claim itself, call the note’s get_claim() method, which returns the note’s most recent claim, or None when it has none:

from canvas_sdk.v1.data.note import Note

note = Note.objects.get(id="89992c23-c298-4118-864a-26cb3e1ae822")

expects_claim = note.note_type_version.is_billable
claim = note.get_claim()

Claim balances and totals #

The money on a claim comes from two stored balance fields plus a set of computed properties layered over the claim’s line items and postings.

patient_balance and aggregate_coverage_balance are stored on the claim and kept in sync by signals as coverage postings transfer money to the patient, as coverage is added or removed, and as the patient makes payments. Reading them needs no aggregation on your part, and they stay correct when coverage is added after a note is signed.

The rest are computed on access, each over a different slice of the claim:

Property	What it adds up
total_charges	charge across the claim’s active line items, with copay and unlinked items excluded
total_paid	paid_amount across every active posting on the claim, coverage and patient alike
total_payer_paid	paid_amount across the active postings of the claim’s active coverages
total_patient_paid	paid_amount across the active postings on the claim’s patient record
total_adjusted	contractual_adjusted_amount plus transferred_amount across every active posting
balance	aggregate_coverage_balance plus patient_balance, the coverage side and the patient side together

A posting counts as active when it has not been entered in error. Because total_paid spans both sides of the claim, total_payer_paid and total_patient_paid are that figure split by who paid it.

Computing patient-allocated charges #

To find how much has been allocated to the patient on a claim, add what the patient still owes to what they have already paid:

from canvas_sdk.v1.data.claim import Claim

claim = Claim.objects.get(id="9d2e0f58-338b-11ec-8d3d-0242ac130003")

patient_allocated = claim.patient_balance + claim.total_patient_paid

This holds for self-pay and insured claims alike, including a self-pay claim carrying no postings at all.

Filtering #

from canvas_sdk.v1.data.claim import Claim

# Active claims only
active_claims = Claim.objects.active()

Attributes #

Claim #

Represents a complete healthcare claim. Claim belongs to a Note and has a one-to-one relationship with a ClaimPatient.

Field Name	Type	Description
id	UUID
dbid	Integer
note	Note
installment_plan	InstallmentPlan
current_queue	ClaimQueue
current_coverage	ClaimCoverage
accept_assign	Boolean
auto_accident	Boolean
auto_accident_state	String
employment_related	Boolean
other_accident	Boolean
accident_code	String
illness_date	Date
remote_batch_id	String
remote_file_id	String
prior_auth	String
narrative	String
account_number	String
snoozed_until	Date
patient_balance	Decimal
aggregate_coverage_balance	Decimal
created	DateTime
modified	DateTime
diagnosis_codes	ClaimDiagnosisCode[]
comments	ClaimComment[]
line_items	ClaimLineItem[]
labels	TaskLabel[]
metadata	ClaimMetadata[]
banner_alerts	ClaimBannerAlert[]
provider	ClaimProvider
incident_to	Boolean
supervising_provider	ClaimSupervisingProvider
latest_invoice	Invoice
patient	ClaimPatient
coverages	ClaimCoverage[]
submissions	ClaimSubmission[]
postings	BasePosting[]
total_charges	Decimal (computed)	Total charges for active line items
total_paid	Decimal (computed)	Sum of paid amounts from postings
total_adjusted	Decimal (computed)	Sum of adjustments and transfers
balance	Decimal (computed)	Remaining balance (coverage plus patient)
total_patient_paid	Decimal (computed)	Amount paid by the patient
total_payer_paid	Decimal (computed)	Amount paid by coverages

Helpful Methods:

• get_coverage_by_payer_id(payer_id: str, subscriber_number: str | None = None): Finds the active coverage associated with a payer_id. Optionally checks if the subscriber_number matches, which will choose the correct coverage in the case where a patient has two coverages with the same payer_id.

ClaimSupervisingProvider #

An immutable snapshot of a claim’s supervising provider (837P loop 2310D), captured at claim creation from the note’s supervising provider and frozen thereafter, so later edits to the note or the underlying Staff record do not retroactively change a submitted claim.

Field Name	Type
id	UUID
dbid	Integer
claim	Claim
staff	Staff
first_name	String
last_name	String
middle_name	String
npi	String
taxonomy	String
tax_id	String
tax_id_type	TaxIDType
created	DateTime
modified	DateTime

ClaimLineItem #

Represents individual billed procedures or services tied to a claim.

Field Name	Type
id	UUID
dbid	Integer
billing_line_item	BillingLineItem
diagnosis_codes	ClaimLineItemDiagnosisCode[]
modifiers	ClaimLineItemModifier[]
claim	Claim
status	ClaimLineItemStatus
charge	Decimal
from_date	String
thru_date	String
narrative	String
ndc_code	String
ndc_dosage	String
ndc_measure	String
place_of_service	PracticeLocationPOS
proc_code	String
display	String
remote_chg_id	String
units	Integer
epsdt	String
family_planning	FamilyPlanningOptions
created	DateTime
modified	DateTime
newlineitempayments	QuerySet[NewLineItemPayment]
newlineitemadjustments	QuerySet[NewLineItemAdjustment]
lineitemtransfers	QuerySet[LineItemTransfer]

ClaimLineItemDiagnosisCode #

Represents a diagnosis code for a given ClaimLineItem. There exists one ClaimLineItemDiagnosisCode for each ClaimDiagnosisCode, and the “linked” attribute indicates whether or not the diagnosis code is linked to the line item.

Field Name	Type
id	UUID
dbid	Integer
line_item	ClaimLineItem
claim_diagnosis_code	ClaimDiagnosisCode
code	String
poa	String
linked	Boolean
created	DateTime
modified	DateTime

ClaimLineItemModifier #

Represents a modifier code for a given ClaimLineItem.

Field Name	Type
id	UUID
dbid	Integer
line_item	ClaimLineItem
modifier	String
created	DateTime
modified	DateTime

ClaimCoverage #

Links a claim to a specific insurance coverage.

Field Name	Type
id	UUID
dbid	Integer
claim	Claim
coverage	Coverage
active	Boolean
payer_name	String
payer_id	String
payer_typecode	String
payer_order	ClaimPayerOrder
payer_addr1	String
payer_addr2	String
payer_city	String
payer_state	String
payer_zip	String
payer_plan_type	ClaimTypeCode
coverage_type	CoverageType
subscriber_employer	String
subscriber_group	String
subscriber_number	String
subscriber_plan	String
subscriber_dob	String
subscriber_first_name	String
subscriber_last_name	String
subscriber_middle_name	String
subscriber_phone	String
subscriber_sex	PersonSex
subscriber_addr1	String
subscriber_addr2	String
subscriber_city	String
subscriber_state	String
subscriber_zip	String
subscriber_country	String
patient_relationship_to_subscriber	CoverageRelationshipCode
pay_to_addr1	String
pay_to_addr2	String
pay_to_city	String
pay_to_state	String
pay_to_zip	String
resubmission_code	String
payer_icn	String
created	DateTime
modified	DateTime

ClaimComment #

Represents a free-text comment made on a Claim.

Field Name	Type
id	UUID
dbid	Integer
claim	Claim
created	DateTime
modified	DateTime
originator	CanvasUser
entered_in_error	CanvasUser
committer	CanvasUser
comment	String

ClaimBannerAlert #

Represents banner alerts associated with a claim. Banner alerts are displayed in the UI to surface important information about a claim. To create or remove ClaimBannerAlert records, see Claim Effects.

Field Name	Type
id	UUID
dbid	Integer
claim	Claim
plugin_name	String
key	String
narrative	String
intent	BannerAlertIntent
href	String
status	BannerAlertStatus
created	DateTime
modified	DateTime

ClaimDiagnosisCode #

Represents diagnosis codes associated with a claim, ordered by rank.

Field Name	Type
id	UUID
dbid	Integer
claim	Claim
line_item_diagnosis_codes	ClaimLineItemDiagnosisCode[]
rank	Integer
code	String
display	String
created	DateTime
modified	DateTime

ClaimQueue #

Defines the metadata for claim queues used in revenue workflows.

Field Name	Type
id	UUID
dbid	Integer
queue_sort_ordering	Integer
name	String
display_name	String
description	String
show_in_revenue	Boolean
visible_columns	Array[ClaimQueueColumns]
created	DateTime
modified	DateTime

ClaimPatient #

Captures patient-level data related to a specific claim.

Field Name	Type
dbid	Integer
claim	Claim
photo	String
dob	String
first_name	String
last_name	String
middle_name	String
phone	String
sex	PersonSex
ssn	String
addr1	String
addr2	String
city	String
state	String
zip	String
country	String
created	DateTime
modified	DateTime

ClaimLabel #

Represents labels assigned to the claim.

Field Name	Type
id	UUID
dbid	Integer
claim	Claim
label	TaskLabel

ClaimMetadata #

Represents key-value metadata associated with a claim. Each claim-key pair is unique.

Field Name	Type
id	UUID
dbid	Integer
claim	Claim
key	String
value	String
created	DateTime
modified	DateTime

ClaimProvider #

Captures provider-level data related to a specific claim.

Field Name	Type
id	UUID
dbid	Integer
claim	Claim
clia_number	String
billing_provider_name	String
billing_provider_phone	String
billing_provider_addr1	String
billing_provider_addr2	String
billing_provider_city	String
billing_provider_state	String
billing_provider_zip	String
billing_provider_id	String
billing_provider_npi	String
billing_provider_tax_id	String
billing_provider_tax_id_type	String
billing_provider_taxonomy	String
provider_id	String
provider_first_name	String
provider_last_name	String
provider_middle_name	String
provider_npi	String
provider_tax_id	String
provider_tax_id_type	String
provider_taxonomy	String
provider_ptan_identifier	String
provider_addr1	String
provider_addr2	String
provider_city	String
provider_state	String
provider_zip	String
referring_provider_id	String
referring_provider_first_name	String
referring_provider_last_name	String
referring_provider_middle_name	String
referring_provider_npi	String
referring_provider_ptan_identifier	String
ordering_provider_first_name	String
ordering_provider_last_name	String
ordering_provider_middle_name	String
ordering_provider_npi	String
facility_id	String
facility_name	String
facility_npi	String
facility_addr1	String
facility_addr2	String
facility_city	String
facility_state	String
facility_zip	String
hosp_from_date	String
hosp_to_date	String
created	DateTime
modified	DateTime

ClaimSubmission #

Captures clearinghouse submission details about a claim.

Field Name	Type
id	UUID
dbid	Integer
created	DateTime
modified	DateTime
claim	Claim
coverage	ClaimCoverage
clearinghouse_claim_id	String
claim_index	Integer

InstallmentPlan #

Represents a payment plan between a patient and provider.

Field Name	Type
dbid	Integer
creator	CanvasUser
patient	Patient
total_amount	Decimal
status	InstallmentPlanStatus
expected_payoff_date	Date
created	DateTime
modified	DateTime
claims	Claim[]

Enumeration types #

ClaimLineItemStatus #

Value	Label
active	Active
removed	Removed

LineItemCodes #

Value
COPAY
UNLINKED

FamilyPlanningOptions #

Value	Label
Y	Yes
N	No

ClaimLineItemStatus #

Value	Label
active	Active
removed	Removed

LineItemCodes #

Value
COPAY
UNLINKED

FamilyPlanningOptions #

Value	Label
Y	Yes
N	No

ClaimPayerOrder #

Value	Label
Primary	Primary
Secondary	Secondary
Tertiary	Tertiary
Quaternary	Quaternary
Quinary	Quinary

ClaimTypeCode #

Code	Description
12	Working Aged (Age 65 or older)
13	End-Stage Renal Disease
14	No-fault
15	Workers Compensation
41	Black Lung
42	Veterans Administration
43	Disabled (Under Age 65)
47	Other Liability Insurance is primary
””	No Typecode necessary

ClaimQueueColumns #

Value	Label
NoteType	Note type
ClaimID	Claim ID
DateOfService	Date of service
Patient	Patient
ActiveInsurance	Active insurance
InsuranceBalance	Insurance balance
PatientBalance	Patient balance
DaysInQueue	Days in queue
Provider	Provider
Guarantor	Guarantor
LatestRemit	Latest remit
LastInvoiced	Last invoiced
SnoozedUntil	Snoozed until
Labels	Labels

ClaimQueues #

Value	Label
1	Appointment
2	NeedsClinicianReview
3	NeedsCodingReview
4	QueuedForSubmission
5	FiledAwaitingResponse
6	RejectedNeedsReview
7	AdjudicatedOpenBalance
8	PatientBalance
9	ZeroBalance
10	Trash

InstallmentPlanStatus #

Value	Label
active	Active
completed	Completed
cancelled	Cancelled