Dental PMS

Charting

40 endpoints

Tooth Status

6 endpoints

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-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"
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"
  }'
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"
  }'
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"

Procedures

12 endpoints

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/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}/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/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"
  }'
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/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"

Indicators

1 endpoint

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"

Conditions

5 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/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"
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"
  }'
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"
  }'
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"

Spans

7 endpoints

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"
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"
  }'
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"
  }'
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"

Estimation

7 endpoints

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}/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"
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
  }'
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
  }'
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"

Timeline

2 endpoints

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"