Dental PMS

Clinical

144 endpoints

Clinical

40 endpoints

get/api/v1/{org_id}/clinical/conditions/{condition_uuid}

Get patient condition

Retrieve a single patient condition by UUID. Raises 404 if not found.

Parameters

Path Parameters
condition_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
condition_typeenumrequired

Type of condition. One of: caries, fracture, abscess, impaction, open_contact, diastema, abrasion, erosion, attrition, watch, periapical_lesion, periodontal, decalcification, defective_restoration, other.

abrasionabscessankylosisattritioncariesdecalcificationdefective_restorationdiastemadilacerationerosionfracturefracture_rootfusiongeminationhypoplasiaimpactionluxationmacrodontiamicrodontiaopen_contactotherperiapical_lesionperiodontalroot_resorption_externalroot_resorption_internalwatch
created_atstring (date-time)required

Record creation timestamp.

date_identifiedstring (date)required

Date the condition was identified.

date_resolvedstring (date)
diagnostic_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

idstring (uuid)required

UUID of the patient condition.

notestringrequired

Clinical note describing the condition.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

severityenum
mildmoderatesevere
statusenumrequired

Condition monitoring status. One of: active, resolved, monitoring.

activemonitoringresolved
surfacestring
tooth_numberstring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/conditions/{condition_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/estimates/{estimate_uuid}/detail

Get estimate breakdown detail

Get full estimation breakdown for a single procedure estimate. Returns the fee waterfall, benefit match details, coverage calculation steps, tracker state, and insurance plan context. If the estimate was created before the detail feature was added, returns has_detail=false. Raises 404 if estimate not found.

Parameters

Path Parameters
estimate_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
benefit_matchobject

Details about the benefit row that matched this procedure.

coverageobject

Step-by-step coverage calculation.

estimate_uuidstring (uuid)required

UUID of the procedure estimate.

exclusion_reasonstring
fee_sourceobject

Audit trail for how a fee was resolved.

has_detailbooleanrequired

True if calculation_detail is available. False for legacy estimates.

is_excludedboolean

True if the procedure is excluded from coverage.

plan_contextobject

Insurance plan context for the estimate detail sidebar.

substitution_codestring
trackerobject

Deductible and annual max tracker state before/after this procedure.

warningsstring[]

Pipeline warnings.

waterfallobject[]

Ordered fee/coverage waterfall steps.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/estimates/{estimate_uuid}/detail" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/chart/at-date

Get historical chart snapshot

Return a coherent snapshot of the full chart as it existed on a given date. Includes: - Tooth statuses: most recent effective record on or before snapshot_date per tooth - Charted procedures: all procedures with proc_date on or before snapshot_date - Patient conditions: conditions identified on or before snapshot_date that were not yet resolved NOTE: Procedure statuses reflect current values, not historical (scoped limitation §6.2). Raises 404 if the patient is not found. Raises 422 if the date parameter is missing or invalid.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
datestringrequired

Target date for the chart snapshot (YYYY-MM-DD).

Responses

200Successful Response
charted_proceduresobject[]required

Procedures charted on or before snapshot_date. NOTE: Procedure statuses reflect current values, not historical (scoped limitation §6.2).

patient_conditionsobject[]required

Conditions active on snapshot_date — identified on or before snapshot_date and not yet resolved at that date.

snapshot_datestring (date)required

The date for which this snapshot reflects chart state.

tooth_statusesobject[]required

Tooth statuses as they were on snapshot_date. Uses the most recent effective_date on or before snapshot_date per tooth.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/chart/at-date" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/chart/timeline

Get chart timeline events

Return a timeline of all dates with chart activity for a patient. Merges distinct dates from tooth status changes, charted procedures, and patient condition identifications. Each entry includes counts per data source for that date. Raises 404 if the patient is not found.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
eventsobject[]required

Timeline entries sorted chronologically, each representing a date with at least one chart change.

totalintegerrequired

Total number of distinct dates with chart activity.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/chart/timeline" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/conditions

List patient conditions

List patient conditions with optional filters. Raises 404 if the patient is not found.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
statusstring

Filter by condition status (e.g., active, resolved).

condition_typestring

Filter by condition type code.

tooth_numberstring

Filter by tooth number.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required
pageintegerrequired
page_sizeintegerrequired
totalintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/conditions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/procedures

List charted procedures

List charted procedures for a patient with optional filters. Raises 404 if the patient is not found.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
status"complete" | "complete_referred" | "existing_current" | "existing_other" | "in_progress" | "referred" | "scheduled" | "treatment_planned"

Filter by procedure status. One of: treatment_planned, scheduled, in_progress, complete, complete_referred, existing_current, existing_other, referred. Use treatment_planned for diagnosed services, pending treatment, planned procedures, and unscheduled treatment.

tooth_numberstring

Filter by tooth number.

date_fromstring

Filter procedures on or after this date.

date_tostring

Filter procedures on or before this date.

provider_uuidstring

Filter by rendering provider UUID.

procedure_codestring

Filter by procedure code prefix (e.g., 'D23').

treatment_area"arch" | "mouth" | "quadrant" | "sextant" | "tooth"

Filter by treatment area. One of: tooth, quadrant, arch, sextant, mouth.

billableboolean

When true, return only completed procedures eligible for insurance claim creation.

do_not_bill_insuranceboolean

Filter by the insurance do-not-bill flag.

billing_order_code"D" | "DD" | "DM" | "M" | "MD" | "MDD" | "MMD" | "N"

Filter by explicit CareStack billing-order letter code.

has_active_claimboolean

Filter by whether a non-voided active claim already references the procedure.

include_deletedboolean

When true, include soft-deleted procedures.

Default: false

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required
pageintegerrequired
page_sizeintegerrequired
totalintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/procedures" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans

List procedure spans

List procedure spans for a patient with optional status filter. Raises 404 if the patient is not found.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
statusstring

Filter by span status (e.g., active, archived).

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required
pageintegerrequired
page_sizeintegerrequired
totalintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}

Get procedure span

Retrieve a single procedure span by UUID. Raises 404 if not found or the span does not belong to the specified patient.

Parameters

Path Parameters
patient_uuidstringrequired
span_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Record creation timestamp.

deleted_atstring (date-time)
idstring (uuid)required

UUID of the procedure span.

membersobject[]required

Ordered list of procedures that make up this span.

notestringrequired

Clinical note for this span.

span_definitionobject

Lightweight reference to a related entity — exposes UUID and optional name.

statusstringrequired

Current status of the span (e.g., 'active', 'completed').

updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}/members

List span members

List all members of a procedure span. Returns the span's member list with charted procedure references, roles, and position order. Raises 404 if the patient or span is not found, or if the span does not belong to the specified patient.

Parameters

Path Parameters
patient_uuidstringrequired
span_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}/members" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/teeth/{tooth_num}/status-history

Get tooth status history

Get the full status history timeline for a specific tooth. Returns ALL records including superseded and soft-deleted entries, ordered by created_at DESC. This provides a complete audit trail of status changes for the tooth. Raises 404 if the patient is not found.

Parameters

Path Parameters
patient_uuidstringrequired
tooth_numstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/teeth/{tooth_num}/status-history" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-indicators

Get aggregated tooth indicators

Aggregated tooth indicators from all registered specialty modules. Currently returns indicators from: perio (mobility, furcation). Future modules (endo, ortho) will be added without API changes. Raises 404 if the patient is not found.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
itemsobject[]required
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-indicators" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-statuses

List tooth statuses

List all active tooth statuses for a patient's chart. Returns one record per tooth that has an active status entry. Raises 404 if the patient is not found.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
itemsobject[]required
totalintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-statuses" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans/{plan_uuid}/estimates

List treatment plan estimates

Get all estimates for a treatment plan with effective values. Returns estimates including COALESCE-resolved override values and staleness status for each estimate. Raises 404 if patient or treatment plan not found, or if the plan does not belong to the patient.

Parameters

Path Parameters
patient_uuidstringrequired
plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans/{plan_uuid}/estimates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans/{plan_uuid}/staleness

Check estimate staleness

Check which estimates in a treatment plan are stale. Returns a report showing which estimates need re-computation based on changes to fees, benefits, or plan configuration. Raises 404 if patient or treatment plan not found, or if the plan does not belong to the patient.

Parameters

Path Parameters
patient_uuidstringrequired
plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
estimatesobject[]required

Per-estimate staleness details.

fresh_countintegerrequired

Estimates that are up-to-date.

stale_countintegerrequired

Estimates needing re-computation.

total_estimatesintegerrequired

Total estimate rows.

treatment_plan_uuidstring (uuid)required

UUID of the treatment plan.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans/{plan_uuid}/staleness" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/procedures/{procedure_uuid}

Get charted procedure

Retrieve a single charted procedure by UUID. Raises 404 if not found.

Parameters

Path Parameters
procedure_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

archstring
billing_notestring
billing_order_codeenumrequired

Effective CareStack billing-order letter code; N means non-insurance.

DDDDMMMDMDDMMDN
bundle_group_idinteger
clinical_notestring
code_sentstring
created_atstring (date-time)required

Record creation timestamp.

date_completedstring (date-time)
date_original_prostheticstring (date)
date_servicestring (date)required

Date of service.

date_treatment_plannedstring (date)
deleted_atstring (date-time)
diagnosis_code_1string
diagnosis_code_2string
diagnosis_code_3string
diagnosis_code_4string
diagnostic_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

do_not_bill_insuranceboolean

True when this charted procedure is intentionally excluded from insurance claim creation.

effective_feestringrequired

The fee actually used for finance: fee_override if set, otherwise office_fee.

explosion_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

fee_overridestring
fee_sourcestringrequired

How the effective fee was determined. One of: fee_schedule, override.

has_active_claimboolean

True when a non-voided active claim already references this charted procedure.

idstring (uuid)required

UUID of the charted procedure.

is_prostheticbooleanrequired

Whether this is a prosthetic procedure.

item_orderinteger

Display order within a treatment plan or visit.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

material_type_codestring
notestringrequired

Clinical note for this procedure.

office_feestringrequired

UCR office fee from the fee schedule at charting time. Always the base production amount — never replaced by fee_override.

patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

priorityobject

Lightweight reference to a related entity — exposes UUID and optional name.

procedure_categorystring
procedure_codestring
procedure_descriptionstring
prognosisobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

quadrantstring
sextantstring
statusstringrequired

Procedure lifecycle status. One of: treatment_planned, scheduled, in_progress, complete, complete_referred, existing_current, existing_other, referred.

surfacesstring
tooth_numberstring
tooth_rangestring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

visit_phase_hintinteger
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/procedures/{procedure_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/procedures/active-claim-refs

List active claim references for charted procedures

Return a compact active-claim badge read model keyed by procedure UUID.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
procedure_uuidsstring[]required

Charted procedure UUIDs to look up.

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/procedures/active-claim-refs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/procedures/unscheduled-treatment/agent-worklist

List unscheduled treatment worklist for agents

Return an agent-safe worklist without clinical notes, billing notes, contact info, or addresses.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
as_of_datestring

Only include procedures planned on or before this date.

max_resultsinteger

Maximum worklist rows to return.

Default: 10

min_fee_centsinteger

Minimum total unscheduled treatment value in cents.

Default: 0

min_days_unscheduledinteger

Only include treatment planned at least this many days ago.

location_uuidstringrequired

Procedure location UUID filter. Required for PHI worklist scoping.

sort"oldest_planned_asc" | "value_desc"

Sort order for worklist rows.

oldest_planned_ascvalue_desc

Default: "value_desc"

Responses

200Successful Response
as_of_datestring (date)required
itemsobject[]required
page_sizeintegerrequired
total_countintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/procedures/unscheduled-treatment/agent-worklist" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/chart-bundle

Create procedure bundle

Create a bundle of charted procedures from an explosion code. Resolves each explosion code entry into an individual charted procedure. Optional entries may be excluded via excluded_entry_uuids. Raises 404 if the patient, explosion code, provider, or any referenced entry is not found. Raises 422 if validation fails.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

archenum
lowerupper
date_servicestring (date)
excluded_entry_uuidsstring (uuid)[]

UUIDs of explosion code entries to exclude from this bundle chart.

explosion_code_uuidstring (uuid)required

UUID of the explosion code (bundle definition) to chart.

location_uuidstring (uuid)
notestring
provider_uuidstring (uuid)required

UUID of the rendering provider.

quadrantenum
LLLRULUR
sextantenum
123456
surfacesstring
tooth_numberstring

Responses

201Successful Response
bundle_group_idintegerrequired

Internal group ID linking all procedures created from this bundle.

proceduresobject[]required

List of charted procedures created from the bundle.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/chart-bundle" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arch": "string",
    "date_service": "string",
    "excluded_entry_uuids": [],
    "explosion_code_uuid": "00000000-0000-0000-0000-000000000000",
    "location_uuid": "string",
    "provider_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/conditions

Create patient condition

Create a new patient condition record. Defaults date_identified to today if not provided. Raises 404 if the patient, provider, or diagnostic code is not found. Raises 422 if validation fails.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

condition_typeenumrequired

Type of condition. One of: caries, fracture, abscess, impaction, open_contact, diastema, abrasion, erosion, attrition, watch, periapical_lesion, periodontal, decalcification, defective_restoration, other.

abrasionabscessankylosisattritioncariesdecalcificationdefective_restorationdiastemadilacerationerosionfracturefracture_rootfusiongeminationhypoplasiaimpactionluxationmacrodontiamicrodontiaopen_contactotherperiapical_lesionperiodontalroot_resorption_externalroot_resorption_internalwatch
date_identifiedstring (date)
diagnostic_code_uuidstring (uuid)
notestring
provider_uuidstring (uuid)
severityenum
mildmoderatesevere
surfacestring
tooth_numberstring

Responses

201Successful Response
condition_typeenumrequired

Type of condition. One of: caries, fracture, abscess, impaction, open_contact, diastema, abrasion, erosion, attrition, watch, periapical_lesion, periodontal, decalcification, defective_restoration, other.

abrasionabscessankylosisattritioncariesdecalcificationdefective_restorationdiastemadilacerationerosionfracturefracture_rootfusiongeminationhypoplasiaimpactionluxationmacrodontiamicrodontiaopen_contactotherperiapical_lesionperiodontalroot_resorption_externalroot_resorption_internalwatch
created_atstring (date-time)required

Record creation timestamp.

date_identifiedstring (date)required

Date the condition was identified.

date_resolvedstring (date)
diagnostic_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

idstring (uuid)required

UUID of the patient condition.

notestringrequired

Clinical note describing the condition.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

severityenum
mildmoderatesevere
statusenumrequired

Condition monitoring status. One of: active, resolved, monitoring.

activemonitoringresolved
surfacestring
tooth_numberstring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/conditions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "condition_type": "abrasion",
    "date_identified": "string",
    "diagnostic_code_uuid": "string",
    "note": "string",
    "provider_uuid": "string"
  }'
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/procedures

Create charted procedure

Create a new charted procedure for a patient. Raises 404 if patient, procedure code, provider, or any referenced entity is not found. Raises 422 if validation fails (e.g., priority_uuid does not reference a priority definition).

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

appointment_uuidstring (uuid)
archenum
lowerupper
billing_order_codeenum
DDDDMMMDMDDMMDN
date_original_prostheticstring (date)
date_servicestring (date)
diagnostic_code_uuidstring (uuid)
do_not_bill_insuranceboolean

When true, this charted procedure is excluded from insurance claim creation.

fee_overridenumber
is_prostheticboolean

Whether this is a prosthetic procedure.

location_uuidstring (uuid)
material_type_codestring
notestring
priority_uuidstring (uuid)
procedure_code_uuidstring (uuid)required

UUID of the procedure code to chart.

prognosis_uuidstring (uuid)
provider_uuidstring (uuid)required

UUID of the rendering provider.

quadrantenum
LLLRULUR
sextantenum
123456
source_procedure_uuidstring (uuid)
statusstring
surfacesstring
tooth_numberstring
tooth_rangestring

Responses

201Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

archstring
billing_notestring
billing_order_codeenumrequired

Effective CareStack billing-order letter code; N means non-insurance.

DDDDMMMDMDDMMDN
bundle_group_idinteger
clinical_notestring
code_sentstring
created_atstring (date-time)required

Record creation timestamp.

date_completedstring (date-time)
date_original_prostheticstring (date)
date_servicestring (date)required

Date of service.

date_treatment_plannedstring (date)
deleted_atstring (date-time)
diagnosis_code_1string
diagnosis_code_2string
diagnosis_code_3string
diagnosis_code_4string
diagnostic_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

do_not_bill_insuranceboolean

True when this charted procedure is intentionally excluded from insurance claim creation.

effective_feestringrequired

The fee actually used for finance: fee_override if set, otherwise office_fee.

explosion_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

fee_overridestring
fee_sourcestringrequired

How the effective fee was determined. One of: fee_schedule, override.

has_active_claimboolean

True when a non-voided active claim already references this charted procedure.

idstring (uuid)required

UUID of the charted procedure.

is_prostheticbooleanrequired

Whether this is a prosthetic procedure.

item_orderinteger

Display order within a treatment plan or visit.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

material_type_codestring
notestringrequired

Clinical note for this procedure.

office_feestringrequired

UCR office fee from the fee schedule at charting time. Always the base production amount — never replaced by fee_override.

patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

priorityobject

Lightweight reference to a related entity — exposes UUID and optional name.

procedure_categorystring
procedure_codestring
procedure_descriptionstring
prognosisobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

quadrantstring
sextantstring
statusstringrequired

Procedure lifecycle status. One of: treatment_planned, scheduled, in_progress, complete, complete_referred, existing_current, existing_other, referred.

surfacesstring
tooth_numberstring
tooth_rangestring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

visit_phase_hintinteger
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/procedures" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_uuid": "string",
    "arch": "string",
    "billing_order_code": "string",
    "date_original_prosthetic": "string",
    "date_service": "string",
    "procedure_code_uuid": "00000000-0000-0000-0000-000000000000",
    "provider_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/procedures/bulk

Bulk import procedures

Bulk import up to 500 charted procedures for a patient. Raises 404 if the patient is not found. Raises 422 if any row fails validation; per-row errors are returned in the response body.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

metaobject

Top-level execution options for a bulk request.

rowsobject[]required

Responses

200Successful Response
createdinteger
failedinteger
resultsobject[]required
skippedinteger
totalintegerrequired
updatedinteger
validatedinteger
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/procedures/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": {},
    "rows": []
  }'
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans

Create procedure span

Create a new procedure span linking multiple charted procedures. Raises 404 if the patient, span definition, or any member charted procedure is not found. Raises 422 if validation fails.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

membersobject[]required

List of charted procedures to include in the span. At least one required.

notestring
span_definition_uuidstring (uuid)required

UUID of the span definition that governs this span.

Responses

201Successful Response
created_atstring (date-time)required

Record creation timestamp.

deleted_atstring (date-time)
idstring (uuid)required

UUID of the procedure span.

membersobject[]required

Ordered list of procedures that make up this span.

notestringrequired

Clinical note for this span.

span_definitionobject

Lightweight reference to a related entity — exposes UUID and optional name.

statusstringrequired

Current status of the span (e.g., 'active', 'completed').

updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [],
    "note": "string",
    "span_definition_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-statuses/seed

Seed initial dentition

Seed or refresh tooth status records for a patient based on date of birth. Modes: - ``age_based``: Initial setup for new patients. Creates all age-appropriate teeth. Idempotent: returns 0 if patient already has records. - ``reseed``: Refresh from current DOB. Soft-deletes all ``age_seeded`` records and re-seeds from the current DOB. Preserves clinician-set statuses (source = manual, clinical_chart, imported). Use for DOB corrections or returning patients. Raises 404 if the patient is not found. Raises 422 if the patient has no date of birth or mode is invalid.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

modestringrequired

Seeding mode: 'age_based' for initial setup (empty charts only), 'reseed' to refresh from current DOB (replaces age_seeded records, preserves clinician-set statuses).

Responses

200Successful Response
teeth_removedinteger

Number of stale age_seeded records removed (reseed mode only).

teeth_seededintegerrequired

Number of tooth status records created. 0 if already seeded.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-statuses/seed" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "string"
  }'
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-transition

Atomic tooth transition

Atomically transition a primary tooth to its permanent successor. Sets both the primary tooth status and the successor tooth status in a single database transaction. Validates the succession mapping (e.g., D→7 is valid, D→14 is not). The primary_tooth_number must have a known permanent successor, and the provided successor_tooth_number must match that expected successor. Raises 422 if the succession mapping is invalid or field validation fails. Raises 404 if the patient is not found.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

primary_statusenumrequired

Status to set on the primary tooth. One of: over_retained, exfoliating.

exfoliatingover_retained
primary_tooth_numberstringrequired

Primary tooth letter (A-T).

successor_eruption_pctinteger
successor_eruption_stagestring
successor_root_completionstring
successor_statusenumrequired

Status to set on the successor tooth. One of: partially_erupted, present.

partially_eruptedpresent
successor_tooth_numberstringrequired

Permanent successor tooth number (1-32).

Responses

200Successful Response
primaryobjectrequired

Output schema for a tooth status record.

successorobjectrequired

Output schema for a tooth status record.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-transition" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_status": "exfoliating",
    "primary_tooth_number": "string",
    "successor_eruption_pct": 1,
    "successor_eruption_stage": "string",
    "successor_root_completion": "string",
    "successor_status": "partially_erupted",
    "successor_tooth_number": "string"
  }'
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans/{plan_uuid}/estimate

Estimate treatment plan

Run insurance estimation for all procedures in a treatment plan. Estimates each procedure against each of the patient's active insurance plans in COB order. Creates or updates ProcedureEstimate rows. Raises 404 if patient, treatment plan, or patient plans not found. Raises 422 if patient has no active insurance plans.

Parameters

Path Parameters
patient_uuidstringrequired
plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
estimate_countintegerrequired

Total number of estimates.

estimatesobject[]required

Individual estimate results.

stale_countintegerrequired

Number of stale estimates.

total_fee_billedstringrequired

Sum of all fee_billed amounts.

total_insurance_estimatestringrequired

Sum of all effective insurance estimates.

total_patient_estimatestringrequired

Sum of all patient estimates.

total_write_offstringrequired

Sum of all effective write-off amounts.

treatment_plan_uuidstring (uuid)required

UUID of the treatment plan that was estimated.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans/{plan_uuid}/estimate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans/{plan_uuid}/re-estimate

Re-estimate treatment plan

Re-estimate stale estimates in a treatment plan. By default only re-estimates stale estimates (where inputs_hash differs). Set force=true to re-estimate all regardless of staleness. Raises 404 if patient or treatment plan not found.

Parameters

Path Parameters
patient_uuidstringrequired
plan_uuidstringrequired
org_idstringrequired

Request Body

forceboolean

If true, re-estimate all procedures regardless of staleness.

Responses

200Successful Response
estimate_countintegerrequired

Total number of estimates.

estimatesobject[]required

Individual estimate results.

stale_countintegerrequired

Number of stale estimates.

total_fee_billedstringrequired

Sum of all fee_billed amounts.

total_insurance_estimatestringrequired

Sum of all effective insurance estimates.

total_patient_estimatestringrequired

Sum of all patient estimates.

total_write_offstringrequired

Sum of all effective write-off amounts.

treatment_plan_uuidstring (uuid)required

UUID of the treatment plan that was estimated.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans/{plan_uuid}/re-estimate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "force": false
  }'
post/api/v1/{org_id}/clinical/procedures/{procedure_uuid}/complete

Complete charted procedure

Mark a charted procedure as completed. Transitions the procedure to completed status and records the service date. Raises 404 if not found. Raises 409 if base_version is stale. Raises 422 if the procedure is not in a completable status.

Parameters

Path Parameters
procedure_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

date_servicestring (date)
notestring

Responses

200Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

archstring
billing_notestring
billing_order_codeenumrequired

Effective CareStack billing-order letter code; N means non-insurance.

DDDDMMMDMDDMMDN
bundle_group_idinteger
clinical_notestring
code_sentstring
created_atstring (date-time)required

Record creation timestamp.

date_completedstring (date-time)
date_original_prostheticstring (date)
date_servicestring (date)required

Date of service.

date_treatment_plannedstring (date)
deleted_atstring (date-time)
diagnosis_code_1string
diagnosis_code_2string
diagnosis_code_3string
diagnosis_code_4string
diagnostic_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

do_not_bill_insuranceboolean

True when this charted procedure is intentionally excluded from insurance claim creation.

effective_feestringrequired

The fee actually used for finance: fee_override if set, otherwise office_fee.

explosion_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

fee_overridestring
fee_sourcestringrequired

How the effective fee was determined. One of: fee_schedule, override.

has_active_claimboolean

True when a non-voided active claim already references this charted procedure.

idstring (uuid)required

UUID of the charted procedure.

is_prostheticbooleanrequired

Whether this is a prosthetic procedure.

item_orderinteger

Display order within a treatment plan or visit.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

material_type_codestring
notestringrequired

Clinical note for this procedure.

office_feestringrequired

UCR office fee from the fee schedule at charting time. Always the base production amount — never replaced by fee_override.

patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

priorityobject

Lightweight reference to a related entity — exposes UUID and optional name.

procedure_categorystring
procedure_codestring
procedure_descriptionstring
prognosisobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

quadrantstring
sextantstring
statusstringrequired

Procedure lifecycle status. One of: treatment_planned, scheduled, in_progress, complete, complete_referred, existing_current, existing_other, referred.

surfacesstring
tooth_numberstring
tooth_rangestring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

visit_phase_hintinteger
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/procedures/{procedure_uuid}/complete" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "date_service": "string",
    "note": "string"
  }'
post/api/v1/{org_id}/clinical/procedures/{procedure_uuid}/transition

Transition procedure status

Transition a charted procedure to a target status. Raises 404 if not found. Raises 409 if base_version is stale. Raises 422 if the requested status transition is not allowed.

Parameters

Path Parameters
procedure_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

notestring
statusstringrequired

Target procedure status. One of: treatment_planned, scheduled, in_progress, complete, complete_referred, existing_current, existing_other, referred.

Responses

200Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

archstring
billing_notestring
billing_order_codeenumrequired

Effective CareStack billing-order letter code; N means non-insurance.

DDDDMMMDMDDMMDN
bundle_group_idinteger
clinical_notestring
code_sentstring
created_atstring (date-time)required

Record creation timestamp.

date_completedstring (date-time)
date_original_prostheticstring (date)
date_servicestring (date)required

Date of service.

date_treatment_plannedstring (date)
deleted_atstring (date-time)
diagnosis_code_1string
diagnosis_code_2string
diagnosis_code_3string
diagnosis_code_4string
diagnostic_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

do_not_bill_insuranceboolean

True when this charted procedure is intentionally excluded from insurance claim creation.

effective_feestringrequired

The fee actually used for finance: fee_override if set, otherwise office_fee.

explosion_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

fee_overridestring
fee_sourcestringrequired

How the effective fee was determined. One of: fee_schedule, override.

has_active_claimboolean

True when a non-voided active claim already references this charted procedure.

idstring (uuid)required

UUID of the charted procedure.

is_prostheticbooleanrequired

Whether this is a prosthetic procedure.

item_orderinteger

Display order within a treatment plan or visit.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

material_type_codestring
notestringrequired

Clinical note for this procedure.

office_feestringrequired

UCR office fee from the fee schedule at charting time. Always the base production amount — never replaced by fee_override.

patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

priorityobject

Lightweight reference to a related entity — exposes UUID and optional name.

procedure_categorystring
procedure_codestring
procedure_descriptionstring
prognosisobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

quadrantstring
sextantstring
statusstringrequired

Procedure lifecycle status. One of: treatment_planned, scheduled, in_progress, complete, complete_referred, existing_current, existing_other, referred.

surfacesstring
tooth_numberstring
tooth_rangestring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

visit_phase_hintinteger
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/procedures/{procedure_uuid}/transition" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "note": "string",
    "status": "string"
  }'
post/api/v1/{org_id}/clinical/procedures/{procedure_uuid}/void

Void completed procedure

Void a completed procedure and remove any treatment-plan links. Raises 404 if not found, 409 if base_version is stale, and 422 if the procedure is not in a voidable completed status.

Parameters

Path Parameters
procedure_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

reasonstring

Responses

200Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

archstring
billing_notestring
billing_order_codeenumrequired

Effective CareStack billing-order letter code; N means non-insurance.

DDDDMMMDMDDMMDN
bundle_group_idinteger
clinical_notestring
code_sentstring
created_atstring (date-time)required

Record creation timestamp.

date_completedstring (date-time)
date_original_prostheticstring (date)
date_servicestring (date)required

Date of service.

date_treatment_plannedstring (date)
deleted_atstring (date-time)
diagnosis_code_1string
diagnosis_code_2string
diagnosis_code_3string
diagnosis_code_4string
diagnostic_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

do_not_bill_insuranceboolean

True when this charted procedure is intentionally excluded from insurance claim creation.

effective_feestringrequired

The fee actually used for finance: fee_override if set, otherwise office_fee.

explosion_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

fee_overridestring
fee_sourcestringrequired

How the effective fee was determined. One of: fee_schedule, override.

has_active_claimboolean

True when a non-voided active claim already references this charted procedure.

idstring (uuid)required

UUID of the charted procedure.

is_prostheticbooleanrequired

Whether this is a prosthetic procedure.

item_orderinteger

Display order within a treatment plan or visit.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

material_type_codestring
notestringrequired

Clinical note for this procedure.

office_feestringrequired

UCR office fee from the fee schedule at charting time. Always the base production amount — never replaced by fee_override.

patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

priorityobject

Lightweight reference to a related entity — exposes UUID and optional name.

procedure_categorystring
procedure_codestring
procedure_descriptionstring
prognosisobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

quadrantstring
sextantstring
statusstringrequired

Procedure lifecycle status. One of: treatment_planned, scheduled, in_progress, complete, complete_referred, existing_current, existing_other, referred.

surfacesstring
tooth_numberstring
tooth_rangestring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

visit_phase_hintinteger
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/procedures/{procedure_uuid}/void" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "reason": "string"
  }'
put/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-statuses

Set tooth status

Set (upsert) the status of a specific tooth for a patient. Creates a new tooth status record or supersedes an existing one for the same tooth. Optional expected_version enforces optimistic concurrency. Raises 404 if the patient or referenced charted procedure is not found. Raises 409 if expected_version is stale. Raises 422 if validation fails.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

charted_procedure_uuidstring (uuid)
ectopic_slot_indexinteger
effective_datestring (date)
eruption_pctinteger
eruption_stagestring
expected_versioninteger
impaction_anglestring
impaction_depthstring
notestring
root_completionstring
rotatenumber

Rotation angle in degrees (-180 to +180).

scale_factornumber
shift_bnumber

Buccal shift in mm (-10 to +10).

shift_mnumber

Mesial shift in mm (-10 to +10).

shift_onumber

Occlusal shift in mm (-10 to +10).

sourcestring
statusstringrequired

Tooth status classification. One of: present, missing, primary, prosthetic, unerupted, supernumerary, hidden, congenitally_absent, partially_erupted, over_retained, residual_root, impacted, avulsed, exfoliating.

tip_bnumber

Buccal tip angle in degrees (-45 to +45).

tip_mnumber

Mesial tip angle in degrees (-45 to +45).

tooth_numberstringrequired

Universal tooth number (1-32 permanent, A-T primary).

transposition_withstring

Responses

200Successful Response
created_atstring (date-time)required

Record creation timestamp.

ectopic_slot_indexinteger
effective_datestring (date)required

Date this status became effective.

eruption_pctinteger
eruption_stagestring
idstring (uuid)required

UUID of the tooth status record.

impaction_anglestring
impaction_depthstring
notestringrequired

Clinical note for this tooth status entry.

root_completionstring
rotatenumberrequired

Rotation angle in degrees (-180 to +180).

scale_factornumber
shift_bnumberrequired

Buccal shift in mm (-10 to +10).

shift_mnumberrequired

Mesial shift in mm (-10 to +10).

shift_onumberrequired

Occlusal shift in mm (-10 to +10).

sourcestringrequired

Source of the tooth status data. One of: manual, imported, clinical_chart.

statusstringrequired

Tooth status classification. One of: present, missing, primary, prosthetic, unerupted, supernumerary, hidden, congenitally_absent, partially_erupted, over_retained, residual_root, impacted, avulsed, exfoliating.

tip_bnumberrequired

Buccal tip angle in degrees (-45 to +45).

tip_mnumberrequired

Mesial tip angle in degrees (-45 to +45).

tooth_numberstringrequired

Universal tooth number (1-32 permanent, A-T primary).

transposition_withstring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PUT "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/tooth-statuses" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "charted_procedure_uuid": "string",
    "ectopic_slot_index": 1,
    "effective_date": "string",
    "eruption_pct": 1,
    "eruption_stage": "string",
    "status": "string",
    "tooth_number": "string"
  }'
patch/api/v1/{org_id}/clinical/conditions/{condition_uuid}

Update patient condition

Partially update a patient condition, or resolve it. If status is set to 'resolved', the condition is resolved and date_resolved is set to today. Otherwise performs a standard partial update. Raises 404 if not found. Raises 409 if base_version is stale. Raises 422 if validation fails.

Parameters

Path Parameters
condition_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

notestring
severityenum
mildmoderatesevere
statusenum
activemonitoringresolved
surfacestring

Responses

200Successful Response
condition_typeenumrequired

Type of condition. One of: caries, fracture, abscess, impaction, open_contact, diastema, abrasion, erosion, attrition, watch, periapical_lesion, periodontal, decalcification, defective_restoration, other.

abrasionabscessankylosisattritioncariesdecalcificationdefective_restorationdiastemadilacerationerosionfracturefracture_rootfusiongeminationhypoplasiaimpactionluxationmacrodontiamicrodontiaopen_contactotherperiapical_lesionperiodontalroot_resorption_externalroot_resorption_internalwatch
created_atstring (date-time)required

Record creation timestamp.

date_identifiedstring (date)required

Date the condition was identified.

date_resolvedstring (date)
diagnostic_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

idstring (uuid)required

UUID of the patient condition.

notestringrequired

Clinical note describing the condition.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

severityenum
mildmoderatesevere
statusenumrequired

Condition monitoring status. One of: active, resolved, monitoring.

activemonitoringresolved
surfacestring
tooth_numberstring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical/conditions/{condition_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "note": "string",
    "severity": "string",
    "status": "string",
    "surface": "string"
  }'
patch/api/v1/{org_id}/clinical/estimates/{estimate_uuid}/overrides

Set estimate overrides

Set override values on a procedure estimate. Override values take precedence over calculated values via the COALESCE pattern: effective_value = COALESCE(override, calculated). Only fields present in the request body are updated. Set a field to null to clear that override. Raises 404 if estimate not found. Raises 409 if base_version doesn't match (optimistic concurrency).

Parameters

Path Parameters
estimate_uuidstringrequired
org_idstringrequired

Request Body

allowed_overridenumber
base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

copay_overridenumber
deductible_overridenumber
insurance_estimate_overridenumber
percentage_overridenumber
write_off_overridenumber

Responses

200Successful Response
allowed_feestring
base_estimatestringrequired

Base estimate before deductible and coverage calculations in dollars.

calculated_atstring (date-time)
charted_procedure_uuidstring (uuid)required

UUID of the charted procedure this estimate belongs to.

code_sentstring
copay_amountstringrequired

Fixed copay amount in dollars.

coverage_percentstringrequired

Insurance coverage percentage for this procedure (0–100).

created_atstring (date-time)required

Record creation timestamp.

date_estimatedstring (date-time)required

Timestamp when this estimate was calculated.

deductible_appliedstringrequired

Deductible amount applied to this procedure in dollars.

effective_allowed_feestring
effective_copaystringrequired

COALESCE(copay_override, copay_amount).

effective_coverage_percentstringrequired

COALESCE(percentage_override, coverage_percent).

effective_deductiblestringrequired

COALESCE(deductible_override, deductible_applied).

effective_insurance_estimatestringrequired

COALESCE(insurance_estimate_override, insurance_estimate).

effective_write_offstringrequired

COALESCE(write_off_override, write_off_estimate).

estimate_notestringrequired

Note or explanation associated with this estimate.

estimate_statusstringrequired

Authorization status of the estimate. One of: estimate, preauth, preauth_received.

exclusion_reasonstring
fee_billedstringrequired

Fee amount billed to insurance in dollars.

has_allowed_overrideboolean

True if allowed_override is set.

has_copay_overrideboolean

True if copay_override is set.

has_deductible_overrideboolean

True if deductible_override is set.

has_insurance_estimate_overrideboolean

True if insurance_estimate_override is set.

has_percentage_overrideboolean

True if percentage_override is set.

has_write_off_overrideboolean

True if write_off_override is set.

idstring (uuid)required

UUID of the procedure estimate.

inputs_hashstring
insurance_estimatestringrequired

Estimated insurance payment in dollars.

is_excludedbooleanrequired

Whether this estimate is excluded from benefit calculations.

is_stalebooleanrequired

True if the estimate needs re-computation.

ordinalintegerrequired

Ordinal position when multiple estimates exist for the same procedure (e.g., primary vs. secondary insurance).

paid_other_insurancestringrequired

Amount paid by another insurance plan (coordination of benefits) in dollars.

patient_estimatestringrequired

Estimated patient responsibility in dollars.

ppo_feestring
preauth_amountstring
preauth_datestring (date)
preauth_numberstring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

write_off_estimatestringrequired

Estimated contractual write-off amount in dollars.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical/estimates/{estimate_uuid}/overrides" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_override": null,
    "base_version": 1,
    "copay_override": null,
    "deductible_override": null,
    "insurance_estimate_override": null
  }'
patch/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}

Update procedure span

Partially update a procedure span. Raises 404 if not found or the span does not belong to the specified patient. Raises 409 if base_version is stale. Raises 422 if validation fails.

Parameters

Path Parameters
patient_uuidstringrequired
span_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

notestring
statusstring

Responses

200Successful Response
created_atstring (date-time)required

Record creation timestamp.

deleted_atstring (date-time)
idstring (uuid)required

UUID of the procedure span.

membersobject[]required

Ordered list of procedures that make up this span.

notestringrequired

Clinical note for this span.

span_definitionobject

Lightweight reference to a related entity — exposes UUID and optional name.

statusstringrequired

Current status of the span (e.g., 'active', 'completed').

updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "note": "string",
    "status": "string"
  }'
patch/api/v1/{org_id}/clinical/procedures/{procedure_uuid}

Update charted procedure

Partially update a charted procedure. Raises 404 if not found. Raises 409 if base_version is stale. Raises 422 if validation fails (e.g., invalid status transition).

Parameters

Path Parameters
procedure_uuidstringrequired
org_idstringrequired

Request Body

archenum
lowerupper
base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

billing_notestring
billing_order_codeenum
DDDDMMMDMDDMMDN
clinical_notestring
date_original_prostheticstring (date)
date_servicestring (date)
diagnostic_code_uuidstring (uuid)
do_not_bill_insuranceboolean
fee_overridenumber
is_prostheticboolean
material_type_codestring
notestring
priority_uuidstring (uuid)
procedure_code_uuidstring (uuid)
prognosis_uuidstring (uuid)
quadrantenum
LLLRULUR
sextantenum
123456
surfacesstring
tooth_numberstring
tooth_rangestring

Responses

200Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

archstring
billing_notestring
billing_order_codeenumrequired

Effective CareStack billing-order letter code; N means non-insurance.

DDDDMMMDMDDMMDN
bundle_group_idinteger
clinical_notestring
code_sentstring
created_atstring (date-time)required

Record creation timestamp.

date_completedstring (date-time)
date_original_prostheticstring (date)
date_servicestring (date)required

Date of service.

date_treatment_plannedstring (date)
deleted_atstring (date-time)
diagnosis_code_1string
diagnosis_code_2string
diagnosis_code_3string
diagnosis_code_4string
diagnostic_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

do_not_bill_insuranceboolean

True when this charted procedure is intentionally excluded from insurance claim creation.

effective_feestringrequired

The fee actually used for finance: fee_override if set, otherwise office_fee.

explosion_codeobject

Lightweight reference to a related entity — exposes UUID and optional name.

fee_overridestring
fee_sourcestringrequired

How the effective fee was determined. One of: fee_schedule, override.

has_active_claimboolean

True when a non-voided active claim already references this charted procedure.

idstring (uuid)required

UUID of the charted procedure.

is_prostheticbooleanrequired

Whether this is a prosthetic procedure.

item_orderinteger

Display order within a treatment plan or visit.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

material_type_codestring
notestringrequired

Clinical note for this procedure.

office_feestringrequired

UCR office fee from the fee schedule at charting time. Always the base production amount — never replaced by fee_override.

patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

priorityobject

Lightweight reference to a related entity — exposes UUID and optional name.

procedure_categorystring
procedure_codestring
procedure_descriptionstring
prognosisobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

quadrantstring
sextantstring
statusstringrequired

Procedure lifecycle status. One of: treatment_planned, scheduled, in_progress, complete, complete_referred, existing_current, existing_other, referred.

surfacesstring
tooth_numberstring
tooth_rangestring
updated_atstring (date-time)required

Record last-update timestamp.

versionintegerrequired

Current version for optimistic concurrency.

visit_phase_hintinteger
422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical/procedures/{procedure_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arch": "string",
    "base_version": 1,
    "billing_note": "string",
    "billing_order_code": "string",
    "clinical_note": "string"
  }'
delete/api/v1/{org_id}/clinical/conditions/{condition_uuid}

Delete patient condition

Soft-delete a patient condition. Raises 404 if not found, 409 if base_version is stale.

Parameters

Path Parameters
condition_uuidstringrequired
org_idstringrequired
Query Parameters
base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/conditions/{condition_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical/patients/{patient_uuid}/procedures/{procedure_uuid}/estimates/{estimate_uuid}

Delete procedure estimate

Soft-delete a procedure estimate. Archives the estimate, removing it from active calculations. Raises 404 if the patient, procedure, or estimate is not found. Raises 409 if base_version is stale.

Parameters

Path Parameters
patient_uuidstringrequired
procedure_uuidstringrequired
estimate_uuidstringrequired
org_idstringrequired
Query Parameters
base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/procedures/{procedure_uuid}/estimates/{estimate_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}

Delete procedure span

Soft-delete a procedure span. Raises 404 if not found or span does not belong to the patient, 409 if base_version is stale.

Parameters

Path Parameters
patient_uuidstringrequired
span_uuidstringrequired
org_idstringrequired
Query Parameters
base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}/cascade

Cascade delete span with procedures

Cascade-delete a span: soft-delete the span, hard-delete member rows, and soft-delete all non-completed member procedures. Completed and complete_referred procedures are preserved as standalone records. Raises 404 if not found, 409 if base_version is stale.

Parameters

Path Parameters
patient_uuidstringrequired
span_uuidstringrequired
org_idstringrequired
Query Parameters
base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

Responses

200Successful Response
deleted_procedure_uuidsstring (uuid)[]required

Procedures that were soft-deleted.

preserved_procedure_uuidsstring (uuid)[]required

Completed procedures that were preserved as standalone records.

span_uuidstring (uuid)required

UUID of the deleted span.

422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/spans/{span_uuid}/cascade" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical/procedures/{procedure_uuid}

Delete charted procedure

Soft-delete a charted procedure and remove treatment-plan links. Raises 404 if not found, 409 if base_version is stale, 422 if procedure is in a non-deletable status (complete, complete_referred).

Parameters

Path Parameters
procedure_uuidstringrequired
org_idstringrequired
Query Parameters
base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/procedures/{procedure_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical/tooth-statuses/{status_uuid}

Delete tooth status

Soft-delete a tooth status record. Supersedes the record and marks it as deleted, removing the tooth from the active chart. Idempotent: returns 204 if already deleted. Raises 404 if not found, 409 if base_version is stale.

Parameters

Path Parameters
status_uuidstringrequired
org_idstringrequired
Query Parameters
base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/tooth-statuses/{status_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Clinical Notes

58 endpoints

get/api/v1/{org_id}/clinical-notes/auto-rules

List auto-note rules

List auto-note rules with optional filters. Returns a paginated list ordered by priority (desc), name (asc).

Parameters

Path Parameters
org_idstringrequired
Query Parameters
trigger_eventstring

Filter by trigger event type.

is_activeboolean

Filter by active status.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of auto-note rules.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching rules.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/auto-rules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/auto-rules/{rule_uuid}

Get auto-note rule

Get a single auto-note rule by UUID. Raises 404 if the rule does not exist.

Parameters

Path Parameters
rule_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

When the rule was created.

descriptionstring
idstring (uuid)required

Public UUID of the auto-note rule.

is_activebooleanrequired

Whether the rule is active.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

merge_strategystringrequired

How auto-generated notes are merged.

namestringrequired

Display name of the rule.

priorityintegerrequired

Rule priority (higher = evaluated first).

procedure_categorystring
procedure_code_patternstring
providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

trigger_eventstringrequired

Event that triggers note generation.

updated_atstring (date-time)required

When the rule was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/auto-rules/{rule_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}

Get clinical note

Get a single clinical note by ID.

Parameters

Path Parameters
note_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
addendumsobject[]

Addendum notes linked to this note, ordered by created_at ASC.

case_idstring
contentstringrequired

Note content (rendered from template or manually entered).

content_editedbooleanrequired

Whether the content has been manually edited after generation.

content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
content_modeenumrequired

Authoritative content ownership mode. structured means template field responses are canonical; manual_override means templated content was user-edited; flattened_narrative means narrative content is canonical; signed_snapshot means the immutable signed snapshot is canonical.

flattened_narrativemanual_overridesigned_snapshotstructured
created_atstring (date-time)required

Timestamp when the note was created.

deleted_atstring (date-time)
field_response_itemsobject[]

Structured field responses for templated notes.

field_stateobject

Server-owned field-state evaluation for a note detail response.

generation_sourceenumrequired

How the note was created. One of: manual, template, auto_rule, ai_generated, ai_scribe.

ai_generatedai_scribeauto_rulemanualtemplate
idstring (uuid)required

Unique identifier of the clinical note.

is_lockedbooleanrequired

Whether the note is locked (signed notes are automatically locked).

is_signedbooleanrequired

Whether the note has been signed by a provider.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

note_datestring (date)required

Practice-local calendar date in YYYY-MM-DD format. Clients resolve the note location's IANA timezone before sending; the API stores and filters this as a date-only value, not a UTC datetime.

note_typeenumrequired

Type of note. One of: procedure, exam, hygiene, consultation, phone_call, general, addendum, treatment_plan, referral, lab.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
parent_note_uuidstring (uuid)
patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

primary_procedure_uuidstring (uuid)
procedure_uuidsstring (uuid)[]

UUIDs of charted procedures linked to this note.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

render_contract_versioninteger
rerender_snapshotobject

Metadata returned when a draft note is explicitly re-rendered from structured fields.

signed_atstring (date-time)
signed_byobject

Lightweight reference to a related entity — exposes UUID and optional name.

signed_contentstring
signed_content_formatenum
markdownplain_text
signed_plain_textstring
signing_readinessobject

Server-owned signing readiness summary for note detail and unsigned queue rows.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

template_sign_deadline_hoursinteger
template_uuidstring (uuid)
template_versioninteger
template_version_uuidstring (uuid)
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/favorites

List template favorites

List the current user's pinned note templates.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
itemsobject[]required

The user's pinned template favorites.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/favorites" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/option-lists

List clinical option lists

Parameters

Path Parameters
org_idstringrequired
Query Parameters
searchstring

Search key, name, description, category, or specialty.

categorystring

Filter by clinical category.

status"archived" | "draft" | "published"

Filter by status: draft, published, archived.

active_onlyboolean

Only return active option lists.

Default: true

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

Option lists on this page.

pageintegerrequired

Current page.

page_sizeintegerrequired

Items per page.

totalintegerrequired

Total matching option lists.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/option-lists" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}

Get clinical option list

Parameters

Path Parameters
option_list_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
categorystring
created_atstring (date-time)required

Creation timestamp.

descriptionstring
idstring (uuid)required

Option-list UUID.

is_activebooleanrequired

Whether available for use.

item_orderintegerrequired

Sort order.

keystringrequired

Stable practice-scoped key.

namestringrequired

Display name.

published_versioninteger
specialtystring
statusenumrequired

draft, published, or archived.

archiveddraftpublished
updated_atstring (date-time)required

Update timestamp.

usage_countinteger

Number of templates referencing this option list.

versionintegerrequired

Optimistic concurrency version.

versionsobject[]

Known versions.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}/usage

Get clinical option-list usage

Parameters

Path Parameters
option_list_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
itemsobject[]

Referencing fields.

option_list_idstring (uuid)required

Option-list UUID.

option_list_keystringrequired

Option-list key.

option_list_namestringrequired

Option-list name.

total_fieldsintegerrequired

Number of template fields referencing the list.

total_templatesintegerrequired

Number of distinct templates referencing the list.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}/usage" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/patients/{patient_uuid}/clinical-notes

List clinical notes

List clinical notes for a patient with optional filters.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
note_type"addendum" | "consultation" | "exam" | "general" | "hygiene" | "lab" | "phone_call" | "procedure" | "referral" | "treatment_plan"

Filter by note type (e.g., procedure, exam, addendum).

note_typesstring

Comma-separated list of note types. When provided, notes matching any listed type are returned.

date_fromstring

Include notes on or after this practice-local date (YYYY-MM-DD). Clients must compute this boundary from the note location's IANA timezone.

date_tostring

Include notes on or before this practice-local date (YYYY-MM-DD). Clients must compute this boundary from the note location's IANA timezone.

is_signedboolean

Filter by signed status.

provider_uuidstring

Filter by authoring provider UUID.

template_uuidstring

Filter by source clinical note template UUID.

generation_source"ai_generated" | "ai_scribe" | "auto_rule" | "manual" | "template"

Filter by generation source. One of: manual, template, auto_rule, ai_generated, ai_scribe.

case_idstring

Filter by case identifier.

searchstring

Text search across note content, note type, case id, patient name, provider name, and template name.

sort"created_asc" | "created_desc" | "newest" | "oldest" | "provider_az" | "signature_due_at"

Sort order. One of: newest, oldest, created_desc, created_asc, signature_due_at, provider_az.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of clinical notes on this page.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching notes across all pages.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/patients/{patient_uuid}/clinical-notes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/patients/{patient_uuid}/clinical-notes/cases

List clinical note case summaries

List compact per-case summaries for a patient.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/patients/{patient_uuid}/clinical-notes/cases" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/preset-blocks

List preset blocks

List field preset blocks with optional filters. Results are ordered by item_order ascending, then name ascending.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
categorystring

Filter by category.

active_onlyboolean

Only return active blocks.

Default: true

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of preset block records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total count matching the filters.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/preset-blocks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/preset-blocks/{block_uuid}

Get preset block

Get a single field preset block by UUID. Raises 404 if the block does not exist or has been archived.

Parameters

Path Parameters
block_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
categorystring
created_atstring (date-time)required

When the block was created.

descriptionstring
fieldsobject[]

Typed array of field definitions.

idstring (uuid)required

Public UUID of the preset block.

is_activebooleanrequired

Whether the block is active.

item_orderintegerrequired

Sort order.

namestringrequired

Display name.

updated_atstring (date-time)required

When the block was last updated.

usage_countinteger

Number of templates currently using fields from this preset block.

versionintegerrequired

Optimistic concurrency version.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/preset-blocks/{block_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/providers/{provider_uuid}/unsigned-notes

List unsigned notes for provider

List unsigned clinical notes for a specific provider. Provides the 'unsigned queue' workflow — notes awaiting provider signature.

Parameters

Path Parameters
provider_uuidstringrequired
org_idstringrequired
Query Parameters
date_fromstring

Include notes on or after this practice-local date (YYYY-MM-DD). Clients must compute this boundary from the note location's IANA timezone.

date_tostring

Include notes on or before this practice-local date (YYYY-MM-DD). Clients must compute this boundary from the note location's IANA timezone.

searchstring

Text search across note content, note type, case id, patient name, provider name, and template name.

sort"created_asc" | "created_desc" | "newest" | "oldest" | "provider_az" | "signature_due_at"

Sort order. One of: newest, oldest, created_desc, created_asc, signature_due_at, provider_az.

Default: "signature_due_at"

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of clinical notes on this page.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching notes across all pages.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/providers/{provider_uuid}/unsigned-notes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/settings

Get clinical notes settings

Get (or auto-create) the org-level clinical notes settings. If no settings row exists yet for the org, one is created with sensible defaults and returned. Raises 404 if the org context is not available (should not occur in normal use).

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
auto_save_interval_msintegerrequired

Milliseconds of inactivity before a note is auto-saved. 0 disables auto-save.

created_atstring (date-time)required

Timestamp when the settings record was created.

default_sign_deadline_hoursintegerrequired

Default hours after note creation before signing is overdue. 0 disables the default deadline. Used when the template has no explicit deadline.

default_sortenumrequired

Default sort order for the notes panel. One of: newest, oldest, created_desc.

created_descnewestoldest
idstring (uuid)required

Public UUID identifier for this settings record.

phrase_trigger_charstringrequired

Single character that activates smart phrase typeahead during note entry.

updated_atstring (date-time)required

Timestamp of the last update.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/settings" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/smart-phrases

List smart phrases

List smart phrases with optional filters. Supports filtering by scope, category, and owner. When no scope is specified and owner_uuid is provided, returns org phrases plus the user's personal phrases. Raises 404 if owner_uuid does not match a known user.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
scopestring

Filter by scope: org or personal.

categorystring

Filter by category.

owner_uuidstring

Filter personal phrases by owner UUID.

active_onlyboolean

If true, return only active phrases.

Default: true

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of smart phrase items.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching phrases.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/smart-phrases" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/smart-phrases/{phrase_uuid}

Get smart phrase

Get a single smart phrase by UUID. Raises 404 if not found.

Parameters

Path Parameters
phrase_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
categorystring
contentstringrequired

Template text with merge fields.

created_atstring (date-time)required

Timestamp when created.

idstring (uuid)required

Public UUID identifier.

is_activebooleanrequired

Whether the phrase is active.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

scopestringrequired

Visibility scope: org or personal.

titlestringrequired

Human-readable title.

trigger_keystringrequired

Shortcode trigger key.

updated_atstring (date-time)required

Timestamp of last update.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/smart-phrases/{phrase_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/smart-phrases/resolve

Resolve smart phrase typeahead

Resolve smart phrase typeahead by trigger_key prefix or title prefix. Returns matching phrases with override precedence: personal > location-scoped org > global org. When context UUIDs are provided (patient_uuid, provider_uuid, appointment_uuid), merge fields (e.g. ``{{patient.first_name}}``, ``{{provider.name}}``, ``{{appointment.date}}``) in the content are replaced with resolved values in ``resolved_content``. Raises 404 if any provided UUID does not match a known entity. Requires clinical.note:create permission (used during note authoring).

Parameters

Path Parameters
org_idstringrequired
Query Parameters
qstringrequired

Trigger key or title prefix to search for.

owner_uuidstring

Owner UUID to include personal phrases.

location_uuidstring

Location UUID for location-scoped resolution.

patient_uuidstring

Patient UUID for merge field resolution (e.g. {{patient.first_name}}).

provider_uuidstring

Provider UUID for merge field resolution (e.g. {{provider.name}}).

appointment_uuidstring

Appointment UUID for merge field resolution (e.g. {{appointment.date}}).

limitinteger

Maximum number of results.

Default: 10

Responses

200Successful Response
itemsobject[]required

List of matching smart phrases with resolved merge fields, with override precedence applied (personal > location org > global org).

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/smart-phrases/resolve" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/templates

List note templates

List clinical note templates with optional filters.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
searchstring

Text search across template name, description, category, and specialty.

category"administrative" | "endodontic" | "exam" | "general" | "implant" | "orthodontic" | "pediatric" | "periodontic" | "preventive" | "prosthodontic" | "restorative" | "surgery"

Filter by template category.

specialtystring

Filter by template specialty. Templates with no specialty tag remain visible in any specialty scope.

note_type"consultation" | "exam" | "general" | "hygiene" | "lab" | "phone_call" | "procedure" | "referral" | "treatment_plan"

Filter by note type.

status"draft" | "published"

Filter by template status (draft or published).

active_onlyboolean

When true, only return active templates.

Default: true

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of templates on this page.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching templates across all pages.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/templates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/templates/{template_uuid}

Get note template

Get a single clinical note template by UUID.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
categoryenumrequired

Template category.

administrativeendodonticexamgeneralimplantorthodonticpediatricperiodonticpreventiveprosthodonticrestorativesurgery
compiled_schema_versioninteger
completion_rulesobject
content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
created_atstring (date-time)required

Timestamp when the template was created.

descriptionstring
fieldsobject[]

Structured field definitions for the template.

idstring (uuid)required

Unique identifier of the template.

is_activebooleanrequired

Whether the template is active and available for use.

is_systembooleanrequired

Whether this is a system-provided immutable template.

item_orderintegerrequired

Display order among templates.

namestringrequired

Display name of the template.

note_typeenumrequired

Type of note this template produces.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
published_atstring (date-time)
published_versioninteger
render_templatestring
specialtystring
statusenumrequired

Template status. One of: draft, published.

draftpublished
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/{template_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/impact

Get template impact analysis

Analyze the impact of modifying or deleting a template. Returns counts of sub-template usages, auto-note rules, notes created, and unsigned notes that reference this template. Raises 404 if the template does not exist.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
auto_note_rulesobject[]

Active auto-note rules using this template.

notes_createdintegerrequired

Total clinical notes created from this template.

sub_template_usagesobject[]

Templates that reference this one as a sub-template field.

template_uuidstring (uuid)required

UUID of the analyzed template.

unsigned_notesobject[]

Sample of unsigned notes (first 10) created from this template.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/impact" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/prefill-suggestions

Get prefill suggestions for a template

Return per-field suggested values derived from the current user's (and, as fallback, the practice's) historical signed notes for this template. Only structured fields (single_select, multi_select, boolean) with sufficient support are returned. Raises 404 if the template does not exist.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
suggestionsobjectrequired

Map of field_key -> suggested value. Only eligible structured fields (single_select, multi_select, boolean) with sufficient support appear.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/prefill-suggestions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/versions

Get template version history

Return the version history for a template, derived from audit log entries. Each entry represents a create, update, publish, or archive action with the version number, timestamp, actor name, and change summary. Raises 404 if the template does not exist.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/versions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/templates/merge-fields

List clinical merge fields

Return available merge fields for clinical note templates. Groups fields by namespace. Each field is a ``namespace.property`` string (e.g. ``patient.first_name``). Used by the template editor to populate the merge field insertion dropdown.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
groupsobject[]required
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/merge-fields" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/templates/specialties

List note template specialties

List distinct template specialty labels for picker filters.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
status"draft" | "published"

Filter specialties by template status.

Default: "published"

active_onlyboolean

When true, only include active templates.

Default: true

Responses

200Successful Response
itemsstring[]required

Sorted distinct specialty labels from matching note templates.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/specialties" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical-notes/templates/summaries

List note template summaries

List compact template summaries for quick-access picker surfaces.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
template_uuidsstring[]

Template UUIDs to validate and summarize.

status"draft" | "published"

Filter summaries by template status.

Default: "published"

active_onlyboolean

When true, only include active templates.

Default: true

Responses

200Successful Response
itemsobject[]required

Validated template summaries.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/summaries" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/clinical-notes/auto-rules

Create auto-note rule

Create a new auto-note rule. Raises 422 if trigger_event or merge_strategy is invalid, or if neither procedure_code_pattern nor procedure_category is provided. Raises 404 if the referenced template does not exist. Raises 422 if the template is not active or not published.

Parameters

Path Parameters
org_idstringrequired

Request Body

descriptionstring
is_activeboolean

Whether the rule is active and will trigger note generation.

location_uuidstring (uuid)
merge_strategystring

How auto-generated notes are merged when multiple procedures trigger the same rule. One of: per_procedure, per_appointment, per_day.

namestringrequired

Display name for the auto-note rule.

priorityinteger

Rule priority — higher values are evaluated first.

procedure_categorystring
procedure_code_patternstring
provider_uuidstring (uuid)
template_uuidstring (uuid)required

UUID of the clinical note template to use.

trigger_eventstringrequired

Event that triggers note generation. One of: on_procedure_complete, on_procedure_treatment_planned.

Responses

201Successful Response
created_atstring (date-time)required

When the rule was created.

descriptionstring
idstring (uuid)required

Public UUID of the auto-note rule.

is_activebooleanrequired

Whether the rule is active.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

merge_strategystringrequired

How auto-generated notes are merged.

namestringrequired

Display name of the rule.

priorityintegerrequired

Rule priority (higher = evaluated first).

procedure_categorystring
procedure_code_patternstring
providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

trigger_eventstringrequired

Event that triggers note generation.

updated_atstring (date-time)required

When the rule was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/auto-rules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "string",
    "is_active": true,
    "location_uuid": "string",
    "merge_strategy": "per_procedure",
    "name": "string",
    "template_uuid": "00000000-0000-0000-0000-000000000000",
    "trigger_event": "string"
  }'
post/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/addendums

Create addendum

Create an addendum to a signed clinical note.

Parameters

Path Parameters
note_uuidstringrequired
org_idstringrequired

Request Body

contentstring
note_datestring (date)required

Practice-local calendar date in YYYY-MM-DD format. Clients resolve the note location's IANA timezone before sending; the API stores and filters this as a date-only value, not a UTC datetime.

provider_uuidstring (uuid)required

UUID of the provider creating the addendum.

Responses

201Successful Response
case_idstring
contentstringrequired

Note content (rendered from template or manually entered).

content_editedbooleanrequired

Whether the content has been manually edited after generation.

content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
content_modeenumrequired

Authoritative content ownership mode. structured means template field responses are canonical; manual_override means templated content was user-edited; flattened_narrative means narrative content is canonical; signed_snapshot means the immutable signed snapshot is canonical.

flattened_narrativemanual_overridesigned_snapshotstructured
created_atstring (date-time)required

Timestamp when the note was created.

deleted_atstring (date-time)
generation_sourceenumrequired

How the note was created. One of: manual, template, auto_rule, ai_generated, ai_scribe.

ai_generatedai_scribeauto_rulemanualtemplate
idstring (uuid)required

Unique identifier of the clinical note.

is_lockedbooleanrequired

Whether the note is locked (signed notes are automatically locked).

is_signedbooleanrequired

Whether the note has been signed by a provider.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

note_datestring (date)required

Practice-local calendar date in YYYY-MM-DD format. Clients resolve the note location's IANA timezone before sending; the API stores and filters this as a date-only value, not a UTC datetime.

note_typeenumrequired

Type of note. One of: procedure, exam, hygiene, consultation, phone_call, general, addendum, treatment_plan, referral, lab.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
parent_note_uuidstring (uuid)
patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

render_contract_versioninteger
rerender_snapshotobject

Metadata returned when a draft note is explicitly re-rendered from structured fields.

signed_atstring (date-time)
signed_byobject

Lightweight reference to a related entity — exposes UUID and optional name.

signed_contentstring
signed_content_formatenum
markdownplain_text
signed_plain_textstring
signing_readinessobject

Server-owned signing readiness summary for note detail and unsigned queue rows.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

template_sign_deadline_hoursinteger
template_uuidstring (uuid)
template_versioninteger
template_version_uuidstring (uuid)
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/addendums" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "string",
    "note_date": "2025-01-15",
    "provider_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/addendums/{addendum_uuid}/sign

Sign addendum

Sign and lock a draft addendum attached to a signed clinical note.

Parameters

Path Parameters
note_uuidstringrequired
addendum_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current addendum version for optimistic concurrency — rejected with 409 if stale.

signed_by_uuidstring (uuid)required

UUID of the provider signing the addendum.

Responses

200Successful Response
case_idstring
contentstringrequired

Note content (rendered from template or manually entered).

content_editedbooleanrequired

Whether the content has been manually edited after generation.

content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
content_modeenumrequired

Authoritative content ownership mode. structured means template field responses are canonical; manual_override means templated content was user-edited; flattened_narrative means narrative content is canonical; signed_snapshot means the immutable signed snapshot is canonical.

flattened_narrativemanual_overridesigned_snapshotstructured
created_atstring (date-time)required

Timestamp when the note was created.

deleted_atstring (date-time)
generation_sourceenumrequired

How the note was created. One of: manual, template, auto_rule, ai_generated, ai_scribe.

ai_generatedai_scribeauto_rulemanualtemplate
idstring (uuid)required

Unique identifier of the clinical note.

is_lockedbooleanrequired

Whether the note is locked (signed notes are automatically locked).

is_signedbooleanrequired

Whether the note has been signed by a provider.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

note_datestring (date)required

Practice-local calendar date in YYYY-MM-DD format. Clients resolve the note location's IANA timezone before sending; the API stores and filters this as a date-only value, not a UTC datetime.

note_typeenumrequired

Type of note. One of: procedure, exam, hygiene, consultation, phone_call, general, addendum, treatment_plan, referral, lab.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
parent_note_uuidstring (uuid)
patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

render_contract_versioninteger
rerender_snapshotobject

Metadata returned when a draft note is explicitly re-rendered from structured fields.

signed_atstring (date-time)
signed_byobject

Lightweight reference to a related entity — exposes UUID and optional name.

signed_contentstring
signed_content_formatenum
markdownplain_text
signed_plain_textstring
signing_readinessobject

Server-owned signing readiness summary for note detail and unsigned queue rows.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

template_sign_deadline_hoursinteger
template_uuidstring (uuid)
template_versioninteger
template_version_uuidstring (uuid)
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/addendums/{addendum_uuid}/sign" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "signed_by_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/procedures

Link procedures to note

Link charted procedures to a clinical note. Duplicate links are silently skipped.

Parameters

Path Parameters
note_uuidstringrequired
org_idstringrequired

Request Body

primary_procedure_uuidstring (uuid)
procedure_uuidsstring (uuid)[]required

List of charted procedure UUIDs to link to the note.

Responses

200Successful Response
itemsobject[]required

List of procedure links.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/procedures" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_procedure_uuid": "string",
    "procedure_uuids": []
  }'
post/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/sign

Sign clinical note

Sign and lock a clinical note.

Parameters

Path Parameters
note_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

signed_by_uuidstring (uuid)required

UUID of the provider signing the note.

Responses

200Successful Response
case_idstring
contentstringrequired

Note content (rendered from template or manually entered).

content_editedbooleanrequired

Whether the content has been manually edited after generation.

content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
content_modeenumrequired

Authoritative content ownership mode. structured means template field responses are canonical; manual_override means templated content was user-edited; flattened_narrative means narrative content is canonical; signed_snapshot means the immutable signed snapshot is canonical.

flattened_narrativemanual_overridesigned_snapshotstructured
created_atstring (date-time)required

Timestamp when the note was created.

deleted_atstring (date-time)
generation_sourceenumrequired

How the note was created. One of: manual, template, auto_rule, ai_generated, ai_scribe.

ai_generatedai_scribeauto_rulemanualtemplate
idstring (uuid)required

Unique identifier of the clinical note.

is_lockedbooleanrequired

Whether the note is locked (signed notes are automatically locked).

is_signedbooleanrequired

Whether the note has been signed by a provider.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

note_datestring (date)required

Practice-local calendar date in YYYY-MM-DD format. Clients resolve the note location's IANA timezone before sending; the API stores and filters this as a date-only value, not a UTC datetime.

note_typeenumrequired

Type of note. One of: procedure, exam, hygiene, consultation, phone_call, general, addendum, treatment_plan, referral, lab.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
parent_note_uuidstring (uuid)
patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

render_contract_versioninteger
rerender_snapshotobject

Metadata returned when a draft note is explicitly re-rendered from structured fields.

signed_atstring (date-time)
signed_byobject

Lightweight reference to a related entity — exposes UUID and optional name.

signed_contentstring
signed_content_formatenum
markdownplain_text
signed_plain_textstring
signing_readinessobject

Server-owned signing readiness summary for note detail and unsigned queue rows.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

template_sign_deadline_hoursinteger
template_uuidstring (uuid)
template_versioninteger
template_version_uuidstring (uuid)
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/sign" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "signed_by_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical-notes/clinical-notes/batch-sign

Batch sign notes

Sign multiple clinical notes in one call. Each note is signed independently — failures do not roll back successes. Returns separate lists of successfully signed notes and failures. Raises 404 if the signing provider does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

notesobject[]required

List of notes to sign, each with UUID and base_version.

signed_by_uuidstring (uuid)required

UUID of the provider performing the signing.

Responses

200Successful Response
failedobject[]

Notes that failed to sign.

signedobject[]

Notes that were successfully signed.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/batch-sign" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": [],
    "signed_by_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical-notes/clinical-notes/batch-sign/preview

Preview batch note signing

Preview selected notes before batch signing without mutating them.

Parameters

Path Parameters
org_idstringrequired

Request Body

notesobject[]required

List of notes to sign, each with UUID and base_version.

signed_by_uuidstring (uuid)required

UUID of the provider performing the signing.

Responses

200Successful Response
blocked_countintegerrequired

Number of selected notes blocked by signing rules.

itemsobject[]

Ordered preview results for selected notes.

not_found_countintegerrequired

Number of selected notes that no longer exist.

ready_countintegerrequired

Number of selected notes ready to sign.

stale_countintegerrequired

Number of selected notes with stale base_version values.

totalintegerrequired

Number of selected notes evaluated.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/batch-sign/preview" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": [],
    "signed_by_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical-notes/favorites

Add template favorite

Pin a note template as a favorite for the current user. Raises 409 if the template is already a favorite for this user.

Parameters

Path Parameters
org_idstringrequired

Request Body

item_orderinteger

Sort order for the favorite (lower values appear first).

template_uuidstring (uuid)required

UUID of the template to pin as a favorite.

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the favorite was created.

idstring (uuid)required

UUID of the favorite record.

item_orderintegerrequired

Sort order for the favorite.

template_categoryenum
administrativeendodonticexamgeneralimplantorthodonticpediatricperiodonticpreventiveprosthodonticrestorativesurgery
template_is_activeboolean
template_namestring
template_note_typeenum
addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
template_statusenum
draftpublished
template_uuidstring (uuid)required
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/favorites" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "item_order": 0,
    "template_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical-notes/option-lists

Create clinical option list

Parameters

Path Parameters
org_idstringrequired

Request Body

categorystring
descriptionstring
item_orderinteger

Sort order in admin lists.

keystringrequired

Stable practice-scoped key, e.g. anesthetics.

namestringrequired

Display name.

optionsobject[]required

Initial draft options.

specialtystring

Responses

201Successful Response
categorystring
created_atstring (date-time)required

Creation timestamp.

descriptionstring
idstring (uuid)required

Option-list UUID.

is_activebooleanrequired

Whether available for use.

item_orderintegerrequired

Sort order.

keystringrequired

Stable practice-scoped key.

namestringrequired

Display name.

published_versioninteger
specialtystring
statusenumrequired

draft, published, or archived.

archiveddraftpublished
updated_atstring (date-time)required

Update timestamp.

usage_countinteger

Number of templates referencing this option list.

versionintegerrequired

Optimistic concurrency version.

versionsobject[]

Known versions.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/option-lists" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "string",
    "description": "string",
    "item_order": 0,
    "key": "string",
    "name": "string",
    "options": []
  }'
post/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}/publish

Publish clinical option list

Parameters

Path Parameters
option_list_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current option-list version for optimistic concurrency.

Responses

200Successful Response
categorystring
created_atstring (date-time)required

Creation timestamp.

descriptionstring
idstring (uuid)required

Option-list UUID.

is_activebooleanrequired

Whether available for use.

item_orderintegerrequired

Sort order.

keystringrequired

Stable practice-scoped key.

namestringrequired

Display name.

published_versioninteger
specialtystring
statusenumrequired

draft, published, or archived.

archiveddraftpublished
updated_atstring (date-time)required

Update timestamp.

usage_countinteger

Number of templates referencing this option list.

versionintegerrequired

Optimistic concurrency version.

versionsobject[]

Known versions.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}/publish" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1
  }'
post/api/v1/{org_id}/clinical-notes/patients/{patient_uuid}/clinical-notes

Create draft clinical note

Create a persisted draft clinical note for a patient.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

appointment_uuidstring (uuid)
case_idstring
contentstring
content_editedboolean
content_formatenum
markdownplain_text
field_responsesobject
location_uuidstring (uuid)required

UUID of the location where the note is created.

note_datestring (date)required

Practice-local calendar date in YYYY-MM-DD format. Clients resolve the note location's IANA timezone before sending; the API stores and filters this as a date-only value, not a UTC datetime.

note_typeenumrequired

Type of non-addendum note. Addendums must use the dedicated addendum endpoint.

consultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
primary_procedure_uuidstring (uuid)
procedure_uuidsstring (uuid)[]
provider_uuidstring (uuid)required

UUID of the authoring provider.

template_uuidstring (uuid)

Responses

201Successful Response
case_idstring
contentstringrequired

Note content (rendered from template or manually entered).

content_editedbooleanrequired

Whether the content has been manually edited after generation.

content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
content_modeenumrequired

Authoritative content ownership mode. structured means template field responses are canonical; manual_override means templated content was user-edited; flattened_narrative means narrative content is canonical; signed_snapshot means the immutable signed snapshot is canonical.

flattened_narrativemanual_overridesigned_snapshotstructured
created_atstring (date-time)required

Timestamp when the note was created.

deleted_atstring (date-time)
generation_sourceenumrequired

How the note was created. One of: manual, template, auto_rule, ai_generated, ai_scribe.

ai_generatedai_scribeauto_rulemanualtemplate
idstring (uuid)required

Unique identifier of the clinical note.

is_lockedbooleanrequired

Whether the note is locked (signed notes are automatically locked).

is_signedbooleanrequired

Whether the note has been signed by a provider.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

note_datestring (date)required

Practice-local calendar date in YYYY-MM-DD format. Clients resolve the note location's IANA timezone before sending; the API stores and filters this as a date-only value, not a UTC datetime.

note_typeenumrequired

Type of note. One of: procedure, exam, hygiene, consultation, phone_call, general, addendum, treatment_plan, referral, lab.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
parent_note_uuidstring (uuid)
patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

render_contract_versioninteger
rerender_snapshotobject

Metadata returned when a draft note is explicitly re-rendered from structured fields.

signed_atstring (date-time)
signed_byobject

Lightweight reference to a related entity — exposes UUID and optional name.

signed_contentstring
signed_content_formatenum
markdownplain_text
signed_plain_textstring
signing_readinessobject

Server-owned signing readiness summary for note detail and unsigned queue rows.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

template_sign_deadline_hoursinteger
template_uuidstring (uuid)
template_versioninteger
template_version_uuidstring (uuid)
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/patients/{patient_uuid}/clinical-notes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_uuid": "string",
    "case_id": "string",
    "content": "string",
    "content_edited": null,
    "content_format": "string",
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "note_date": "2025-01-15",
    "note_type": "consultation",
    "provider_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical-notes/preset-blocks

Create preset block

Create a new field preset block. Raises 409 if a preset block with the same name already exists.

Parameters

Path Parameters
org_idstringrequired

Request Body

categorystring
descriptionstring
fieldsobject[]

Array of typed field definitions.

is_activeboolean

Whether the preset block is active and visible for selection.

item_orderinteger

Sort order within category listings. Lower values appear first.

namestringrequired

Unique display name for the preset block.

Responses

201Successful Response
categorystring
created_atstring (date-time)required

When the block was created.

descriptionstring
fieldsobject[]

Typed array of field definitions.

idstring (uuid)required

Public UUID of the preset block.

is_activebooleanrequired

Whether the block is active.

item_orderintegerrequired

Sort order.

namestringrequired

Display name.

updated_atstring (date-time)required

When the block was last updated.

usage_countinteger

Number of templates currently using fields from this preset block.

versionintegerrequired

Optimistic concurrency version.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/preset-blocks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "string",
    "description": "string",
    "fields": [],
    "is_active": true,
    "item_order": 0,
    "name": "string"
  }'
post/api/v1/{org_id}/clinical-notes/smart-phrases

Create smart phrase

Create a new smart phrase. Validates trigger_key format. Raises 409 if a phrase with the same trigger_key already exists in the same scope. Raises 422 for invalid trigger_key format or scope.

Parameters

Path Parameters
org_idstringrequired

Request Body

categorystring
contentstringrequired

Template text with optional merge fields like {{patient.first_name}}.

is_activeboolean

Whether the phrase is active and available for use.

location_uuidstring (uuid)
owner_uuidstring (uuid)
scopestring

Visibility scope. One of: org, personal.

titlestringrequired

Human-readable title for the smart phrase.

trigger_keystringrequired

Shortcode trigger (lowercase alphanumeric, hyphens, underscores). Must match ^[a-z0-9][a-z0-9\-_]{1,49}$.

Responses

201Successful Response
categorystring
contentstringrequired

Template text with merge fields.

created_atstring (date-time)required

Timestamp when created.

idstring (uuid)required

Public UUID identifier.

is_activebooleanrequired

Whether the phrase is active.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

scopestringrequired

Visibility scope: org or personal.

titlestringrequired

Human-readable title.

trigger_keystringrequired

Shortcode trigger key.

updated_atstring (date-time)required

Timestamp of last update.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/smart-phrases" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "string",
    "content": "string",
    "is_active": true,
    "location_uuid": "string",
    "owner_uuid": "string",
    "title": "string",
    "trigger_key": "string"
  }'
post/api/v1/{org_id}/clinical-notes/templates

Create note template

Create a new clinical note template. Optionally include a ``fields`` array to create structured field definitions. Raises 409 if a template with the same name already exists.

Parameters

Path Parameters
org_idstringrequired

Request Body

categoryenumrequired

Template category. One of: exam, restorative, endodontic, periodontic, preventive, surgery, orthodontic, prosthodontic, implant, pediatric, general, administrative.

administrativeendodonticexamgeneralimplantorthodonticpediatricperiodonticpreventiveprosthodonticrestorativesurgery
completion_rulesobject
content_formatenum
markdownplain_text
descriptionstring
fieldsobject[]
namestringrequired

Display name of the template.

note_typeenumrequired

Type of note this template produces. One of: procedure, exam, hygiene, consultation, phone_call, general, treatment_plan, referral, lab.

consultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
render_templatestring
specialtystring

Responses

201Successful Response
categoryenumrequired

Template category.

administrativeendodonticexamgeneralimplantorthodonticpediatricperiodonticpreventiveprosthodonticrestorativesurgery
compiled_schema_versioninteger
completion_rulesobject
content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
created_atstring (date-time)required

Timestamp when the template was created.

descriptionstring
fieldsobject[]

Structured field definitions for the template.

idstring (uuid)required

Unique identifier of the template.

is_activebooleanrequired

Whether the template is active and available for use.

is_systembooleanrequired

Whether this is a system-provided immutable template.

item_orderintegerrequired

Display order among templates.

namestringrequired

Display name of the template.

note_typeenumrequired

Type of note this template produces.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
published_atstring (date-time)
published_versioninteger
render_templatestring
specialtystring
statusenumrequired

Template status. One of: draft, published.

draftpublished
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/templates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "administrative",
    "completion_rules": null,
    "content_format": "string",
    "description": "string",
    "fields": null,
    "name": "string",
    "note_type": "consultation"
  }'
post/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/apply-preset

Apply preset block to template

Apply a field preset block to a template by copying its field definitions. Copies all fields from the specified preset block into the template's field list at the given insertion order. Raises 404 if the template or preset block does not exist. Raises 422 if the preset block is inactive.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Request Body

block_namestringrequired

Display name for the applied block section within the template.

insert_at_orderinteger

Order position at which to insert the preset fields. Defaults to 0 (beginning).

preset_block_uuidstring (uuid)required

UUID of the FieldPresetBlock to apply to the template.

Responses

200Successful Response
categoryenumrequired

Template category.

administrativeendodonticexamgeneralimplantorthodonticpediatricperiodonticpreventiveprosthodonticrestorativesurgery
compiled_schema_versioninteger
completion_rulesobject
content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
created_atstring (date-time)required

Timestamp when the template was created.

descriptionstring
fieldsobject[]

Structured field definitions for the template.

idstring (uuid)required

Unique identifier of the template.

is_activebooleanrequired

Whether the template is active and available for use.

is_systembooleanrequired

Whether this is a system-provided immutable template.

item_orderintegerrequired

Display order among templates.

namestringrequired

Display name of the template.

note_typeenumrequired

Type of note this template produces.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
published_atstring (date-time)
published_versioninteger
render_templatestring
specialtystring
statusenumrequired

Template status. One of: draft, published.

draftpublished
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/apply-preset" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "block_name": "string",
    "insert_at_order": 0,
    "preset_block_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/lint

Lint template

Run lint checks on a template's render_template and field definitions. Returns a list of errors (blocking) and warnings (non-blocking). Does not modify the template. Raises 404 if the template does not exist.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
errorsobject[]

Blocking issues that prevent publishing.

validbooleanrequired

True if no errors were found (warnings are non-blocking).

warningsobject[]

Non-blocking suggestions.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/lint" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/publish

Publish template

Publish a template: run lint, compile render_template and completion_rules, freeze version. Raises 404 if the template does not exist. Raises 409 if base_version is stale. Raises 422 if lint finds errors.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

Responses

200Successful Response
impactobjectrequired

Template impact analysis returned with the publish result.

lint_resultobjectrequired

Backend lint result used to authorize publishing.

published_template_version_uuidstring (uuid)
published_versionintegerrequired

Immutable published version number created or acknowledged.

templateobjectrequired

Output schema for a clinical note template.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/{template_uuid}/publish" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1
  }'
post/api/v1/{org_id}/clinical-notes/templates/render-preview

Preview note template rendering

Render a draft template through the backend materialization path.

Parameters

Path Parameters
org_idstringrequired

Request Body

field_responsesobject
fieldsobject[]

Draft structured field definitions used for preview materialization.

patient_uuidstring (uuid)
render_templatestringrequired

Render template using {{field:key}} syntax.

Responses

200Successful Response
contentstringrequired

Rendered HTML preview.

field_valuesobject

Display-ready field values used to render token chips.

render_contract_versionintegerrequired

Backend render/materialization contract version used for this preview.

unresolved_field_keysstring[]

Field token keys referenced by the template but absent from the supplied field definitions.

unresolved_merge_keysstring[]

Merge token keys not known to the clinical merge-field registry.

warningsobject[]

Non-blocking materialization warnings.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/render-preview" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_responses": null,
    "fields": [],
    "patient_uuid": "string",
    "render_template": "string"
  }'
put/api/v1/{org_id}/clinical-notes/settings

Update clinical notes settings

Update the org-level clinical notes settings (partial update). Auto-creates defaults first if no settings row exists yet. Only provided fields are applied — omit a field to leave it unchanged. Raises 422 for invalid field values (e.g., phrase_trigger_char longer than 1 character).

Parameters

Path Parameters
org_idstringrequired

Request Body

auto_save_interval_msinteger
default_sign_deadline_hoursinteger
default_sortenum
created_descnewestoldest
phrase_trigger_charstring

Responses

200Successful Response
auto_save_interval_msintegerrequired

Milliseconds of inactivity before a note is auto-saved. 0 disables auto-save.

created_atstring (date-time)required

Timestamp when the settings record was created.

default_sign_deadline_hoursintegerrequired

Default hours after note creation before signing is overdue. 0 disables the default deadline. Used when the template has no explicit deadline.

default_sortenumrequired

Default sort order for the notes panel. One of: newest, oldest, created_desc.

created_descnewestoldest
idstring (uuid)required

Public UUID identifier for this settings record.

phrase_trigger_charstringrequired

Single character that activates smart phrase typeahead during note entry.

updated_atstring (date-time)required

Timestamp of the last update.

422Validation Error
detailobject[]
curl
curl -X PUT "https://api.example.com/api/v1/{org_id}/clinical-notes/settings" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_save_interval_ms": 1,
    "default_sign_deadline_hours": 1,
    "default_sort": "string",
    "phrase_trigger_char": "string"
  }'
patch/api/v1/{org_id}/clinical-notes/auto-rules/{rule_uuid}

Update auto-note rule

Update an auto-note rule. Raises 404 if the rule does not exist. Raises 409 if the base_version does not match (version conflict). Raises 422 if trigger_event or merge_strategy is invalid.

Parameters

Path Parameters
rule_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency -- rejected with 409 if stale.

descriptionstring
is_activeboolean
location_uuidstring (uuid)
merge_strategystring
namestring
priorityinteger
procedure_categorystring
procedure_code_patternstring
provider_uuidstring (uuid)
template_uuidstring (uuid)
trigger_eventstring

Responses

200Successful Response
created_atstring (date-time)required

When the rule was created.

descriptionstring
idstring (uuid)required

Public UUID of the auto-note rule.

is_activebooleanrequired

Whether the rule is active.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

merge_strategystringrequired

How auto-generated notes are merged.

namestringrequired

Display name of the rule.

priorityintegerrequired

Rule priority (higher = evaluated first).

procedure_categorystring
procedure_code_patternstring
providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

trigger_eventstringrequired

Event that triggers note generation.

updated_atstring (date-time)required

When the rule was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical-notes/auto-rules/{rule_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "description": "string",
    "is_active": null,
    "location_uuid": "string",
    "merge_strategy": "string"
  }'
patch/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}

Save draft clinical note

Save a draft clinical note (only if unlocked).

Parameters

Path Parameters
note_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

case_idstring
contentstring
content_editedboolean
content_formatenum
markdownplain_text
field_responsesobject
force_rerenderboolean

If true and note has a template, re-render content from template using current field_values. Ignores any content update in this request.

location_uuidstring (uuid)
note_datestring (date)
note_typeenum
consultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
provider_uuidstring (uuid)

Responses

200Successful Response
case_idstring
contentstringrequired

Note content (rendered from template or manually entered).

content_editedbooleanrequired

Whether the content has been manually edited after generation.

content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
content_modeenumrequired

Authoritative content ownership mode. structured means template field responses are canonical; manual_override means templated content was user-edited; flattened_narrative means narrative content is canonical; signed_snapshot means the immutable signed snapshot is canonical.

flattened_narrativemanual_overridesigned_snapshotstructured
created_atstring (date-time)required

Timestamp when the note was created.

deleted_atstring (date-time)
generation_sourceenumrequired

How the note was created. One of: manual, template, auto_rule, ai_generated, ai_scribe.

ai_generatedai_scribeauto_rulemanualtemplate
idstring (uuid)required

Unique identifier of the clinical note.

is_lockedbooleanrequired

Whether the note is locked (signed notes are automatically locked).

is_signedbooleanrequired

Whether the note has been signed by a provider.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

note_datestring (date)required

Practice-local calendar date in YYYY-MM-DD format. Clients resolve the note location's IANA timezone before sending; the API stores and filters this as a date-only value, not a UTC datetime.

note_typeenumrequired

Type of note. One of: procedure, exam, hygiene, consultation, phone_call, general, addendum, treatment_plan, referral, lab.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
parent_note_uuidstring (uuid)
patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

render_contract_versioninteger
rerender_snapshotobject

Metadata returned when a draft note is explicitly re-rendered from structured fields.

signed_atstring (date-time)
signed_byobject

Lightweight reference to a related entity — exposes UUID and optional name.

signed_contentstring
signed_content_formatenum
markdownplain_text
signed_plain_textstring
signing_readinessobject

Server-owned signing readiness summary for note detail and unsigned queue rows.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

template_sign_deadline_hoursinteger
template_uuidstring (uuid)
template_versioninteger
template_version_uuidstring (uuid)
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "case_id": "string",
    "content": "string",
    "content_edited": null,
    "content_format": "string"
  }'
patch/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/addendums/{addendum_uuid}

Update addendum

Update a draft addendum attached to a signed clinical note.

Parameters

Path Parameters
note_uuidstringrequired
addendum_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current addendum version for optimistic concurrency — rejected with 409 if stale.

contentstringrequired

Addendum content.

Responses

200Successful Response
case_idstring
contentstringrequired

Note content (rendered from template or manually entered).

content_editedbooleanrequired

Whether the content has been manually edited after generation.

content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
content_modeenumrequired

Authoritative content ownership mode. structured means template field responses are canonical; manual_override means templated content was user-edited; flattened_narrative means narrative content is canonical; signed_snapshot means the immutable signed snapshot is canonical.

flattened_narrativemanual_overridesigned_snapshotstructured
created_atstring (date-time)required

Timestamp when the note was created.

deleted_atstring (date-time)
generation_sourceenumrequired

How the note was created. One of: manual, template, auto_rule, ai_generated, ai_scribe.

ai_generatedai_scribeauto_rulemanualtemplate
idstring (uuid)required

Unique identifier of the clinical note.

is_lockedbooleanrequired

Whether the note is locked (signed notes are automatically locked).

is_signedbooleanrequired

Whether the note has been signed by a provider.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

note_datestring (date)required

Practice-local calendar date in YYYY-MM-DD format. Clients resolve the note location's IANA timezone before sending; the API stores and filters this as a date-only value, not a UTC datetime.

note_typeenumrequired

Type of note. One of: procedure, exam, hygiene, consultation, phone_call, general, addendum, treatment_plan, referral, lab.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
parent_note_uuidstring (uuid)
patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

render_contract_versioninteger
rerender_snapshotobject

Metadata returned when a draft note is explicitly re-rendered from structured fields.

signed_atstring (date-time)
signed_byobject

Lightweight reference to a related entity — exposes UUID and optional name.

signed_contentstring
signed_content_formatenum
markdownplain_text
signed_plain_textstring
signing_readinessobject

Server-owned signing readiness summary for note detail and unsigned queue rows.

templateobject

Lightweight reference to a related entity — exposes UUID and optional name.

template_sign_deadline_hoursinteger
template_uuidstring (uuid)
template_versioninteger
template_version_uuidstring (uuid)
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/addendums/{addendum_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "content": "string"
  }'
patch/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}

Update clinical option list

Parameters

Path Parameters
option_list_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current option-list version for optimistic concurrency.

categorystring
descriptionstring
is_activeboolean
item_orderinteger
keystring
namestring
optionsobject[]
specialtystring

Responses

200Successful Response
categorystring
created_atstring (date-time)required

Creation timestamp.

descriptionstring
idstring (uuid)required

Option-list UUID.

is_activebooleanrequired

Whether available for use.

item_orderintegerrequired

Sort order.

keystringrequired

Stable practice-scoped key.

namestringrequired

Display name.

published_versioninteger
specialtystring
statusenumrequired

draft, published, or archived.

archiveddraftpublished
updated_atstring (date-time)required

Update timestamp.

usage_countinteger

Number of templates referencing this option list.

versionintegerrequired

Optimistic concurrency version.

versionsobject[]

Known versions.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "category": "string",
    "description": "string",
    "is_active": null,
    "item_order": 1
  }'
patch/api/v1/{org_id}/clinical-notes/preset-blocks/{block_uuid}

Update preset block

Update a field preset block. Raises 404 if the block does not exist. Raises 409 if base_version is stale or name conflicts with an existing block.

Parameters

Path Parameters
block_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

categorystring
descriptionstring
fieldsobject[]
is_activeboolean
item_orderinteger
namestring

Responses

200Successful Response
categorystring
created_atstring (date-time)required

When the block was created.

descriptionstring
fieldsobject[]

Typed array of field definitions.

idstring (uuid)required

Public UUID of the preset block.

is_activebooleanrequired

Whether the block is active.

item_orderintegerrequired

Sort order.

namestringrequired

Display name.

updated_atstring (date-time)required

When the block was last updated.

usage_countinteger

Number of templates currently using fields from this preset block.

versionintegerrequired

Optimistic concurrency version.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical-notes/preset-blocks/{block_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "category": "string",
    "description": "string",
    "fields": null,
    "is_active": null
  }'
patch/api/v1/{org_id}/clinical-notes/smart-phrases/{phrase_uuid}

Update smart phrase

Update a smart phrase (partial update). Requires base_version for optimistic concurrency. Raises 404 if not found, 409 on version conflict or duplicate trigger_key.

Parameters

Path Parameters
phrase_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

categorystring
contentstring
is_activeboolean
location_uuidstring (uuid)
owner_uuidstring (uuid)
scopestring
titlestring
trigger_keystring

Responses

200Successful Response
categorystring
contentstringrequired

Template text with merge fields.

created_atstring (date-time)required

Timestamp when created.

idstring (uuid)required

Public UUID identifier.

is_activebooleanrequired

Whether the phrase is active.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

scopestringrequired

Visibility scope: org or personal.

titlestringrequired

Human-readable title.

trigger_keystringrequired

Shortcode trigger key.

updated_atstring (date-time)required

Timestamp of last update.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical-notes/smart-phrases/{phrase_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "category": "string",
    "content": "string",
    "is_active": null,
    "location_uuid": "string"
  }'
patch/api/v1/{org_id}/clinical-notes/templates/{template_uuid}

Update note template

Update a clinical note template. Optionally include a ``fields`` array to replace structured field definitions. Published templates are automatically transitioned back to draft on edit. Raises 404 if the template does not exist. Raises 409 if base_version is stale or name conflicts with an existing template.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency — rejected with 409 if stale.

categoryenum
administrativeendodonticexamgeneralimplantorthodonticpediatricperiodonticpreventiveprosthodonticrestorativesurgery
completion_rulesobject
content_formatenum
markdownplain_text
descriptionstring
fieldsobject[]
is_activeboolean
namestring
note_typeenum
consultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
render_templatestring
specialtystring

Responses

200Successful Response
categoryenumrequired

Template category.

administrativeendodonticexamgeneralimplantorthodonticpediatricperiodonticpreventiveprosthodonticrestorativesurgery
compiled_schema_versioninteger
completion_rulesobject
content_formatenumrequired

Content format. One of: plain_text, markdown.

markdownplain_text
created_atstring (date-time)required

Timestamp when the template was created.

descriptionstring
fieldsobject[]

Structured field definitions for the template.

idstring (uuid)required

Unique identifier of the template.

is_activebooleanrequired

Whether the template is active and available for use.

is_systembooleanrequired

Whether this is a system-provided immutable template.

item_orderintegerrequired

Display order among templates.

namestringrequired

Display name of the template.

note_typeenumrequired

Type of note this template produces.

addendumconsultationexamgeneralhygienelabphone_callprocedurereferraltreatment_plan
published_atstring (date-time)
published_versioninteger
render_templatestring
specialtystring
statusenumrequired

Template status. One of: draft, published.

draftpublished
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version number for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/{template_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "category": "string",
    "completion_rules": null,
    "content_format": "string",
    "description": "string"
  }'
delete/api/v1/{org_id}/clinical-notes/auto-rules/{rule_uuid}

Archive auto-note rule

Archive an auto-note rule (soft delete). Raises 404 if the rule does not exist.

Parameters

Path Parameters
rule_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical-notes/auto-rules/{rule_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}

Delete clinical note

Soft-delete a clinical note. Only unsigned notes can be deleted. Signed notes must be amended instead. Raises 404 if the note does not exist. Raises 422 if the note is signed.

Parameters

Path Parameters
note_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/procedures/{procedure_uuid}

Unlink procedure from note

Remove a charted procedure link from a clinical note.

Parameters

Path Parameters
note_uuidstringrequired
procedure_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
itemsobject[]required

List of procedure links.

422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical-notes/clinical-notes/{note_uuid}/procedures/{procedure_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical-notes/favorites/{favorite_uuid}

Remove template favorite

Remove a template from the current user's favorites. Raises 404 if the favorite does not exist or does not belong to the current user.

Parameters

Path Parameters
favorite_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical-notes/favorites/{favorite_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}

Archive clinical option list

Parameters

Path Parameters
option_list_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical-notes/option-lists/{option_list_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical-notes/preset-blocks/{block_uuid}

Archive preset block

Archive a field preset block (soft delete). Raises 404 if the block does not exist.

Parameters

Path Parameters
block_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical-notes/preset-blocks/{block_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical-notes/smart-phrases/{phrase_uuid}

Archive smart phrase

Archive a smart phrase (soft delete). Raises 404 if not found.

Parameters

Path Parameters
phrase_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical-notes/smart-phrases/{phrase_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical-notes/templates/{template_uuid}

Archive note template

Archive a clinical note template (soft delete).

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical-notes/templates/{template_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Treatment Plans

14 endpoints

get/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans

List Treatment Plans

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
statusstring
pageinteger

Default: 1

page_sizeinteger

Default: 50

Responses

200Successful Response
itemsobject[]required
pageintegerrequired
page_sizeintegerrequired
totalintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}

Get Plan

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
alternate_group_idinteger
created_atstring (date-time)required
date_acceptedstring (date-time)
date_presentedstring (date-time)
date_rejectedstring (date-time)
deleted_atstring (date-time)
headingstringrequired
idstring (uuid)required
is_recommendedbooleanrequired
location_uuidstring (uuid)
notestringrequired
plan_typestringrequired
provider_uuidstring (uuid)
rejection_reasonstring
statusstringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/procedures

List Procedures

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
itemsobject[]required
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/procedures" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/snapshots

List Snapshots

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
itemsobject[]required
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/snapshots" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans

Create Plan

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

alternate_group_idinteger
headingstringrequired
is_recommendedboolean
location_uuidstring (uuid)required
notestring
plan_typestring
provider_uuidstring (uuid)
responsible_party_uuidstring (uuid)

Responses

201Successful Response
alternate_group_idinteger
created_atstring (date-time)required
date_acceptedstring (date-time)
date_presentedstring (date-time)
date_rejectedstring (date-time)
deleted_atstring (date-time)
headingstringrequired
idstring (uuid)required
is_recommendedbooleanrequired
location_uuidstring (uuid)
notestringrequired
plan_typestringrequired
provider_uuidstring (uuid)
rejection_reasonstring
statusstringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/treatment-plans" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "alternate_group_id": 1,
    "heading": "string",
    "is_recommended": false,
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "note": "string"
  }'
post/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/accept

Accept Plan

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired
plan_dataobjectrequired

Responses

200Successful Response
alternate_group_idinteger
created_atstring (date-time)required
date_acceptedstring (date-time)
date_presentedstring (date-time)
date_rejectedstring (date-time)
deleted_atstring (date-time)
headingstringrequired
idstring (uuid)required
is_recommendedbooleanrequired
location_uuidstring (uuid)
notestringrequired
plan_typestringrequired
provider_uuidstring (uuid)
rejection_reasonstring
statusstringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/accept" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "plan_data": {}
  }'
post/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/present

Present Plan

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Responses

200Successful Response
alternate_group_idinteger
created_atstring (date-time)required
date_acceptedstring (date-time)
date_presentedstring (date-time)
date_rejectedstring (date-time)
deleted_atstring (date-time)
headingstringrequired
idstring (uuid)required
is_recommendedbooleanrequired
location_uuidstring (uuid)
notestringrequired
plan_typestringrequired
provider_uuidstring (uuid)
rejection_reasonstring
statusstringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/present" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1
  }'
post/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/procedures

Add Procedure

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

charted_procedure_uuidstring (uuid)required
item_orderinteger
priority_uuidstring (uuid)
visit_numberinteger

Responses

201Successful Response
charted_procedure_uuidstring (uuid)
created_atstring (date-time)required
feestring
idstring (uuid)required
is_scheduledboolean

Whether the charted procedure is linked to an appointment.

item_orderintegerrequired
priority_uuidstring (uuid)
procedure_codestring
procedure_code_uuidstring (uuid)
procedure_descriptionstring
quadrantstring
scheduled_appointment_uuidstring (uuid)
surfacestring
tooth_numstring
visit_numberintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/procedures" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "charted_procedure_uuid": "00000000-0000-0000-0000-000000000000",
    "item_order": 0,
    "priority_uuid": "string",
    "visit_number": 1
  }'
post/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/reject

Reject Plan

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired
rejection_reasonstring

Responses

200Successful Response
alternate_group_idinteger
created_atstring (date-time)required
date_acceptedstring (date-time)
date_presentedstring (date-time)
date_rejectedstring (date-time)
deleted_atstring (date-time)
headingstringrequired
idstring (uuid)required
is_recommendedbooleanrequired
location_uuidstring (uuid)
notestringrequired
plan_typestringrequired
provider_uuidstring (uuid)
rejection_reasonstring
statusstringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/reject" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "rejection_reason": "string"
  }'
post/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/reorder

Reorder Procedures

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

procedure_orderobject[]required

Responses

200Successful Response
itemsobject[]required
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/reorder" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "procedure_order": []
  }'
post/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/snapshots

Create Snapshot

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

plan_dataobjectrequired

Responses

201Successful Response
created_atstring (date-time)required
headingstring
idstring (uuid)required
is_patient_signedbooleanrequired
is_practice_signedbooleanrequired
notestring
patient_signaturestring
patient_signed_atstring (date-time)
patient_signer_namestring
plan_dataobjectrequired
practice_signaturestring
practice_signed_atstring (date-time)
practice_signer_namestring
snapshot_datestring (date-time)required
snapshot_typestringrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}/snapshots" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_data": {}
  }'
patch/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}

Update Plan

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired
headingstring
is_recommendedboolean
location_uuidstring (uuid)
notestring
provider_uuidstring (uuid)

Responses

200Successful Response
alternate_group_idinteger
created_atstring (date-time)required
date_acceptedstring (date-time)
date_presentedstring (date-time)
date_rejectedstring (date-time)
deleted_atstring (date-time)
headingstringrequired
idstring (uuid)required
is_recommendedbooleanrequired
location_uuidstring (uuid)
notestringrequired
plan_typestringrequired
provider_uuidstring (uuid)
rejection_reasonstring
statusstringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "heading": "string",
    "is_recommended": null,
    "location_uuid": "string",
    "note": "string"
  }'
delete/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}

Delete Plan

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/{plan_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical/treatment-plans/procedures/{link_uuid}

Remove Procedure

Parameters

Path Parameters
link_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/treatment-plans/procedures/{link_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Perio

8 endpoints

get/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}

Get perio voice session

Parameters

Path Parameters
voice_session_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
audio_chunk_countintegerrequired
audio_formatstringrequired
cancelled_atstring (date-time)
completed_atstring (date-time)
created_atstring (date-time)required
exam_refstring (uuid)required
failed_atstring (date-time)
failure_codestring
failure_messagestring
final_transcript_countintegerrequired
final_transcript_hmac_sha256string
host_practice_refstringrequired
idstring (uuid)required
interim_transcript_countintegerrequired
last_event_atstring (date-time)
localestringrequired
location_refstring
patient_refstringrequired
provider_refstring
provider_session_refstring
raw_audio_retainedbooleanrequired
raw_transcript_retainedbooleanrequired
retention_policystringrequired
safe_metadataobject
sample_rate_hzinteger
started_atstring (date-time)
started_by_refstring
statusenumrequired
cancelledcompletedcreatedfailedlistening
stt_providerstringrequired
transcript_char_countintegerrequired
transcript_fingerprint_policystringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/support-replay

Get safe Perio voice support replay

Return support-safe BFF and Perio-MS voice replay summaries.

Parameters

Path Parameters
voice_session_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/support-replay" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/voice-sessions

Create perio voice session

Create a voice session through Perio-MS without exposing service identity.

Parameters

Path Parameters
exam_uuidstringrequired
org_idstringrequired

Request Body

audio_formatstring
client_session_refstring
localestring
provider_session_refstring
safe_metadataobject
sample_rate_hzinteger
stt_providerstringrequired

Responses

201Successful Response
audio_chunk_countintegerrequired
audio_formatstringrequired
cancelled_atstring (date-time)
completed_atstring (date-time)
created_atstring (date-time)required
exam_refstring (uuid)required
failed_atstring (date-time)
failure_codestring
failure_messagestring
final_transcript_countintegerrequired
final_transcript_hmac_sha256string
host_practice_refstringrequired
idstring (uuid)required
interim_transcript_countintegerrequired
last_event_atstring (date-time)
localestringrequired
location_refstring
patient_refstringrequired
provider_refstring
provider_session_refstring
raw_audio_retainedbooleanrequired
raw_transcript_retainedbooleanrequired
retention_policystringrequired
safe_metadataobject
sample_rate_hzinteger
started_atstring (date-time)
started_by_refstring
statusenumrequired
cancelledcompletedcreatedfailedlistening
stt_providerstringrequired
transcript_char_countintegerrequired
transcript_fingerprint_policystringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/voice-sessions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_format": "webm-opus",
    "client_session_ref": "string",
    "locale": "en-US",
    "provider_session_ref": "string",
    "safe_metadata": {},
    "stt_provider": "string"
  }'
post/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/cancel

Cancel perio voice session

Parameters

Path Parameters
voice_session_uuidstringrequired
org_idstringrequired

Request Body

audio_chunk_countinteger
final_transcript_countinteger
final_transcript_hmac_sha256string
interim_transcript_countinteger
provider_session_refstring
safe_metadataobject
transcript_char_countinteger

Responses

200Successful Response
audio_chunk_countintegerrequired
audio_formatstringrequired
cancelled_atstring (date-time)
completed_atstring (date-time)
created_atstring (date-time)required
exam_refstring (uuid)required
failed_atstring (date-time)
failure_codestring
failure_messagestring
final_transcript_countintegerrequired
final_transcript_hmac_sha256string
host_practice_refstringrequired
idstring (uuid)required
interim_transcript_countintegerrequired
last_event_atstring (date-time)
localestringrequired
location_refstring
patient_refstringrequired
provider_refstring
provider_session_refstring
raw_audio_retainedbooleanrequired
raw_transcript_retainedbooleanrequired
retention_policystringrequired
safe_metadataobject
sample_rate_hzinteger
started_atstring (date-time)
started_by_refstring
statusenumrequired
cancelledcompletedcreatedfailedlistening
stt_providerstringrequired
transcript_char_countintegerrequired
transcript_fingerprint_policystringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/cancel" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_chunk_count": 1,
    "final_transcript_count": 1,
    "final_transcript_hmac_sha256": "string",
    "interim_transcript_count": 1,
    "provider_session_ref": "string"
  }'
post/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/direct-credential

Create perio voice direct credential

Mint a short-lived provider credential through Perio-MS without exposing root keys.

Parameters

Path Parameters
voice_session_uuidstringrequired
org_idstringrequired

Request Body

provider_profile_refstring
requested_ttl_secondsinteger

Responses

201Successful Response
accessTokenstringrequired
allowedTransportModestringrequired
authTransportstringrequired
credentialRefstringrequired
expiresAtstringrequired
providerstringrequired
providerProfileRefstringrequired
queryobjectrequired
sessionRefstringrequired
transcriptFingerprintPolicystringrequired
websocketUrlstringrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/direct-credential" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_profile_ref": "string",
    "requested_ttl_seconds": 1
  }'
post/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/finish

Finish perio voice session

Parameters

Path Parameters
voice_session_uuidstringrequired
org_idstringrequired

Request Body

audio_chunk_countinteger
final_transcript_countinteger
final_transcript_hmac_sha256string
interim_transcript_countinteger
provider_session_refstring
safe_metadataobject
transcript_char_countinteger

Responses

200Successful Response
audio_chunk_countintegerrequired
audio_formatstringrequired
cancelled_atstring (date-time)
completed_atstring (date-time)
created_atstring (date-time)required
exam_refstring (uuid)required
failed_atstring (date-time)
failure_codestring
failure_messagestring
final_transcript_countintegerrequired
final_transcript_hmac_sha256string
host_practice_refstringrequired
idstring (uuid)required
interim_transcript_countintegerrequired
last_event_atstring (date-time)
localestringrequired
location_refstring
patient_refstringrequired
provider_refstring
provider_session_refstring
raw_audio_retainedbooleanrequired
raw_transcript_retainedbooleanrequired
retention_policystringrequired
safe_metadataobject
sample_rate_hzinteger
started_atstring (date-time)
started_by_refstring
statusenumrequired
cancelledcompletedcreatedfailedlistening
stt_providerstringrequired
transcript_char_countintegerrequired
transcript_fingerprint_policystringrequired
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/finish" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_chunk_count": 0,
    "final_transcript_count": 0,
    "final_transcript_hmac_sha256": "string",
    "interim_transcript_count": 0,
    "provider_session_ref": "string"
  }'
post/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/runtime-telemetry

Forward Perio voice browser/runtime telemetry

Forward browser/runtime voice telemetry to Perio-MS.

Parameters

Path Parameters
voice_session_uuidstringrequired
org_idstringrequired

Request Body

eventsobject[]required

Responses

202Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/runtime-telemetry" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": []
  }'
post/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/stream-ticket

Create perio voice stream ticket

Mint a short-lived browser-safe ticket for the Perio voice WebSocket.

Parameters

Path Parameters
voice_session_uuidstringrequired
org_idstringrequired

Responses

201Successful Response
expires_atstring (date-time)required
ticketstringrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/perio-voice-sessions/{voice_session_uuid}/stream-ticket" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Exams

13 endpoints

get/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-boot

Get perio chart boot data

Single-request initialization for the perio charting UI.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
provider_uuidstring

Optional provider UUID for settings resolution

location_uuidstring

Optional location UUID for settings resolution

Responses

200Successful Response
implant_teethstring[]

Tooth numbers identified as implants. Currently always returns an empty list — implant tracking via tooth status is not yet implemented. Reserved for future use when an 'implant' tooth status value is added.

missing_teethstring[]required

Tooth numbers recorded as missing.

present_teethstring[]required

Tooth numbers currently present in the patient's mouth (universal numbering '1'-'32' / 'A'-'T').

recent_examsobject[]required

Up to the last 5 exams for this patient, ordered by exam_date descending, with measurement counts.

resolved_settingsobjectrequired

Fully merged perio settings from the hierarchy (system defaults -> practice -> location -> provider), including '_sources' metadata indicating the origin level of each value.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-boot" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-comparison

Compare two perio exams

Compare two perio exams side by side.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
exam_uuid_1stringrequired

First exam (typically earlier)

exam_uuid_2stringrequired

Second exam (typically later)

Responses

200Successful Response
comparisonobject

Per-tooth comparison keyed by tooth number. Each value is a dict of site surfaces (e.g. 'DB') or per-tooth fields (e.g. 'furcation'), each containing: {'delta': int, 'direction': 'improved'|'worsened'|'unchanged', 'significant': bool}. 'significant' is True when abs(delta) >= 2.

exam_1objectrequired

First (earlier) exam in the comparison.

exam_2objectrequired

Second (later) exam in the comparison.

summary_comparisonobject

Aggregate delta between exam_1 and exam_2 summaries: 'average_probing_depth_delta', 'bleeding_pct_delta', etc. Each value is a signed float.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-comparison" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-exams

List perio exams

List all perio exams for a patient ordered by date descending.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
exam_typestring

Filter by exam type: full, psr, or plaque_bleeding

pageinteger

Page number (1-based)

Default: 1

page_sizeinteger

Number of records per page (1-200)

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of exam records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Maximum items per page.

totalintegerrequired

Total number of matching exams.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-exams" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-trends

Get perio trends

Longitudinal trend data across all exams for a patient.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
exam_typestring

Filter by exam type: full, psr, or plaque_bleeding

limitinteger

Maximum number of exams to return.

Default: 20

Responses

200Successful Response
examsobject[]required

Exam snapshots in chronological order (oldest first), each containing summary statistics and per-tooth data.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-trends" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}

Get perio exam detail

Retrieve a perio exam with nested measurements and summary statistics.

Parameters

Path Parameters
exam_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

created_atstring (date-time)required

Timestamp when the exam was created.

exam_datestring (date)required

Date the exam was performed.

exam_typeenumrequired

Exam scope: 'full' (comprehensive), 'psr' (screening), or 'plaque_bleeding' (O'Leary plaque/bleeding index).

fullplaque_bleedingpsr
idstring (uuid)required

Unique identifier of the exam.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

measurementsobjectrequired

Nested measurement data keyed by tooth number, then by site code (e.g., 'F0', 'L3'), with measurement values per sequence type.

notestringrequired

Free-text clinical note.

providerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

statusenumrequired

Lifecycle status of the exam.

completedin_progressreviewed
summaryobjectrequired

Computed clinical statistics: average probing depth, percentage of sites with bleeding on probing, max probing depth, attachment loss distribution, and other aggregate metrics.

updated_atstring (date-time)required

Timestamp of the last modification.

versionintegerrequired

Optimistic-concurrency version for conflict detection.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/patient-report

Get latest perio patient report

Return the latest patient report status for the exam, or null when none exists.

Parameters

Path Parameters
exam_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
exam_refstring (uuid)required

Exam this report belongs to.

failure_codestring
host_document_refstring
idstring (uuid)required

Report public id.

statusstringrequired

One of: pending, generated, delivering, delivered, failed, skipped_no_data, skipped_disabled.

triggerstringrequired

One of: auto, manual.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/patient-report" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-exams

Create perio exam

Create a new periodontal examination for a patient.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

appointment_uuidstring (uuid)
exam_datestring (date)
exam_typeenum
fullplaque_bleedingpsr
location_uuidstring (uuid)
notestring
provider_uuidstring (uuid)required

UUID of the provider performing the exam.

Responses

201Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

created_atstring (date-time)required

Timestamp when the exam was created.

exam_datestring (date)required

Date the exam was performed.

exam_typeenumrequired

Exam scope: 'full' (comprehensive), 'psr' (screening), or 'plaque_bleeding' (O'Leary plaque/bleeding index).

fullplaque_bleedingpsr
idstring (uuid)required

Unique identifier of the exam.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

notestringrequired

Free-text clinical note.

providerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

statusenumrequired

Lifecycle status of the exam.

completedin_progressreviewed
updated_atstring (date-time)required

Timestamp of the last modification.

versionintegerrequired

Optimistic-concurrency version; include in updates to detect conflicts.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/patients/{patient_uuid}/perio-exams" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_uuid": "string",
    "exam_date": "string",
    "exam_type": "string",
    "location_uuid": "string",
    "note": "string",
    "provider_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/convert-to-full

Convert PSR to full exam

Create a new full periodontal exam from a completed PSR screening.

Parameters

Path Parameters
exam_uuidstringrequired
org_idstringrequired

Responses

201Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

created_atstring (date-time)required

Timestamp when the exam was created.

exam_datestring (date)required

Date the exam was performed.

exam_typeenumrequired

Exam scope: 'full' (comprehensive), 'psr' (screening), or 'plaque_bleeding' (O'Leary plaque/bleeding index).

fullplaque_bleedingpsr
idstring (uuid)required

Unique identifier of the exam.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

notestringrequired

Free-text clinical note.

providerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

statusenumrequired

Lifecycle status of the exam.

completedin_progressreviewed
updated_atstring (date-time)required

Timestamp of the last modification.

versionintegerrequired

Optimistic-concurrency version; include in updates to detect conflicts.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/convert-to-full" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/measurements

Save measurements

Batch upsert measurements for a perio exam.

Parameters

Path Parameters
exam_uuidstringrequired
org_idstringrequired

Request Body

measurementsobject[]required

List of individual measurement records to upsert. Existing measurements for the same tooth/surface/site/sequence are overwritten.

provenanceobject

Safe source metadata for measurement saves. This intentionally excludes transcripts, audio, provider raw events, and measurement payload details.

Responses

201Successful Response
measurementsobjectrequired

Nested dict of saved measurements keyed by tooth number, then by site code, containing the persisted measurement values.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/measurements" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": [],
    "provenance": null
  }'
post/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/patient-report

Generate perio patient report

Manually generate the patient-facing report. Raises 409 if one is already generating, 422 if patient reports are disabled or the exam is not completed.

Parameters

Path Parameters
exam_uuidstringrequired
org_idstringrequired

Responses

201Successful Response
exam_refstring (uuid)required

Exam this report belongs to.

failure_codestring
host_document_refstring
idstring (uuid)required

Report public id.

statusstringrequired

One of: pending, generated, delivering, delivered, failed, skipped_no_data, skipped_disabled.

triggerstringrequired

One of: auto, manual.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/patient-report" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
patch/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/complete

Complete perio exam

Transition exam status from in_progress to completed.

Parameters

Path Parameters
exam_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

created_atstring (date-time)required

Timestamp when the exam was created.

exam_datestring (date)required

Date the exam was performed.

exam_typeenumrequired

Exam scope: 'full' (comprehensive), 'psr' (screening), or 'plaque_bleeding' (O'Leary plaque/bleeding index).

fullplaque_bleedingpsr
idstring (uuid)required

Unique identifier of the exam.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

notestringrequired

Free-text clinical note.

providerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

statusenumrequired

Lifecycle status of the exam.

completedin_progressreviewed
updated_atstring (date-time)required

Timestamp of the last modification.

versionintegerrequired

Optimistic-concurrency version; include in updates to detect conflicts.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/complete" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
patch/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/review

Review perio exam

Transition exam status from completed to reviewed.

Parameters

Path Parameters
exam_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

created_atstring (date-time)required

Timestamp when the exam was created.

exam_datestring (date)required

Date the exam was performed.

exam_typeenumrequired

Exam scope: 'full' (comprehensive), 'psr' (screening), or 'plaque_bleeding' (O'Leary plaque/bleeding index).

fullplaque_bleedingpsr
idstring (uuid)required

Unique identifier of the exam.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

notestringrequired

Free-text clinical note.

providerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

statusenumrequired

Lifecycle status of the exam.

completedin_progressreviewed
updated_atstring (date-time)required

Timestamp of the last modification.

versionintegerrequired

Optimistic-concurrency version; include in updates to detect conflicts.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}/review" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}

Delete perio exam

Soft-delete a periodontal exam.

Parameters

Path Parameters
exam_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
appointmentobject

Lightweight reference to a related entity — exposes UUID and optional name.

created_atstring (date-time)required

Timestamp when the exam was created.

exam_datestring (date)required

Date the exam was performed.

exam_typeenumrequired

Exam scope: 'full' (comprehensive), 'psr' (screening), or 'plaque_bleeding' (O'Leary plaque/bleeding index).

fullplaque_bleedingpsr
idstring (uuid)required

Unique identifier of the exam.

locationobject

Lightweight reference to a related entity — exposes UUID and optional name.

notestringrequired

Free-text clinical note.

providerobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

statusenumrequired

Lifecycle status of the exam.

completedin_progressreviewed
updated_atstring (date-time)required

Timestamp of the last modification.

versionintegerrequired

Optimistic-concurrency version; include in updates to detect conflicts.

422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/perio-exams/{exam_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Settings

11 endpoints

get/api/v1/{org_id}/clinical/perio-settings/locations

List location overrides

List all location-level settings overrides.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
itemsobject[]required

Location settings override summaries.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/locations" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/perio-settings/locations/{location_uuid}

Get location settings

Get location-level settings override.

Parameters

Path Parameters
location_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
idstring (uuid)required

Unique identifier of the override record.

is_activebooleanrequired

Whether location-level overrides are currently enabled.

location_uuidstring (uuid)
override_payloadobjectrequired

JSON dict of setting keys overridden at this location.

versionintegerrequired

Optimistic-concurrency version for safe updates.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/locations/{location_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/perio-settings/practice

Get practice settings

Get practice-level perio settings.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
comparison_configobjectrequired

Exam comparison view settings.

default_exam_typestringrequired

Default exam type for new exams ('full', 'psr', or 'plaque_bleeding').

exam_configobjectrequired

Exam behavior configuration (sites per tooth, default sequences, etc.).

idstring (uuid)
patient_report_configobjectrequired

Patient report generation settings.

print_export_configobjectrequired

Print layout and PDF export settings.

psr_configobjectrequired

PSR screening-specific settings.

summary_configobjectrequired

Summary statistics computation and display settings.

threshold_configobjectrequired

Clinical threshold definitions for color-coding probing depths and other metrics.

traversal_configobjectrequired

Tooth traversal order and navigation settings.

validation_configobjectrequired

Measurement range validation rules per sequence type.

versionintegerrequired

Optimistic-concurrency version; supply as base_version in the next update.

visibility_configobjectrequired

Default column visibility for measurement sequence types.

voice_configobjectrequired

Voice charting dictation settings.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/practice" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/perio-settings/providers

List provider preferences

List all provider-level preference records.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
itemsobject[]required

Provider preference summaries.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/providers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/perio-settings/providers/{provider_uuid}

Get provider preferences

Get provider-level preferences.

Parameters

Path Parameters
provider_uuidstringrequired
org_idstringrequired
Query Parameters
location_uuidstring

Optional location UUID to scope preferences to a specific location

Responses

200Successful Response
auto_advancebooleanrequired

Whether the cursor auto-advances after measurement entry.

idstring (uuid)required

Unique identifier of the preferences record.

is_activebooleanrequired

Whether provider-level overrides are currently enabled.

location_uuidstring (uuid)
override_payloadobjectrequired

JSON dict of setting keys overridden by this provider.

versionintegerrequired

Optimistic-concurrency version for safe updates.

voice_charting_enabledbooleanrequired

Whether voice dictation input is enabled.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/providers/{provider_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/clinical/perio-settings/resolved

Get resolved settings

Get effective settings resolved from the hierarchy.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
provider_uuidstring

Optional provider UUID for hierarchy resolution

location_uuidstring

Optional location UUID for hierarchy resolution

Responses

200Successful Response
settingsobjectrequired

Fully merged settings dictionary. Each top-level key is a config section (e.g., 'threshold_config', 'visibility_config'). A special '_sources' key maps each setting to the hierarchy level it was resolved from ('system', 'practice', 'location', or 'provider').

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/resolved" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
put/api/v1/{org_id}/clinical/perio-settings/locations/{location_uuid}

Update location settings

Create or update location-level settings override.

Parameters

Path Parameters
location_uuidstringrequired
org_idstringrequired

Request Body

base_versioninteger
is_activeboolean
override_payloadobject

JSON dict of setting keys to override at this location. Keys correspond to practice-level config section names (e.g., 'threshold_config', 'visibility_config'). Only included keys override the practice default; omitted keys inherit.

Responses

200Successful Response
idstring (uuid)required

Unique identifier of the override record.

is_activebooleanrequired

Whether location-level overrides are currently enabled.

location_uuidstring (uuid)
override_payloadobjectrequired

JSON dict of setting keys overridden at this location.

versionintegerrequired

Optimistic-concurrency version for safe updates.

422Validation Error
detailobject[]
curl
curl -X PUT "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/locations/{location_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "is_active": null,
    "override_payload": {}
  }'
put/api/v1/{org_id}/clinical/perio-settings/practice

Update practice settings

Create or update practice-level perio settings.

Parameters

Path Parameters
org_idstringrequired

Request Body

base_versioninteger
comparison_configobject
default_exam_typeenum
fullplaque_bleedingpsr
exam_configobject
patient_report_configobject
print_export_configobject
psr_configobject
summary_configobject
threshold_configobject
traversal_configobject
validation_configobject
visibility_configobject
voice_configobject

Responses

200Successful Response
comparison_configobjectrequired

Exam comparison view settings.

default_exam_typestringrequired

Default exam type for new exams ('full', 'psr', or 'plaque_bleeding').

exam_configobjectrequired

Exam behavior configuration (sites per tooth, default sequences, etc.).

idstring (uuid)
patient_report_configobjectrequired

Patient report generation settings.

print_export_configobjectrequired

Print layout and PDF export settings.

psr_configobjectrequired

PSR screening-specific settings.

summary_configobjectrequired

Summary statistics computation and display settings.

threshold_configobjectrequired

Clinical threshold definitions for color-coding probing depths and other metrics.

traversal_configobjectrequired

Tooth traversal order and navigation settings.

validation_configobjectrequired

Measurement range validation rules per sequence type.

versionintegerrequired

Optimistic-concurrency version; supply as base_version in the next update.

visibility_configobjectrequired

Default column visibility for measurement sequence types.

voice_configobjectrequired

Voice charting dictation settings.

422Validation Error
detailobject[]
curl
curl -X PUT "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/practice" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "comparison_config": null,
    "default_exam_type": "string",
    "exam_config": null,
    "patient_report_config": null
  }'
put/api/v1/{org_id}/clinical/perio-settings/providers/{provider_uuid}

Update provider preferences

Create or update provider-level preferences.

Parameters

Path Parameters
provider_uuidstringrequired
org_idstringrequired

Request Body

auto_advanceboolean
base_versioninteger
is_activeboolean
location_uuidstring (uuid)
override_payloadobject

JSON dict of setting keys to override at the provider level. Keys correspond to practice/location config section names.

voice_charting_enabledboolean

Responses

200Successful Response
auto_advancebooleanrequired

Whether the cursor auto-advances after measurement entry.

idstring (uuid)required

Unique identifier of the preferences record.

is_activebooleanrequired

Whether provider-level overrides are currently enabled.

location_uuidstring (uuid)
override_payloadobjectrequired

JSON dict of setting keys overridden by this provider.

versionintegerrequired

Optimistic-concurrency version for safe updates.

voice_charting_enabledbooleanrequired

Whether voice dictation input is enabled.

422Validation Error
detailobject[]
curl
curl -X PUT "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/providers/{provider_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_advance": null,
    "base_version": 1,
    "is_active": null,
    "location_uuid": "string",
    "override_payload": {}
  }'
delete/api/v1/{org_id}/clinical/perio-settings/locations/{location_uuid}

Delete location settings

Delete location settings override.

Parameters

Path Parameters
location_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/locations/{location_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/clinical/perio-settings/providers/{provider_uuid}

Delete provider preferences

Delete provider preferences.

Parameters

Path Parameters
provider_uuidstringrequired
org_idstringrequired
Query Parameters
location_uuidstring

Optional location UUID to scope the deletion to a specific location

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/clinical/perio-settings/providers/{provider_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"