Dental PMS

Insurance

120 endpoints

Insurance

99 endpoints

get/api/v1/{org_id}/insurance/carriers

List carriers

List carriers with optional filters, search, and sorting. Staff callers receive the full ``CarrierListOut`` shape.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
searchstring

Text search on carrier name, electronic ID, or group name.

carrier_group_namestring

Filter by exact carrier group name.

include_hiddenboolean

Include hidden carriers.

Default: false

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

sort_bystring

Sort column. One of: carrier_name, electronic_id, carrier_group_name, trust_level, created_at.

sort_order"asc" | "desc"

Sort direction. One of: asc, desc.

ascdesc

Default: "asc"

Responses

200Successful Response
itemsobject[]required

List of carrier records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching carriers.

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

Get carrier

Retrieve a single carrier by UUID. Staff callers receive the full ``CarrierOut`` shape. Raises 404 if the carrier does not exist.

Parameters

Path Parameters
carrier_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
address_line1string
address_line2string
carrier_group_namestring
carrier_namestringrequired

Display name of the carrier.

citystring
cob_insurance_paid_behavior_overridestring
created_atstring (date-time)required

Timestamp when the carrier was created.

deleted_atstring (date-time)
electronic_filing_typeenum
do_not_send_electronicallydo_not_send_secondary_electronicallysend_electronically
electronic_idstring
era_automation_overrideenum
auto_receivedo_not_processmanual_review
idstring (uuid)required

Carrier UUID.

is_hiddenboolean

Whether the carrier is hidden from default list views.

notesstring
phonestring
statestring
trust_levelenumrequired

Trust level. One of: standard, trusted, untrusted.

standardtrusteduntrusted
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

zip_codestring
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/carriers/{carrier_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/carriers/stats

Carrier stats

Batch stats for all active carriers — plan counts and subscriber counts. Returns one entry per carrier. Designed for lazy-loading alongside the carrier list so the main table renders immediately.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
itemsobject[]required

One stats entry per carrier.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/carriers/stats" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/coverage-categories

List coverage categories

List coverage categories with optional search and filters. Set ``include_spans=true`` to include procedure code spans in each category.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

searchstring

Case-insensitive search on category name.

include_hiddenboolean

Include hidden categories.

Default: false

include_spansboolean

Eagerly load procedure code spans for each category.

Default: false

Responses

200Successful Response
itemsobject[]required

List of category records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching categories.

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

Get coverage category

Retrieve a single coverage category by UUID. Includes spans by default. Raises 404 if the category does not exist.

Parameters

Path Parameters
category_uuidstringrequired
org_idstringrequired
Query Parameters
include_spansboolean

Include procedure code spans in response.

Default: true

Responses

200Successful Response
category_namestringrequired

Display name of the category.

created_atstring (date-time)required

Timestamp when the category was created.

deleted_atstring (date-time)
descriptionstring
idstring (uuid)required

Category UUID.

is_hiddenboolean

Whether hidden from default list views.

is_systemboolean

Whether this is a system-seeded category protected from archiving.

item_orderinteger

Sort order among categories.

spansobject[]
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/spans

List coverage spans

List procedure code spans within a coverage category. Raises 404 if the category does not exist.

Parameters

Path Parameters
category_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 100

Responses

200Successful Response
itemsobject[]required

List of span records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching spans.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/spans" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/drafts

List drafts

List insurance drafts with optional patient and status filters.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

patient_uuidstring

Filter drafts by patient UUID.

review_statusstring

Filter by review status. One of: pending, matched, converted, rejected.

Responses

200Successful Response
itemsobject[]required

List of draft records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching drafts.

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

Get draft with candidates

Retrieve a single draft with its matching candidates. Returns the draft plus candidate carriers, plans, and patients for the review UI. Raises 404 if the draft does not exist.

Parameters

Path Parameters
draft_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
candidatesobjectrequired

Matching candidates for review.

draftobjectrequired

Full insurance draft output.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/drafts/{draft_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/estimate-books

List estimate books

List estimate books with optional filters and search.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

searchstring

Text search on estimate book name.

scope_typestring

Filter by scope type (e.g., tenant, carrier, plan).

statusstring

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

Responses

200Successful Response
itemsobject[]required

List of estimate book records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching estimate books.

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

Get estimate book

Retrieve a single estimate book by UUID. Raises 404 if the estimate book does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
allowed_fee_scheduleobject

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

carrierobject

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

claim_match_methodstring
created_atstring (date-time)required

Timestamp when the book was created.

deleted_atstring (date-time)
exclude_over_ucrboolean

Whether to cap allowed fees at the UCR amount.

idstring (uuid)required

Estimate book UUID.

insurance_planobject

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

namestringrequired

Display name.

rule_typestringrequired

Rule type. One of: manual_fee_schedule, allowed_from_claims, ucr_fallback.

scope_typestringrequired

Scope. One of: tenant, carrier, plan.

statusstringrequired

Status. One of: active, archived.

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/adjustment-logs

List adjustment logs

List fee adjustment log entries for an estimate book. Raises 404 if the estimate book does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of adjustment log entries.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching entries.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/adjustment-logs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/allowed-fees

List allowed fees

List computed allowed fee entries for an estimate book. Raises 404 if the estimate book does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of allowed fee entries.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching entries.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/allowed-fees" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/evidence

List evidence entries

List claim payment evidence entries for an estimate book. Raises 404 if the estimate book does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of evidence entries.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching entries.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/evidence" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/rule-steps

List rule steps

List rule steps for an estimate book. Set active_only=true to filter to active steps only. Raises 404 if the estimate book does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired
Query Parameters
active_onlyboolean

Only return active rule steps.

Default: false

Responses

200Successful Response
itemsobject[]required

List of rule steps, ordered by priority.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/rule-steps" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/runs

List estimate book runs

List recomputation runs for an estimate book. Raises 404 if the estimate book does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of run records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of runs.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/runs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/runs/{run_uuid}

Get estimate book run

Retrieve a single run by UUID. Raises 404 if the run does not exist.

Parameters

Path Parameters
book_uuidstringrequired
run_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the run record was created.

deleted_atstring (date-time)
errorstring
estimate_bookobjectrequired

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

finished_atstring (date-time)
idstring (uuid)required

Run UUID.

started_atstring (date-time)required

Timestamp when the run started.

statusstringrequired

Run status. One of: running, completed, failed.

summary_jsonobject
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/runs/{run_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedule-assignments

List assignments

List fee schedule assignments with optional filters. By default returns only active (open-ended) assignments. Use ``active_as_of`` to find assignments effective on a specific date. Use ``effective_start_after`` / ``effective_start_before`` for date-range filtering.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location UUID.

carrier_uuidstring

Filter by carrier UUID.

insurance_plan_uuidstring

Filter by insurance plan UUID.

assignment_kindstring

Filter by assignment kind.

fee_schedule_uuidstring

Filter by fee schedule UUID.

active_onlyboolean

Only return active (open-ended) assignments.

Default: true

active_as_ofstring

Return assignments active as of this date.

effective_start_afterstring

Filter: effective_start >= this date.

effective_start_beforestring

Filter: effective_start <= this date.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

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}/insurance/fee-schedule-assignments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedule-assignments/{assignment_uuid}

Get assignment

Get a single fee schedule assignment by UUID. Raises 404 if the assignment does not exist.

Parameters

Path Parameters
assignment_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
assignment_kindstringrequired

Kind of assignment. One of: ucr, primary, copay, out_of_network, allowed, manual_blue_book.

carrierobject

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

created_atstring (date-time)required
effective_endstring (date)
effective_startstring (date)required

Start date of this assignment.

estimate_bookobject

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

fee_scheduleobjectrequired

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

idstring (uuid)required

Assignment UUID.

insurance_planobject

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

locationobjectrequired

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

notesstring
updated_atstring (date-time)required
versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments/{assignment_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedule-assignments/activity

Assignment activity log

Return audit log entries for fee schedule assignment changes. Shows create, update, and archive actions on assignments, ordered newest-first.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
limitinteger

Max entries to return.

Default: 20

offsetinteger

Offset for pagination.

Default: 0

Responses

200Successful Response
itemsobject[]required
totalintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments/activity" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedule-assignments/compare

Compare plan across locations

Compare a single plan's assignments across all locations for a given kind. Shows which fee schedule is assigned at each location.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
plan_uuidstringrequired

Insurance plan UUID to compare.

kindstringrequired

Assignment kind to compare (e.g., 'primary').

Responses

200Successful Response
kindstringrequired

Assignment kind.

locationsobject[]required

Per-location comparison.

planobjectrequired

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

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments/compare" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedule-assignments/matrix

Assignment matrix

Build a cross-tab matrix of plans x locations for a given assignment kind. Returns column headers (locations) and rows (plans), with each cell containing the assigned fee schedule or null.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
kindstringrequired

Assignment kind to display (e.g., 'primary', 'ucr').

carrier_uuidstring

Filter by carrier.

Responses

200Successful Response
kindstringrequired

Assignment kind being displayed.

locationsobject[]required

Column headers.

rowsobject[]required

One row per plan (or UCR).

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments/matrix" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedule-assignments/resolve

Resolve assignment for slot

Resolve the best-matching fee schedule assignment for a given slot. Uses the standard resolution precedence: plan-specific > carrier-level > UCR fallback. Returns the resolved assignment and the level at which it was found.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstringrequired

Location UUID to resolve for.

kindstringrequired

Assignment kind to resolve (e.g., ucr, primary).

as_of_datestringrequired

Date of service for which to resolve the assignment.

carrier_uuidstring

Optional carrier UUID for carrier-level resolution.

insurance_plan_uuidstring

Optional plan UUID for plan-level resolution.

Responses

200Successful Response
assignmentobject

Full fee schedule assignment output.

resolution_levelstring
resolvedbooleanrequired

Whether an assignment was found for the given parameters.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments/resolve" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedule-assignments/upcoming

List upcoming changes

List future-dated assignments (effective_start > today). These represent upcoming changes that will take effect in the future.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required
totalintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments/upcoming" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedule-assignments/validate

Validate assignments

Run assignment health checks and return a validation report. Checks include: missing UCR, missing primary, archived schedule references, date overlaps, purpose/kind mismatches, and invalid estimate book references. Optionally filter to a single location.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter validation to a specific location.

Responses

200Successful Response
issuesobject[]required

List of validation issues.

statsobjectrequired

Summary statistics.

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

List assignments at location

List all fee schedule assignments at a specific location. Raises 404 if the location does not exist.

Parameters

Path Parameters
location_uuidstringrequired
org_idstringrequired
Query Parameters
assignment_kindstring

Filter by assignment kind.

active_onlyboolean

Only return active (open-ended) assignments.

Default: true

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

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}/insurance/locations/{location_uuid}/fee-schedule-assignments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/patient-plans/{patient_plan_uuid}/benefits

List patient benefit overrides

List patient-level benefit overrides for a patient plan. Returns only benefits directly attached to the patient plan (not plan-level defaults). Use the effective-benefits endpoint to see the merged view. Raises 404 if the patient plan does not exist.

Parameters

Path Parameters
patient_plan_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

benefit_typestring

Filter by benefit type.

Responses

200Successful Response
itemsobject[]required

List of benefit records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching benefits.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/patient-plans/{patient_plan_uuid}/benefits" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/patient-plans/{patient_plan_uuid}/effective-benefits

Get effective benefits for patient plan

Return the merged effective benefits for a patient plan. Merges plan-level benefits with patient-level overrides. Patient overrides take precedence per (coverage_category, benefit_type) key. Raises 404 if the patient plan does not exist.

Parameters

Path Parameters
patient_plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
itemsobject[]required

List of benefit records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching benefits.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/patient-plans/{patient_plan_uuid}/effective-benefits" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/patient-plans/{patient_plan_uuid}/verifications

List verifications for patient plan

List verification history for a specific patient plan. Returns verifications ordered by verified_at descending. Raises 404 if the patient plan does not exist.

Parameters

Path Parameters
patient_plan_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

verification_typestring

Filter by verification type.

Responses

200Successful Response
itemsobject[]required

List of verification records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching verifications.

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

List patient insurance plans

List all insurance plan assignments for a specific patient. Staff callers receive the full ``PatientPlanListOut`` shape (with COB overrides, fee-schedule refs, etc.). Raises 404 if the patient does not exist.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired
Query Parameters
include_deletedboolean

Include archived (soft-deleted) patient plans.

Default: false

Responses

200Successful Response
itemsobject[]required

List of patient plan records.

totalintegerrequired

Total number of patient plans returned.

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

Get patient plan

Retrieve a single patient plan by UUID. Staff callers receive the full ``PatientPlanOut`` shape. Raises 404 if the patient or patient plan does not exist.

Parameters

Path Parameters
patient_uuidstringrequired
patient_plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
benefits_last_verified_atstring (date-time)
benefits_summaryobject

Plan-level benefit totals. Usage values are zeros until claims tracking is implemented — only the *_total fields carry real data from ``InsuranceBenefit`` rows.

cob_order_overrideinteger
coverage_typeenumrequired

Coverage type. One of: dental, medical, vision.

dentalmedicalvision
created_atstring (date-time)required

Timestamp when the patient plan was created.

deleted_atstring (date-time)
eligibility_last_verified_atstring (date-time)
fee_scheduleobject

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

idstring (uuid)required

Patient plan UUID.

is_pendingboolean

Whether this plan assignment is pending verification.

ordinalintegerrequired

Priority ordinal (1=primary, 2=secondary, 3=tertiary).

pat_id_overridestring
patientobjectrequired

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

relationship_to_subscriberenumrequired

Relationship to subscriber. One of: self, spouse, child, other.

childotherselfspouse
statusenum

Plan status. One of: active, inactive, pending_verification.

activeinactivepending_verification
subscriptionobject

Brief subscription info nested inside PatientPlanOut. ``subscriber`` is non-nullable — ``subscriber_id`` is NOT NULL in the DB and the relationship must be eager-loaded. If the eager-load is missing, Pydantic validation will fail (desired fail-fast behavior).

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

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

List insurance plans

List insurance plans with optional filters, search, and sorting. Use ``carrier_uuid`` to show only plans belonging to a specific carrier.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
carrier_uuidstring

Filter plans by carrier UUID.

plan_typestring

Filter by plan type.

searchstring

Text search on plan name/group.

include_hiddenboolean

Include hidden plans.

Default: false

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

sort_bystring

Sort column. One of: group_name, group_number, plan_type, created_at.

sort_order"asc" | "desc"

Sort direction. One of: asc, desc.

ascdesc

Default: "asc"

Responses

200Successful Response
itemsobject[]required

List of plan records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching plans.

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

Get insurance plan

Retrieve a single insurance plan by UUID. Raises 404 if the plan does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired
Query Parameters
include_benefitsboolean

Eagerly load benefit rows for this plan.

Default: false

Responses

200Successful Response
assignment_of_benefitsboolean

Whether assignment of benefits is accepted.

benefit_year_start_monthinteger

Month (1-12) the benefit year starts.

carrierobject

Brief carrier reference embedded in plan output.

claim_form_typeenumrequired

Claim form type. One of: ada_2019, cms_1500.

ada_2019cms_1500
claims_use_ucrboolean

Whether claims use UCR fees.

cob_ruleenum
basiccarve_outsecondary_medicaidstandard
created_atstring (date-time)required

Timestamp when the plan was created.

deleted_atstring (date-time)
eclaim_send_behaviorenumrequired

E-claim send behavior. One of: send, do_not_send, secondary_only.

do_not_sendsecondary_onlysend
filing_codestring
filing_code_subtypestring
group_namestring
group_numberstring
idstring (uuid)required

Plan UUID.

is_hiddenboolean

Whether hidden from default list views.

is_medicalboolean

Whether this is a medical plan.

is_verification_exemptboolean

Whether verification-exempt.

ortho_auto_claim_days_waitinteger

Days to wait between ortho auto-claims.

ortho_auto_claim_typeenumrequired

Ortho auto-claim type. One of: none, initial_only, initial_plus_visit, initial_plus_periodic.

initial_onlyinitial_plus_periodicinitial_plus_visitnone
ortho_auto_fee_amtstring
ortho_auto_proc_codestring
plan_notestring
plan_typeenumrequired

Plan type. One of: category_percentage, ppo_percentage, ppo_fixed_benefit, medicaid_flat_copay, capitation.

capitationcategory_percentagemedicaid_flat_copayppo_fixed_benefitppo_percentage
release_of_informationboolean

Whether release of information is authorized.

show_base_unitsboolean

Whether to show base units on claims.

substitution_code_behaviorenumrequired

Substitution code behavior. One of: none, downgrade_to_amalgam, custom.

customdowngrade_to_amalgamnone
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

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

List plan benefits

List benefits for an insurance plan with optional type filter. Raises 404 if the plan does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

benefit_typestring

Filter by benefit type (e.g., coinsurance, deductible, annual_max).

Responses

200Successful Response
itemsobject[]required

List of benefit records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching benefits.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits/{benefit_uuid}

Get benefit

Retrieve a single benefit by UUID. Raises 404 if the plan or benefit does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
benefit_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
age_maxinteger
age_mininteger
benefit_typestringrequired

Benefit type. One of: coinsurance, deductible, annual_max, ortho_lifetime_max, exclusion, limitation, waiting_period, copayment, family_deductible, family_annual_max.

coverage_categoryobject

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

created_atstring (date-time)required

Timestamp when the benefit was created.

deleted_atstring (date-time)
idstring (uuid)required

Benefit UUID.

insurance_planobject

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

is_deductible_exemptboolean

Whether exempt from the deductible.

monetary_amtstring
patient_planobject

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

percentinteger
procedure_codeobject

Brief procedure code info embedded in fee entries.

quantityinteger
quantity_qualifierstring
substitution_codeobject

Brief procedure code info embedded in fee entries.

time_periodstring
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version for optimistic concurrency.

waiting_period_monthsinteger
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits/{benefit_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/plans/{plan_uuid}/fee-schedule-assignments

List assignments for plan

List all fee schedule assignments for a specific insurance plan. Raises 404 if the plan does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired
Query Parameters
assignment_kindstring

Filter by assignment kind.

active_onlyboolean

Only return active (open-ended) assignments.

Default: true

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

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}/insurance/plans/{plan_uuid}/fee-schedule-assignments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/plans/{plan_uuid}/subscriber-count

Get subscriber count

Return the active subscriber and patient plan counts for a specific plan. Raises 404 if the plan does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
active_patient_plan_countintegerrequired

Number of active patient plans linked to this plan's subscriptions.

plan_uuidstring (uuid)required

UUID of the plan.

subscriber_countintegerrequired

Number of active subscribers (subscriptions) on this plan.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}/subscriber-count" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/plans/stats

Plan stats

Batch stats for all active plans — subscriber counts and fee schedule counts. Returns one entry per plan. Designed for lazy-loading alongside the plan list so the main table renders immediately.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
itemsobject[]required

One stats entry per plan.

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

Get insurance settings

Retrieve the organization's insurance settings. Creates default settings if none exist yet.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
allow_fee_exceed_ucrbooleanrequired

Whether insurance fees may exceed UCR.

allow_verification_without_appointmentbooleanrequired

Allow verification without appointment.

auto_calculate_estimatesbooleanrequired

Auto-calculate estimates.

auto_flag_unverifiedbooleanrequired

Auto-flag unverified insurance.

base_versionintegerrequired

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

benefits_verify_daysintegerrequired

Days between benefits re-verifications.

color_code_proceduresbooleanrequired

Color-code procedures by category.

created_atstring (date-time)required

Timestamp when settings were created.

days_before_appointment_flagintegerrequired

Days before appointment to flag.

default_benefit_year_typestringrequired

Benefit year type. One of: calendar, fiscal.

default_cob_rulestringrequired

Default COB rule. One of: basic, standard, carve_out, secondary_medicaid.

default_fiscal_year_startintegerrequired

Fiscal year start month (1-12).

default_insurance_tabstringrequired

Default tab. One of: benefits, claims, coverage.

eligibility_verify_daysintegerrequired

Days between eligibility re-verifications.

estimate_display_modestringrequired

How estimates are displayed.

idstring (uuid)required

Settings UUID.

include_write_offbooleanrequired

Include write-offs in estimates.

show_alerts_on_check_inbooleanrequired

Show alerts during check-in.

show_on_bannerbooleanrequired

Show insurance in patient banner.

show_on_treatment_plansbooleanrequired

Show estimates on treatment plans.

show_remaining_benefitsbooleanrequired

Show remaining benefits in banner.

updated_atstring (date-time)required

Timestamp of the last update.

write_off_methodstringrequired

Write-off method. One of: lesser_of_ucr_fee, fee_only, ucr_only.

writeoff_on_exclusionbooleanrequired

Auto write-off on exclusion.

writeoff_on_frequency_limitbooleanrequired

Auto write-off on frequency limit.

writeoff_on_max_reachedbooleanrequired

Auto write-off when annual max reached.

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

List subscriptions

List insurance subscriptions with optional filters. Filter by insurance_plan_uuid, subscriber_uuid, status, or search text.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

insurance_plan_uuidstring

Filter by insurance plan UUID.

subscriber_uuidstring

Filter by subscriber (patient) UUID.

statusstring

Filter by status. One of: active, inactive, terminated.

searchstring

Text search on subscriber ID number.

Responses

200Successful Response
itemsobject[]required

List of subscription records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching subscriptions.

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

Get subscription

Retrieve a single subscription by UUID. Raises 404 if the subscription does not exist.

Parameters

Path Parameters
subscription_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
benefit_notesstring
carrierobject

Brief carrier reference embedded in plan output.

created_atstring (date-time)required

Timestamp when the subscription was created.

date_effectivestring (date)
date_termstring (date)
deleted_atstring (date-time)
idstring (uuid)required

Subscription UUID.

insurance_planobject

Brief insurance plan reference embedded in subscription output.

last_verified_atstring (date-time)
last_verified_sourcestring
statusstringrequired

Subscription status. One of: active, terminated, pending_verification.

subscriberobjectrequired

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

subscriber_id_numberstringrequired

Subscriber ID number from the carrier.

subscriber_notestring
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

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

List verifications

List insurance verifications filtered by patient plan or insurance plan. At least one of patient_plan_uuid or insurance_plan_uuid must be provided. Returns empty list if neither is provided.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

patient_plan_uuidstring

Filter by patient plan UUID.

insurance_plan_uuidstring

Filter by insurance plan UUID.

verification_typestring

Filter by verification type. One of: eligibility, benefits.

Responses

200Successful Response
itemsobject[]required

List of verification records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching verifications.

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

Get verification

Retrieve a single verification by UUID. Raises 404 if the verification does not exist.

Parameters

Path Parameters
verification_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
assigned_to_user_uuidstring (uuid)
call_duration_minutesinteger
carrier_ref_numberstring
carrier_rep_namestring
created_atstring (date-time)required

Timestamp when the record was created.

deleted_atstring (date-time)
idstring (uuid)required

Verification UUID.

insurance_plan_uuidstring (uuid)
next_verification_duestring (date)
notesstring
patient_plan_uuidstring (uuid)
raw_response_jsonobject
updated_atstring (date-time)required

Timestamp of the last update.

verification_sourceenumrequired

Source. One of: manual, phone, electronic, fax.

electronicfaxmanualphone
verification_statusenumrequired

Status. One of: verified, failed, partial, unable_to_verify.

failedpartialunable_to_verifyverified
verification_typeenumrequired

Type. One of: eligibility, benefits.

benefitseligibility
verified_atstring (date-time)required

Timestamp when the verification was performed.

verified_by_user_uuidstring (uuid)
versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/verifications/{verification_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/carriers

Create carrier

Create a new insurance carrier. Raises 409 if a carrier with the same name already exists (idempotent).

Parameters

Path Parameters
org_idstringrequired

Request Body

address_line1string
address_line2string
carrier_group_namestring
carrier_namestringrequired

Display name for the carrier.

citystring
cob_insurance_paid_behavior_overridestring
electronic_filing_typeenum
do_not_send_electronicallydo_not_send_secondary_electronicallysend_electronically
electronic_idstring
era_automation_overrideenum
auto_receivedo_not_processmanual_review
is_hiddenboolean
notesstring
phonestring
statestring
trust_levelenum
standardtrusteduntrusted
zip_codestring

Responses

201Successful Response
address_line1string
address_line2string
carrier_group_namestring
carrier_namestringrequired

Display name of the carrier.

citystring
cob_insurance_paid_behavior_overridestring
created_atstring (date-time)required

Timestamp when the carrier was created.

deleted_atstring (date-time)
electronic_filing_typeenum
do_not_send_electronicallydo_not_send_secondary_electronicallysend_electronically
electronic_idstring
era_automation_overrideenum
auto_receivedo_not_processmanual_review
idstring (uuid)required

Carrier UUID.

is_hiddenboolean

Whether the carrier is hidden from default list views.

notesstring
phonestring
statestring
trust_levelenumrequired

Trust level. One of: standard, trusted, untrusted.

standardtrusteduntrusted
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

zip_codestring
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/carriers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address_line1": "string",
    "address_line2": "string",
    "carrier_group_name": "string",
    "carrier_name": "string",
    "city": "string"
  }'
post/api/v1/{org_id}/insurance/carriers/{carrier_uuid}/archive

Archive carrier

Soft-delete a carrier by setting deleted_at. The carrier remains in the database but is excluded from default list views. Raises 404 if the carrier does not exist.

Parameters

Path Parameters
carrier_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
address_line1string
address_line2string
carrier_group_namestring
carrier_namestringrequired

Display name of the carrier.

citystring
cob_insurance_paid_behavior_overridestring
created_atstring (date-time)required

Timestamp when the carrier was created.

deleted_atstring (date-time)
electronic_filing_typeenum
do_not_send_electronicallydo_not_send_secondary_electronicallysend_electronically
electronic_idstring
era_automation_overrideenum
auto_receivedo_not_processmanual_review
idstring (uuid)required

Carrier UUID.

is_hiddenboolean

Whether the carrier is hidden from default list views.

notesstring
phonestring
statestring
trust_levelenumrequired

Trust level. One of: standard, trusted, untrusted.

standardtrusteduntrusted
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

zip_codestring
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/carriers/{carrier_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/carriers/combine

Combine carriers

Merge multiple source carriers into a single target carrier. All plans from source carriers are moved to the target. Source carriers are archived after the merge. Raises 404 if any carrier UUID does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

source_uuidsstring (uuid)[]required

UUIDs of carriers whose plans will be moved to the target.

target_uuidstring (uuid)required

UUID of the carrier that will absorb plans from source carriers.

Responses

200Successful Response
carrierobjectrequired

Full insurance carrier output.

plans_movedintegerrequired

Number of plans moved from source carriers to the target.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/carriers/combine" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_uuids": [],
    "target_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/insurance/coverage-categories

Create coverage category

Create a new coverage category. Raises 409 on idempotency conflict.

Parameters

Path Parameters
org_idstringrequired

Request Body

category_namestringrequired

Display name for the category (e.g., 'Preventive').

descriptionstring
is_hiddenboolean
item_orderinteger

Responses

201Successful Response
category_namestringrequired

Display name of the category.

created_atstring (date-time)required

Timestamp when the category was created.

deleted_atstring (date-time)
descriptionstring
idstring (uuid)required

Category UUID.

is_hiddenboolean

Whether hidden from default list views.

is_systemboolean

Whether this is a system-seeded category protected from archiving.

item_orderinteger

Sort order among categories.

spansobject[]
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/coverage-categories" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_name": "string",
    "description": "string",
    "is_hidden": null,
    "item_order": 1
  }'
post/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/archive

Archive coverage category

Soft-delete a coverage category by setting deleted_at. Raises 404 if the category does not exist.

Parameters

Path Parameters
category_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
category_namestringrequired

Display name of the category.

created_atstring (date-time)required

Timestamp when the category was created.

deleted_atstring (date-time)
descriptionstring
idstring (uuid)required

Category UUID.

is_hiddenboolean

Whether hidden from default list views.

is_systemboolean

Whether this is a system-seeded category protected from archiving.

item_orderinteger

Sort order among categories.

spansobject[]
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/spans

Create coverage span

Create a procedure code span in a coverage category. Returns the new span plus any overlapping spans as warnings. Raises 404 if the category does not exist.

Parameters

Path Parameters
category_uuidstringrequired
org_idstringrequired

Request Body

from_codestringrequired

Start of the procedure code range (inclusive, e.g., 'D0100').

is_exclusionboolean
item_orderinteger
to_codestringrequired

End of the procedure code range (inclusive, e.g., 'D0999').

Responses

201Successful Response
overlapping_spansobject[]required

Spans with overlapping code ranges (for warning display).

spanobjectrequired

Full procedure code span output.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/spans" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_code": "string",
    "is_exclusion": null,
    "item_order": 1,
    "to_code": "string"
  }'
post/api/v1/{org_id}/insurance/coverage-categories/reorder

Reorder coverage categories

Batch-update the sort order of multiple coverage categories. All referenced categories must exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

itemsobject[]required

List of category UUIDs with their new sort orders.

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/coverage-categories/reorder" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": []
  }'
post/api/v1/{org_id}/insurance/drafts/{draft_uuid}/convert

Convert draft

Convert a matched draft into a subscription and patient plan. Creates real insurance records from the draft data. Raises 404 if the draft does not exist. Raises 422 if the draft is not in 'matched' status.

Parameters

Path Parameters
draft_uuidstringrequired
org_idstringrequired

Responses

201Successful Response
draftobjectrequired

The updated draft (status=converted).

patient_planobjectrequired

The created patient plan.

subscriptionobjectrequired

The created subscription.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/drafts/{draft_uuid}/convert" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/drafts/{draft_uuid}/reject

Reject draft

Reject a draft with a reason. Sets review_status to 'rejected'. Raises 404 if the draft does not exist.

Parameters

Path Parameters
draft_uuidstringrequired
org_idstringrequired

Request Body

reasonstringrequired

Reason for rejecting the draft.

Responses

200Successful Response
conversion_errorstring
converted_patient_planobject

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

converted_subscriptionobject

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

created_atstring (date-time)required

Timestamp when the draft was created.

idstring (uuid)required

Draft UUID.

matched_carrierobject

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

matched_planobject

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

patientobjectrequired

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

raw_data_jsonobjectrequired

Original raw import data.

review_statusstringrequired

Review status. One of: pending, matched, converted, rejected, error.

reviewed_atstring (date-time)
reviewed_by_user_uuidstring (uuid)
source_refstring
source_systemstring
subscriber_patientobject

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

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/drafts/{draft_uuid}/reject" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "string"
  }'
post/api/v1/{org_id}/insurance/drafts/{draft_uuid}/rematch

Re-run matching on a draft

Re-run auto-matching on an insurance draft. Clears existing carrier/plan matches and re-runs the auto-match algorithm. Only allowed on drafts that have not been converted. Raises 404 if the draft does not exist. Raises 409 if the draft has already been converted.

Parameters

Path Parameters
draft_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
conversion_errorstring
converted_patient_planobject

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

converted_subscriptionobject

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

created_atstring (date-time)required

Timestamp when the draft was created.

idstring (uuid)required

Draft UUID.

matched_carrierobject

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

matched_planobject

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

patientobjectrequired

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

raw_data_jsonobjectrequired

Original raw import data.

review_statusstringrequired

Review status. One of: pending, matched, converted, rejected, error.

reviewed_atstring (date-time)
reviewed_by_user_uuidstring (uuid)
source_refstring
source_systemstring
subscriber_patientobject

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

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/drafts/{draft_uuid}/rematch" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/drafts/import

Import drafts

Import raw insurance data as draft records for review. Each row becomes a separate draft. Auto-matching is attempted. Raises 404 if the patient does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

patient_uuidstring (uuid)required

UUID of the patient these drafts belong to.

rowsobject[]required

Raw insurance data rows to import.

source_systemstring

Responses

201Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/drafts/import" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_uuid": "00000000-0000-0000-0000-000000000000",
    "rows": [],
    "source_system": "string"
  }'
post/api/v1/{org_id}/insurance/estimate-books

Create estimate book

Create a new estimate book for allowed fee computation. Raises 409 on idempotency conflict.

Parameters

Path Parameters
org_idstringrequired

Request Body

allowed_fee_schedule_uuidstring (uuid)
carrier_uuidstring (uuid)
claim_match_methodstring
exclude_over_ucrboolean
insurance_plan_uuidstring (uuid)
namestringrequired

Display name for the estimate book.

rule_typestringrequired

Rule type for fee computation. One of: manual_fee_schedule, allowed_from_claims, ucr_fallback.

scope_typestring
statusstring

Responses

201Successful Response
allowed_fee_scheduleobject

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

carrierobject

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

claim_match_methodstring
created_atstring (date-time)required

Timestamp when the book was created.

deleted_atstring (date-time)
exclude_over_ucrboolean

Whether to cap allowed fees at the UCR amount.

idstring (uuid)required

Estimate book UUID.

insurance_planobject

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

namestringrequired

Display name.

rule_typestringrequired

Rule type. One of: manual_fee_schedule, allowed_from_claims, ucr_fallback.

scope_typestringrequired

Scope. One of: tenant, carrier, plan.

statusstringrequired

Status. One of: active, archived.

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/estimate-books" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_fee_schedule_uuid": "string",
    "carrier_uuid": "string",
    "claim_match_method": "string",
    "exclude_over_ucr": null,
    "insurance_plan_uuid": "string",
    "name": "string",
    "rule_type": "string"
  }'
post/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/adjustment-logs

Create adjustment log

Record a fee adjustment for an estimate book. Raises 404 if the estimate book, procedure code, or linked run does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired

Request Body

change_reasonstringrequired

Reason for the change. One of: rule_match, manual_override, recompute.

delta_allowed_feenumber
descriptionstringrequired

Human-readable description of the adjustment.

estimate_book_run_uuidstring (uuid)
insurance_claim_procedure_identifierinteger
insurance_procedure_estimate_idinteger
new_allowed_feenumberrequired

New allowed fee after adjustment.

previous_allowed_feenumber
procedure_code_uuidstring (uuid)required

UUID of the procedure code adjusted.

Responses

201Successful Response
change_reasonstringrequired

Reason. One of: rule_match, manual_override, recompute.

created_atstring (date-time)required

Timestamp when the log entry was created.

delta_allowed_feenumber
descriptionstringrequired

Description of the adjustment.

estimate_bookobjectrequired

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

estimate_book_runobject

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

idstring (uuid)required

Adjustment log UUID.

insurance_claim_procedure_identifierinteger
insurance_procedure_estimate_idinteger
new_allowed_feenumberrequired

New allowed fee.

previous_allowed_feenumber
procedure_codeobjectrequired

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

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/adjustment-logs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "change_reason": "string",
    "delta_allowed_fee": null,
    "description": "string",
    "estimate_book_run_uuid": "string",
    "insurance_claim_procedure_identifier": 1,
    "new_allowed_fee": 1,
    "procedure_code_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/allowed-fees

Create allowed fee

Create a computed allowed fee entry. Raises 404 if the estimate book, procedure code, or linked run/step does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired

Request Body

allowed_feenumberrequired

Computed allowed fee amount.

computed_atstring (date-time)required

Timestamp when the fee was computed.

confidencestring
estimate_book_rule_step_uuidstring (uuid)
estimate_book_run_uuidstring (uuid)
expires_atstring (date-time)
group_numberstring
procedure_code_uuidstring (uuid)required

UUID of the procedure code.

resolution_scope_identifierinteger
resolution_scope_typestringrequired

Scope at which the fee was resolved. One of: insurance_plan, group_number, insurance_carrier.

sample_countinteger

Number of evidence entries used to compute the fee.

Responses

201Successful Response
allowed_feenumberrequired

Computed allowed fee amount.

computed_atstring (date-time)required

When the fee was computed.

confidencestring
created_atstring (date-time)required

Timestamp when the entry was created.

estimate_bookobjectrequired

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

estimate_book_rule_stepobject

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

estimate_book_runobject

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

expires_atstring (date-time)
group_numberstring
idstring (uuid)required

Allowed fee UUID.

procedure_codeobjectrequired

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

resolution_scope_identifierinteger
resolution_scope_typestringrequired

Scope. One of: insurance_plan, group_number, insurance_carrier.

sample_countintegerrequired

Number of evidence entries used.

updated_atstring (date-time)required

Timestamp of the last update.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/allowed-fees" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_fee": 1,
    "computed_at": "2025-01-15T09:00:00Z",
    "confidence": "string",
    "estimate_book_rule_step_uuid": "string",
    "estimate_book_run_uuid": "string",
    "procedure_code_uuid": "00000000-0000-0000-0000-000000000000",
    "resolution_scope_type": "string"
  }'
post/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/archive

Archive estimate book

Soft-delete an estimate book by setting deleted_at. Raises 404 if the estimate book does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
allowed_fee_scheduleobject

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

carrierobject

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

claim_match_methodstring
created_atstring (date-time)required

Timestamp when the book was created.

deleted_atstring (date-time)
exclude_over_ucrboolean

Whether to cap allowed fees at the UCR amount.

idstring (uuid)required

Estimate book UUID.

insurance_planobject

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

namestringrequired

Display name.

rule_typestringrequired

Rule type. One of: manual_fee_schedule, allowed_from_claims, ucr_fallback.

scope_typestringrequired

Scope. One of: tenant, carrier, plan.

statusstringrequired

Status. One of: active, archived.

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/evidence

Create evidence entry

Record a claim payment observation as evidence. Raises 404 if the estimate book or procedure code does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired

Request Body

allowed_overridenumber
carrier_uuidstring (uuid)
claim_rolestring
clinical_procedure_uuidstring (uuid)
group_numberstring
insurance_claim_identifierinteger
insurance_claim_procedure_identifierinteger
insurance_payment_amountnumber
insurance_plan_uuidstring (uuid)
procedure_code_uuidstring (uuid)required

UUID of the procedure code observed.

procedure_service_datestring (date)required

Date the procedure was performed.

source_typestringrequired

Source of this evidence. One of: adjudicated_claim, import, manual.

Responses

201Successful Response
allowed_overridenumber
carrierobject

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

claim_rolestring
clinical_procedure_uuidstring (uuid)
created_atstring (date-time)required

Timestamp when the entry was created.

estimate_bookobjectrequired

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

group_numberstring
idstring (uuid)required

Evidence entry UUID.

insurance_claim_identifierinteger
insurance_claim_procedure_identifierinteger
insurance_payment_amountnumber
insurance_planobject

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

procedure_codeobjectrequired

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

procedure_service_datestring (date)required

Date the procedure was performed.

source_typestringrequired

Evidence source. One of: adjudicated_claim, import, manual.

updated_atstring (date-time)required

Timestamp of the last update.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/evidence" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_override": null,
    "carrier_uuid": "string",
    "claim_role": "string",
    "clinical_procedure_uuid": "string",
    "group_number": "string",
    "procedure_code_uuid": "00000000-0000-0000-0000-000000000000",
    "procedure_service_date": "2025-01-15",
    "source_type": "string"
  }'
post/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/recompute

Recompute estimate book

Start a recomputation run for the estimate book. Creates a new run and recomputes all allowed fees. Raises 404 if the estimate book does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the run record was created.

deleted_atstring (date-time)
errorstring
estimate_bookobjectrequired

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

finished_atstring (date-time)
idstring (uuid)required

Run UUID.

started_atstring (date-time)required

Timestamp when the run started.

statusstringrequired

Run status. One of: running, completed, failed.

summary_jsonobject
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/recompute" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/rule-steps

Create rule step

Create a rule step defining fee computation logic. Raises 404 if the estimate book does not exist.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired

Request Body

is_activeboolean

Whether this step is active.

limit_typestring

Limit type for sample filtering. One of: none, years, months, weeks, days.

limit_valueinteger

Limit value (e.g., 2 for '2 years').

priority_orderintegerrequired

Execution order (lower runs first).

rule_typestringrequired

Rule type. One of: insurance_plan, group_number, insurance_carrier, insurance_carrier_group, manual_fee_schedule, provider_fee.

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the step was created.

estimate_bookobjectrequired

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

idstring (uuid)required

Rule step UUID.

is_activebooleanrequired

Whether this step is active.

limit_typestringrequired

Limit type. One of: none, years, months, weeks, days.

limit_valueintegerrequired

Limit value (e.g., 2 for '2 years').

priority_orderintegerrequired

Execution order (lower runs first).

rule_typestringrequired

Rule type. One of: insurance_plan, group_number, insurance_carrier, insurance_carrier_group, manual_fee_schedule, provider_fee.

updated_atstring (date-time)required

Timestamp of the last update.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/rule-steps" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": true,
    "limit_type": "none",
    "limit_value": 0,
    "priority_order": 1,
    "rule_type": "string"
  }'
post/api/v1/{org_id}/insurance/fee-resolution/debug

Debug fee resolution

Trace the full fee resolution process step by step. Walks the assignment hierarchy for each kind (ucr, primary, copay, etc.) and shows match/skip/miss at each level. Does NOT invoke the full estimation orchestrator — this is a diagnostic tool for assignment configuration. Raises 404 if any referenced entity (location, plan, procedure code) is not found.

Parameters

Path Parameters
org_idstringrequired

Request Body

date_of_servicestring (date)required

Date of service for resolution.

insurance_plan_uuidstring (uuid)required

Insurance plan UUID for the patient.

location_uuidstring (uuid)required

Location UUID where the procedure is performed.

procedure_codestringrequired

CDT procedure code (e.g., 'D0120').

provider_uuidstring (uuid)

Responses

200Successful Response
date_of_servicestring (date)required

The date of service used.

insurance_planobjectrequired

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

locationobjectrequired

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

procedure_codestringrequired

The procedure code queried.

statusstringrequired

Overall status. One of: resolved, partial, no_match.

summaryobjectrequired

Per-kind resolved fees (e.g., {'ucr': 150.00, 'primary': 120.00}).

tracesobject[]required

Detailed per-kind resolution traces.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-resolution/debug" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date_of_service": "2025-01-15",
    "insurance_plan_uuid": "00000000-0000-0000-0000-000000000000",
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "procedure_code": "string",
    "provider_uuid": "string"
  }'
post/api/v1/{org_id}/insurance/fee-schedule-assignments

Create assignment

Create a new fee schedule assignment linking a schedule to a location slot. Validates purpose-kind compatibility and checks for date-range overlaps. Raises 409 if an overlapping assignment already exists in the same slot. Raises 422 if the fee schedule purpose is incompatible with the assignment kind.

Parameters

Path Parameters
org_idstringrequired

Request Body

assignment_kindstringrequired

Kind of assignment. One of: ucr, primary, copay, out_of_network, allowed, manual_blue_book.

carrier_uuidstring (uuid)
effective_endstring (date)
effective_startstring (date)
estimate_book_uuidstring (uuid)
fee_schedule_uuidstring (uuid)required

Fee schedule to assign.

insurance_plan_uuidstring (uuid)
location_uuidstring (uuid)required

Location this assignment applies to.

notesstring

Responses

201Successful Response
assignment_kindstringrequired

Kind of assignment. One of: ucr, primary, copay, out_of_network, allowed, manual_blue_book.

carrierobject

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

created_atstring (date-time)required
effective_endstring (date)
effective_startstring (date)required

Start date of this assignment.

estimate_bookobject

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

fee_scheduleobjectrequired

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

idstring (uuid)required

Assignment UUID.

insurance_planobject

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

locationobjectrequired

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

notesstring
updated_atstring (date-time)required
versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assignment_kind": "string",
    "carrier_uuid": "string",
    "effective_end": "string",
    "effective_start": "string",
    "estimate_book_uuid": "string",
    "fee_schedule_uuid": "00000000-0000-0000-0000-000000000000",
    "location_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/insurance/fee-schedule-assignments/{assignment_uuid}/archive

Archive assignment

Archive (soft-delete) a fee schedule assignment. Raises 404 if the assignment does not exist.

Parameters

Path Parameters
assignment_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
assignment_kindstringrequired

Kind of assignment. One of: ucr, primary, copay, out_of_network, allowed, manual_blue_book.

carrierobject

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

created_atstring (date-time)required
effective_endstring (date)
effective_startstring (date)required

Start date of this assignment.

estimate_bookobject

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

fee_scheduleobjectrequired

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

idstring (uuid)required

Assignment UUID.

insurance_planobject

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

locationobjectrequired

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

notesstring
updated_atstring (date-time)required
versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments/{assignment_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/fee-schedule-assignments/bulk

Bulk assign to locations

Assign a fee schedule to multiple locations in a single request. Each location is processed independently inside a savepoint — failures on individual locations do not roll back other locations. Returns a per-location result set with success/failure status. Raises 422 if assignment_kind is invalid or fee schedule purpose is incompatible.

Parameters

Path Parameters
org_idstringrequired

Request Body

assignment_kindstringrequired

Kind of assignment. One of: ucr, primary, copay, out_of_network, allowed, manual_blue_book.

carrier_uuidstring (uuid)
effective_endstring (date)
effective_startstring (date)
estimate_book_uuidstring (uuid)
fee_schedule_uuidstring (uuid)required

Fee schedule to assign to each location.

insurance_plan_uuidstring (uuid)
location_uuidsstring (uuid)[]required

Location UUIDs to assign the fee schedule to (1–100).

notesstring

Responses

200Successful Response
failedintegerrequired

Number of locations that failed.

resultsobject[]required

Per-location results.

succeededintegerrequired

Number of locations that succeeded.

totalintegerrequired

Total number of locations attempted.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assignment_kind": "string",
    "carrier_uuid": "string",
    "effective_end": "string",
    "effective_start": "string",
    "estimate_book_uuid": "string",
    "fee_schedule_uuid": "00000000-0000-0000-0000-000000000000",
    "location_uuids": []
  }'
post/api/v1/{org_id}/insurance/patient-plans/{patient_plan_uuid}/benefits

Create patient benefit override

Create a patient-level benefit override for a patient plan. This benefit overrides the plan-level default for the same (coverage_category, benefit_type) combination. Raises 404 if the patient plan does not exist. Raises 409 if a conflicting benefit already exists.

Parameters

Path Parameters
patient_plan_uuidstringrequired
org_idstringrequired

Request Body

age_maxinteger
age_mininteger
benefit_typestringrequired

Benefit type. One of: coinsurance, deductible, annual_max, ortho_lifetime_max, exclusion, limitation, waiting_period, copayment, family_deductible, family_annual_max.

coverage_category_uuidstring (uuid)
is_deductible_exemptboolean
monetary_amtnumber
percentinteger
procedure_code_uuidstring (uuid)
quantityinteger
quantity_qualifierstring
substitution_code_uuidstring (uuid)
time_periodstring
waiting_period_monthsinteger

Responses

201Successful Response
age_maxinteger
age_mininteger
benefit_typestringrequired

Benefit type. One of: coinsurance, deductible, annual_max, ortho_lifetime_max, exclusion, limitation, waiting_period, copayment, family_deductible, family_annual_max.

coverage_categoryobject

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

created_atstring (date-time)required

Timestamp when the benefit was created.

deleted_atstring (date-time)
idstring (uuid)required

Benefit UUID.

insurance_planobject

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

is_deductible_exemptboolean

Whether exempt from the deductible.

monetary_amtstring
patient_planobject

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

percentinteger
procedure_codeobject

Brief procedure code info embedded in fee entries.

quantityinteger
quantity_qualifierstring
substitution_codeobject

Brief procedure code info embedded in fee entries.

time_periodstring
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version for optimistic concurrency.

waiting_period_monthsinteger
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/patient-plans/{patient_plan_uuid}/benefits" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "age_max": 1,
    "age_min": 1,
    "benefit_type": "string",
    "coverage_category_uuid": "string",
    "is_deductible_exempt": null
  }'
post/api/v1/{org_id}/insurance/patients/{patient_uuid}/insurance

Create patient plan

Assign an insurance plan to a patient via subscription. Raises 404 if the patient or subscription does not exist. Raises 422 if the patient already has 3 plans assigned.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

cob_order_overrideinteger
coverage_typeenum
dentalmedicalvision
fee_schedule_uuidstring (uuid)
insurance_subscription_uuidstring (uuid)required

UUID of the insurance subscription to link.

is_pendingboolean
ordinalinteger
pat_id_overridestring
relationship_to_subscriberenumrequired

Relationship to the subscriber. One of: self, spouse, child, other.

childotherselfspouse

Responses

201Successful Response
benefits_last_verified_atstring (date-time)
benefits_summaryobject

Plan-level benefit totals. Usage values are zeros until claims tracking is implemented — only the *_total fields carry real data from ``InsuranceBenefit`` rows.

cob_order_overrideinteger
coverage_typeenumrequired

Coverage type. One of: dental, medical, vision.

dentalmedicalvision
created_atstring (date-time)required

Timestamp when the patient plan was created.

deleted_atstring (date-time)
eligibility_last_verified_atstring (date-time)
fee_scheduleobject

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

idstring (uuid)required

Patient plan UUID.

is_pendingboolean

Whether this plan assignment is pending verification.

ordinalintegerrequired

Priority ordinal (1=primary, 2=secondary, 3=tertiary).

pat_id_overridestring
patientobjectrequired

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

relationship_to_subscriberenumrequired

Relationship to subscriber. One of: self, spouse, child, other.

childotherselfspouse
statusenum

Plan status. One of: active, inactive, pending_verification.

activeinactivepending_verification
subscriptionobject

Brief subscription info nested inside PatientPlanOut. ``subscriber`` is non-nullable — ``subscriber_id`` is NOT NULL in the DB and the relationship must be eager-loaded. If the eager-load is missing, Pydantic validation will fail (desired fail-fast behavior).

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/patients/{patient_uuid}/insurance" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cob_order_override": 1,
    "coverage_type": "string",
    "fee_schedule_uuid": "string",
    "insurance_subscription_uuid": "00000000-0000-0000-0000-000000000000",
    "is_pending": null,
    "relationship_to_subscriber": "child"
  }'
post/api/v1/{org_id}/insurance/patients/{patient_uuid}/insurance/{patient_plan_uuid}/archive

Archive patient plan

Soft-delete a patient plan assignment. Raises 404 if the patient or patient plan does not exist.

Parameters

Path Parameters
patient_uuidstringrequired
patient_plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
benefits_last_verified_atstring (date-time)
benefits_summaryobject

Plan-level benefit totals. Usage values are zeros until claims tracking is implemented — only the *_total fields carry real data from ``InsuranceBenefit`` rows.

cob_order_overrideinteger
coverage_typeenumrequired

Coverage type. One of: dental, medical, vision.

dentalmedicalvision
created_atstring (date-time)required

Timestamp when the patient plan was created.

deleted_atstring (date-time)
eligibility_last_verified_atstring (date-time)
fee_scheduleobject

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

idstring (uuid)required

Patient plan UUID.

is_pendingboolean

Whether this plan assignment is pending verification.

ordinalintegerrequired

Priority ordinal (1=primary, 2=secondary, 3=tertiary).

pat_id_overridestring
patientobjectrequired

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

relationship_to_subscriberenumrequired

Relationship to subscriber. One of: self, spouse, child, other.

childotherselfspouse
statusenum

Plan status. One of: active, inactive, pending_verification.

activeinactivepending_verification
subscriptionobject

Brief subscription info nested inside PatientPlanOut. ``subscriber`` is non-nullable — ``subscriber_id`` is NOT NULL in the DB and the relationship must be eager-loaded. If the eager-load is missing, Pydantic validation will fail (desired fail-fast behavior).

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/patients/{patient_uuid}/insurance/{patient_plan_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/patients/{patient_uuid}/insurance/reorder

Reorder patient plans

Change the priority ordering of a patient's insurance plans. Updates ordinal values (1=primary, 2=secondary, 3=tertiary). Raises 404 if the patient or any patient plan does not exist.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

itemsobject[]required

List of patient plan UUIDs with their new ordinals.

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/patients/{patient_uuid}/insurance/reorder" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": []
  }'
post/api/v1/{org_id}/insurance/plans

Create insurance plan

Create a new insurance plan under a carrier. Raises 404 if the carrier_uuid does not exist. Raises 409 on idempotency conflict.

Parameters

Path Parameters
org_idstringrequired

Request Body

assignment_of_benefitsboolean
benefit_year_start_monthinteger
carrier_uuidstring (uuid)required

UUID of the carrier this plan belongs to.

claim_form_typeenum
ada_2019cms_1500
claims_use_ucrboolean
cob_ruleenum
basiccarve_outsecondary_medicaidstandard
eclaim_send_behaviorenum
do_not_sendsecondary_onlysend
filing_codestring
filing_code_subtypestring
group_namestring
group_numberstring
is_hiddenboolean
is_medicalboolean
is_verification_exemptboolean
ortho_auto_claim_days_waitinteger
ortho_auto_claim_typeenum
initial_onlyinitial_plus_periodicinitial_plus_visitnone
ortho_auto_fee_amtnumber
ortho_auto_proc_codestring
plan_notestring
plan_typeenumrequired

Plan type. One of: category_percentage, ppo_percentage, ppo_fixed_benefit, medicaid_flat_copay, capitation.

capitationcategory_percentagemedicaid_flat_copayppo_fixed_benefitppo_percentage
release_of_informationboolean
show_base_unitsboolean
substitution_code_behaviorenum
customdowngrade_to_amalgamnone

Responses

201Successful Response
assignment_of_benefitsboolean

Whether assignment of benefits is accepted.

benefit_year_start_monthinteger

Month (1-12) the benefit year starts.

carrierobject

Brief carrier reference embedded in plan output.

claim_form_typeenumrequired

Claim form type. One of: ada_2019, cms_1500.

ada_2019cms_1500
claims_use_ucrboolean

Whether claims use UCR fees.

cob_ruleenum
basiccarve_outsecondary_medicaidstandard
created_atstring (date-time)required

Timestamp when the plan was created.

deleted_atstring (date-time)
eclaim_send_behaviorenumrequired

E-claim send behavior. One of: send, do_not_send, secondary_only.

do_not_sendsecondary_onlysend
filing_codestring
filing_code_subtypestring
group_namestring
group_numberstring
idstring (uuid)required

Plan UUID.

is_hiddenboolean

Whether hidden from default list views.

is_medicalboolean

Whether this is a medical plan.

is_verification_exemptboolean

Whether verification-exempt.

ortho_auto_claim_days_waitinteger

Days to wait between ortho auto-claims.

ortho_auto_claim_typeenumrequired

Ortho auto-claim type. One of: none, initial_only, initial_plus_visit, initial_plus_periodic.

initial_onlyinitial_plus_periodicinitial_plus_visitnone
ortho_auto_fee_amtstring
ortho_auto_proc_codestring
plan_notestring
plan_typeenumrequired

Plan type. One of: category_percentage, ppo_percentage, ppo_fixed_benefit, medicaid_flat_copay, capitation.

capitationcategory_percentagemedicaid_flat_copayppo_fixed_benefitppo_percentage
release_of_informationboolean

Whether release of information is authorized.

show_base_unitsboolean

Whether to show base units on claims.

substitution_code_behaviorenumrequired

Substitution code behavior. One of: none, downgrade_to_amalgam, custom.

customdowngrade_to_amalgamnone
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/plans" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assignment_of_benefits": null,
    "benefit_year_start_month": 1,
    "carrier_uuid": "00000000-0000-0000-0000-000000000000",
    "claim_form_type": "string",
    "claims_use_ucr": null,
    "plan_type": "capitation"
  }'
post/api/v1/{org_id}/insurance/plans/{plan_uuid}/archive

Archive insurance plan

Soft-delete an insurance plan by setting deleted_at. Raises 404 if the plan does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
assignment_of_benefitsboolean

Whether assignment of benefits is accepted.

benefit_year_start_monthinteger

Month (1-12) the benefit year starts.

carrierobject

Brief carrier reference embedded in plan output.

claim_form_typeenumrequired

Claim form type. One of: ada_2019, cms_1500.

ada_2019cms_1500
claims_use_ucrboolean

Whether claims use UCR fees.

cob_ruleenum
basiccarve_outsecondary_medicaidstandard
created_atstring (date-time)required

Timestamp when the plan was created.

deleted_atstring (date-time)
eclaim_send_behaviorenumrequired

E-claim send behavior. One of: send, do_not_send, secondary_only.

do_not_sendsecondary_onlysend
filing_codestring
filing_code_subtypestring
group_namestring
group_numberstring
idstring (uuid)required

Plan UUID.

is_hiddenboolean

Whether hidden from default list views.

is_medicalboolean

Whether this is a medical plan.

is_verification_exemptboolean

Whether verification-exempt.

ortho_auto_claim_days_waitinteger

Days to wait between ortho auto-claims.

ortho_auto_claim_typeenumrequired

Ortho auto-claim type. One of: none, initial_only, initial_plus_visit, initial_plus_periodic.

initial_onlyinitial_plus_periodicinitial_plus_visitnone
ortho_auto_fee_amtstring
ortho_auto_proc_codestring
plan_notestring
plan_typeenumrequired

Plan type. One of: category_percentage, ppo_percentage, ppo_fixed_benefit, medicaid_flat_copay, capitation.

capitationcategory_percentagemedicaid_flat_copayppo_fixed_benefitppo_percentage
release_of_informationboolean

Whether release of information is authorized.

show_base_unitsboolean

Whether to show base units on claims.

substitution_code_behaviorenumrequired

Substitution code behavior. One of: none, downgrade_to_amalgam, custom.

customdowngrade_to_amalgamnone
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits

Create benefit

Create a benefit rule for an insurance plan. Raises 404 if the plan or any referenced entity does not exist. Raises 409 on idempotency conflict.

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

age_maxinteger
age_mininteger
benefit_typestringrequired

Benefit type. One of: coinsurance, deductible, annual_max, ortho_lifetime_max, exclusion, limitation, waiting_period, copayment, family_deductible, family_annual_max.

coverage_category_uuidstring (uuid)
is_deductible_exemptboolean
monetary_amtnumber
percentinteger
procedure_code_uuidstring (uuid)
quantityinteger
quantity_qualifierstring
substitution_code_uuidstring (uuid)
time_periodstring
waiting_period_monthsinteger

Responses

201Successful Response
age_maxinteger
age_mininteger
benefit_typestringrequired

Benefit type. One of: coinsurance, deductible, annual_max, ortho_lifetime_max, exclusion, limitation, waiting_period, copayment, family_deductible, family_annual_max.

coverage_categoryobject

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

created_atstring (date-time)required

Timestamp when the benefit was created.

deleted_atstring (date-time)
idstring (uuid)required

Benefit UUID.

insurance_planobject

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

is_deductible_exemptboolean

Whether exempt from the deductible.

monetary_amtstring
patient_planobject

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

percentinteger
procedure_codeobject

Brief procedure code info embedded in fee entries.

quantityinteger
quantity_qualifierstring
substitution_codeobject

Brief procedure code info embedded in fee entries.

time_periodstring
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version for optimistic concurrency.

waiting_period_monthsinteger
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "age_max": 1,
    "age_min": 1,
    "benefit_type": "string",
    "coverage_category_uuid": "string",
    "is_deductible_exempt": null
  }'
post/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits/bulk

Bulk set benefits

Replace all benefits for a plan with the provided set. Existing benefits are deleted and replaced. Raises 404 if the plan does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

benefitsobject[]required

List of benefit definitions to set.

Responses

200Successful Response
itemsobject[]required

List of benefit records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching benefits.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "benefits": []
  }'
post/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits/copy-from/{source_plan_uuid}

Copy benefits from another plan

Copy all benefits from a source plan to the target plan. Existing benefits on the target plan are not removed. Raises 404 if either plan does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
source_plan_uuidstringrequired
org_idstringrequired

Responses

201Successful Response
countintegerrequired

Number of benefits copied.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits/copy-from/{source_plan_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/plans/{plan_uuid}/clone

Clone insurance plan

Create a copy of an existing plan with all its settings and benefits. Optionally provide ``new_group_name`` and ``new_group_number`` to override the cloned plan's group name/number instead of using the default "(Copy)" suffix. Raises 404 if the source plan does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

new_group_namestring
new_group_numberstring

Responses

201Successful Response
assignment_of_benefitsboolean

Whether assignment of benefits is accepted.

benefit_year_start_monthinteger

Month (1-12) the benefit year starts.

carrierobject

Brief carrier reference embedded in plan output.

claim_form_typeenumrequired

Claim form type. One of: ada_2019, cms_1500.

ada_2019cms_1500
claims_use_ucrboolean

Whether claims use UCR fees.

cob_ruleenum
basiccarve_outsecondary_medicaidstandard
created_atstring (date-time)required

Timestamp when the plan was created.

deleted_atstring (date-time)
eclaim_send_behaviorenumrequired

E-claim send behavior. One of: send, do_not_send, secondary_only.

do_not_sendsecondary_onlysend
filing_codestring
filing_code_subtypestring
group_namestring
group_numberstring
idstring (uuid)required

Plan UUID.

is_hiddenboolean

Whether hidden from default list views.

is_medicalboolean

Whether this is a medical plan.

is_verification_exemptboolean

Whether verification-exempt.

ortho_auto_claim_days_waitinteger

Days to wait between ortho auto-claims.

ortho_auto_claim_typeenumrequired

Ortho auto-claim type. One of: none, initial_only, initial_plus_visit, initial_plus_periodic.

initial_onlyinitial_plus_periodicinitial_plus_visitnone
ortho_auto_fee_amtstring
ortho_auto_proc_codestring
plan_notestring
plan_typeenumrequired

Plan type. One of: category_percentage, ppo_percentage, ppo_fixed_benefit, medicaid_flat_copay, capitation.

capitationcategory_percentagemedicaid_flat_copayppo_fixed_benefitppo_percentage
release_of_informationboolean

Whether release of information is authorized.

show_base_unitsboolean

Whether to show base units on claims.

substitution_code_behaviorenumrequired

Substitution code behavior. One of: none, downgrade_to_amalgam, custom.

customdowngrade_to_amalgamnone
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}/clone" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/subscriptions

Create subscription

Create a new insurance subscription. Returns the subscription and an optional duplicate_warning if a similar subscription already exists (same subscriber + plan). Raises 404 if the plan or subscriber does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

benefit_notesstring
date_effectivestring (date)
date_termstring (date)
insurance_plan_uuidstring (uuid)required

UUID of the insurance plan to subscribe to.

statusstring
subscriber_id_numberstringrequired

Subscriber ID number assigned by the carrier.

subscriber_notestring
subscriber_uuidstring (uuid)required

UUID of the patient who is the subscriber.

Responses

201Successful Response
duplicate_warningobject

Full insurance subscription output.

subscriptionobjectrequired

Full insurance subscription output.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/subscriptions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "benefit_notes": "string",
    "date_effective": "string",
    "date_term": "string",
    "insurance_plan_uuid": "00000000-0000-0000-0000-000000000000",
    "status": "string",
    "subscriber_id_number": "string",
    "subscriber_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/insurance/subscriptions/{subscription_uuid}/archive

Archive subscription

Soft-delete a subscription by setting deleted_at. Raises 404 if the subscription does not exist.

Parameters

Path Parameters
subscription_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
benefit_notesstring
carrierobject

Brief carrier reference embedded in plan output.

created_atstring (date-time)required

Timestamp when the subscription was created.

date_effectivestring (date)
date_termstring (date)
deleted_atstring (date-time)
idstring (uuid)required

Subscription UUID.

insurance_planobject

Brief insurance plan reference embedded in subscription output.

last_verified_atstring (date-time)
last_verified_sourcestring
statusstringrequired

Subscription status. One of: active, terminated, pending_verification.

subscriberobjectrequired

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

subscriber_id_numberstringrequired

Subscriber ID number from the carrier.

subscriber_notestring
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/subscriptions/{subscription_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/subscriptions/{subscription_uuid}/terminate

Terminate subscription

Terminate a subscription with a specific date. Sets status to 'terminated' and deactivates associated patient plans. Raises 404 if the subscription does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
subscription_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

termination_datestring (date)required

Date the subscription terminates.

Responses

200Successful Response
patient_plans_affectedintegerrequired

Number of patient plans deactivated as a result of termination.

subscriptionobjectrequired

Full insurance subscription output.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/subscriptions/{subscription_uuid}/terminate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "termination_date": "2025-01-15"
  }'
post/api/v1/{org_id}/insurance/subscriptions/bulk-terminate

Bulk terminate subscriptions

Terminate multiple subscriptions with a given date. Also deactivates associated patient plans. Raises 404 if any subscription UUID does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

subscription_idsstring (uuid)[]required

UUIDs of subscriptions to terminate.

term_datestring (date)required

Termination date to apply to all subscriptions.

Responses

200Successful Response
patient_plans_deactivatedintegerrequired

Number of patient plans deactivated.

terminatedintegerrequired

Number of subscriptions terminated.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/subscriptions/bulk-terminate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_ids": [],
    "term_date": "2025-01-15"
  }'
post/api/v1/{org_id}/insurance/verifications

Record verification

Record a new insurance verification result. Exactly one of patient_plan_uuid or insurance_plan_uuid must be provided. Raises 404 if the patient plan or insurance plan does not exist. Raises 422 if both or neither owner UUID is provided.

Parameters

Path Parameters
org_idstringrequired

Request Body

assigned_to_user_uuidstring (uuid)
call_duration_minutesinteger
carrier_ref_numberstring
carrier_rep_namestring
insurance_plan_uuidstring (uuid)
next_verification_duestring (date)
notesstring
patient_plan_uuidstring (uuid)
verification_sourceenumrequired

How the verification was obtained. One of: manual, phone, electronic, fax.

electronicfaxmanualphone
verification_statusenumrequired

Outcome of verification. One of: verified, failed, partial, unable_to_verify.

failedpartialunable_to_verifyverified
verification_typeenumrequired

Type of verification. One of: eligibility, benefits.

benefitseligibility

Responses

201Successful Response
assigned_to_user_uuidstring (uuid)
call_duration_minutesinteger
carrier_ref_numberstring
carrier_rep_namestring
created_atstring (date-time)required

Timestamp when the record was created.

deleted_atstring (date-time)
idstring (uuid)required

Verification UUID.

insurance_plan_uuidstring (uuid)
next_verification_duestring (date)
notesstring
patient_plan_uuidstring (uuid)
raw_response_jsonobject
updated_atstring (date-time)required

Timestamp of the last update.

verification_sourceenumrequired

Source. One of: manual, phone, electronic, fax.

electronicfaxmanualphone
verification_statusenumrequired

Status. One of: verified, failed, partial, unable_to_verify.

failedpartialunable_to_verifyverified
verification_typeenumrequired

Type. One of: eligibility, benefits.

benefitseligibility
verified_atstring (date-time)required

Timestamp when the verification was performed.

verified_by_user_uuidstring (uuid)
versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/verifications" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assigned_to_user_uuid": "string",
    "call_duration_minutes": 1,
    "carrier_ref_number": "string",
    "carrier_rep_name": "string",
    "insurance_plan_uuid": "string",
    "verification_source": "electronic",
    "verification_status": "failed",
    "verification_type": "benefits"
  }'
post/api/v1/{org_id}/insurance/verifications/bulk

Bulk record verifications

Bulk-record multiple insurance verifications in one request. Each entry must specify exactly one of patient_plan_uuid or insurance_plan_uuid. Raises 404 if any referenced entity does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

verificationsobject[]required

List of verification entries to record.

Responses

201Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/verifications/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "verifications": []
  }'
post/api/v1/{org_id}/insurance/verifications/bulk-mark

Bulk-update verification status

Bulk update the verification_status of multiple verifications. All provided verification UUIDs must exist. Returns the count of updated verifications. Raises 404 if any verification UUID does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

verification_statusenumrequired

New status. One of: verified, failed, partial, unable_to_verify.

failedpartialunable_to_verifyverified
verification_uuidsstring (uuid)[]required

UUIDs of verifications to update.

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/verifications/bulk-mark" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_status": "failed",
    "verification_uuids": []
  }'
put/api/v1/{org_id}/insurance/drafts/{draft_uuid}/match

Match draft

Manually match a draft to a carrier, plan, and/or subscriber. Raises 404 if the draft or any referenced entity does not exist.

Parameters

Path Parameters
draft_uuidstringrequired
org_idstringrequired

Request Body

carrier_uuidstring (uuid)
plan_uuidstring (uuid)
subscriber_patient_uuidstring (uuid)

Responses

200Successful Response
conversion_errorstring
converted_patient_planobject

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

converted_subscriptionobject

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

created_atstring (date-time)required

Timestamp when the draft was created.

idstring (uuid)required

Draft UUID.

matched_carrierobject

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

matched_planobject

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

patientobjectrequired

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

raw_data_jsonobjectrequired

Original raw import data.

review_statusstringrequired

Review status. One of: pending, matched, converted, rejected, error.

reviewed_atstring (date-time)
reviewed_by_user_uuidstring (uuid)
source_refstring
source_systemstring
subscriber_patientobject

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

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PUT "https://api.example.com/api/v1/{org_id}/insurance/drafts/{draft_uuid}/match" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier_uuid": "string",
    "plan_uuid": "string",
    "subscriber_patient_uuid": "string"
  }'
patch/api/v1/{org_id}/insurance/carriers/{carrier_uuid}

Update carrier

Update mutable fields on an existing carrier. Raises 404 if the carrier does not exist. Raises 409 if base_version does not match (optimistic concurrency).

Parameters

Path Parameters
carrier_uuidstringrequired
org_idstringrequired

Request Body

address_line1string
address_line2string
base_versionintegerrequired

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

carrier_group_namestring
carrier_namestring
citystring
cob_insurance_paid_behavior_overridestring
electronic_filing_typeenum
do_not_send_electronicallydo_not_send_secondary_electronicallysend_electronically
electronic_idstring
era_automation_overrideenum
auto_receivedo_not_processmanual_review
is_hiddenboolean
notesstring
phonestring
statestring
trust_levelenum
standardtrusteduntrusted
zip_codestring

Responses

200Successful Response
address_line1string
address_line2string
carrier_group_namestring
carrier_namestringrequired

Display name of the carrier.

citystring
cob_insurance_paid_behavior_overridestring
created_atstring (date-time)required

Timestamp when the carrier was created.

deleted_atstring (date-time)
electronic_filing_typeenum
do_not_send_electronicallydo_not_send_secondary_electronicallysend_electronically
electronic_idstring
era_automation_overrideenum
auto_receivedo_not_processmanual_review
idstring (uuid)required

Carrier UUID.

is_hiddenboolean

Whether the carrier is hidden from default list views.

notesstring
phonestring
statestring
trust_levelenumrequired

Trust level. One of: standard, trusted, untrusted.

standardtrusteduntrusted
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

zip_codestring
422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/carriers/{carrier_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address_line1": "string",
    "address_line2": "string",
    "base_version": 1,
    "carrier_group_name": "string",
    "carrier_name": "string"
  }'
patch/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}

Update coverage category

Update mutable fields on a coverage category. Raises 404 if the category does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
category_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

category_namestring
descriptionstring
is_hiddenboolean
item_orderinteger

Responses

200Successful Response
category_namestringrequired

Display name of the category.

created_atstring (date-time)required

Timestamp when the category was created.

deleted_atstring (date-time)
descriptionstring
idstring (uuid)required

Category UUID.

is_hiddenboolean

Whether hidden from default list views.

is_systemboolean

Whether this is a system-seeded category protected from archiving.

item_orderinteger

Sort order among categories.

spansobject[]
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "category_name": "string",
    "description": "string",
    "is_hidden": null,
    "item_order": 1
  }'
patch/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/spans/{span_uuid}

Update coverage span

Update a procedure code span. Returns the updated span plus any overlapping spans as warnings. Raises 404 if the category or span does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
category_uuidstringrequired
span_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

from_codestring
is_exclusionboolean
item_orderinteger
to_codestring

Responses

200Successful Response
overlapping_spansobject[]required

Spans with overlapping code ranges (for warning display).

spanobjectrequired

Full procedure code span output.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/spans/{span_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "from_code": "string",
    "is_exclusion": null,
    "item_order": 1,
    "to_code": "string"
  }'
patch/api/v1/{org_id}/insurance/estimate-books/{book_uuid}

Update estimate book

Update mutable fields on an estimate book. Raises 404 if the estimate book does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
book_uuidstringrequired
org_idstringrequired

Request Body

allowed_fee_schedule_uuidstring (uuid)
base_versionintegerrequired

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

carrier_uuidstring (uuid)
claim_match_methodstring
exclude_over_ucrboolean
insurance_plan_uuidstring (uuid)
namestring
rule_typestring
scope_typestring
statusstring

Responses

200Successful Response
allowed_fee_scheduleobject

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

carrierobject

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

claim_match_methodstring
created_atstring (date-time)required

Timestamp when the book was created.

deleted_atstring (date-time)
exclude_over_ucrboolean

Whether to cap allowed fees at the UCR amount.

idstring (uuid)required

Estimate book UUID.

insurance_planobject

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

namestringrequired

Display name.

rule_typestringrequired

Rule type. One of: manual_fee_schedule, allowed_from_claims, ucr_fallback.

scope_typestringrequired

Scope. One of: tenant, carrier, plan.

statusstringrequired

Status. One of: active, archived.

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_fee_schedule_uuid": "string",
    "base_version": 1,
    "carrier_uuid": "string",
    "claim_match_method": "string",
    "exclude_over_ucr": null
  }'
patch/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/allowed-fees/{entry_uuid}

Update allowed fee

Update mutable fields on an allowed fee entry. Raises 404 if the estimate book or allowed fee does not exist.

Parameters

Path Parameters
book_uuidstringrequired
entry_uuidstringrequired
org_idstringrequired

Request Body

allowed_feenumber
computed_atstring (date-time)
confidencestring
expires_atstring (date-time)
sample_countinteger

Responses

200Successful Response
allowed_feenumberrequired

Computed allowed fee amount.

computed_atstring (date-time)required

When the fee was computed.

confidencestring
created_atstring (date-time)required

Timestamp when the entry was created.

estimate_bookobjectrequired

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

estimate_book_rule_stepobject

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

estimate_book_runobject

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

expires_atstring (date-time)
group_numberstring
idstring (uuid)required

Allowed fee UUID.

procedure_codeobjectrequired

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

resolution_scope_identifierinteger
resolution_scope_typestringrequired

Scope. One of: insurance_plan, group_number, insurance_carrier.

sample_countintegerrequired

Number of evidence entries used.

updated_atstring (date-time)required

Timestamp of the last update.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/allowed-fees/{entry_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_fee": null,
    "computed_at": "string",
    "confidence": "string",
    "expires_at": "string",
    "sample_count": 1
  }'
patch/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/rule-steps/{step_uuid}

Update rule step

Update mutable fields on a rule step. Raises 404 if the estimate book or rule step does not exist.

Parameters

Path Parameters
book_uuidstringrequired
step_uuidstringrequired
org_idstringrequired

Request Body

is_activeboolean
limit_typestring
limit_valueinteger
priority_orderinteger
rule_typestring

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the step was created.

estimate_bookobjectrequired

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

idstring (uuid)required

Rule step UUID.

is_activebooleanrequired

Whether this step is active.

limit_typestringrequired

Limit type. One of: none, years, months, weeks, days.

limit_valueintegerrequired

Limit value (e.g., 2 for '2 years').

priority_orderintegerrequired

Execution order (lower runs first).

rule_typestringrequired

Rule type. One of: insurance_plan, group_number, insurance_carrier, insurance_carrier_group, manual_fee_schedule, provider_fee.

updated_atstring (date-time)required

Timestamp of the last update.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/rule-steps/{step_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": null,
    "limit_type": "string",
    "limit_value": 1,
    "priority_order": 1,
    "rule_type": "string"
  }'
patch/api/v1/{org_id}/insurance/fee-schedule-assignments/{assignment_uuid}

Update assignment

Update a fee schedule assignment. The slot fields (location, carrier, plan, kind) are immutable. Re-validates purpose-kind compatibility if fee_schedule_id changes. Re-checks date overlap if effective dates change. Raises 409 if version is stale or dates overlap.

Parameters

Path Parameters
assignment_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

effective_endstring (date)
effective_startstring (date)
estimate_book_uuidstring (uuid)
fee_schedule_uuidstring (uuid)
notesstring

Responses

200Successful Response
assignment_kindstringrequired

Kind of assignment. One of: ucr, primary, copay, out_of_network, allowed, manual_blue_book.

carrierobject

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

created_atstring (date-time)required
effective_endstring (date)
effective_startstring (date)required

Start date of this assignment.

estimate_bookobject

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

fee_scheduleobjectrequired

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

idstring (uuid)required

Assignment UUID.

insurance_planobject

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

locationobjectrequired

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

notesstring
updated_atstring (date-time)required
versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/fee-schedule-assignments/{assignment_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "effective_end": "string",
    "effective_start": "string",
    "estimate_book_uuid": "string",
    "fee_schedule_uuid": "string"
  }'
patch/api/v1/{org_id}/insurance/patients/{patient_uuid}/insurance/{patient_plan_uuid}

Update patient plan

Update mutable fields on a patient plan assignment. Raises 404 if the patient or patient plan does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
patient_uuidstringrequired
patient_plan_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

benefits_last_verified_atstring (date-time)
cob_order_overrideinteger
coverage_typeenum
dentalmedicalvision
eligibility_last_verified_atstring (date-time)
fee_schedule_uuidstring (uuid)
is_pendingboolean
ordinalinteger
pat_id_overridestring
relationship_to_subscriberenum
childotherselfspouse

Responses

200Successful Response
benefits_last_verified_atstring (date-time)
benefits_summaryobject

Plan-level benefit totals. Usage values are zeros until claims tracking is implemented — only the *_total fields carry real data from ``InsuranceBenefit`` rows.

cob_order_overrideinteger
coverage_typeenumrequired

Coverage type. One of: dental, medical, vision.

dentalmedicalvision
created_atstring (date-time)required

Timestamp when the patient plan was created.

deleted_atstring (date-time)
eligibility_last_verified_atstring (date-time)
fee_scheduleobject

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

idstring (uuid)required

Patient plan UUID.

is_pendingboolean

Whether this plan assignment is pending verification.

ordinalintegerrequired

Priority ordinal (1=primary, 2=secondary, 3=tertiary).

pat_id_overridestring
patientobjectrequired

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

relationship_to_subscriberenumrequired

Relationship to subscriber. One of: self, spouse, child, other.

childotherselfspouse
statusenum

Plan status. One of: active, inactive, pending_verification.

activeinactivepending_verification
subscriptionobject

Brief subscription info nested inside PatientPlanOut. ``subscriber`` is non-nullable — ``subscriber_id`` is NOT NULL in the DB and the relationship must be eager-loaded. If the eager-load is missing, Pydantic validation will fail (desired fail-fast behavior).

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/patients/{patient_uuid}/insurance/{patient_plan_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "benefits_last_verified_at": "string",
    "cob_order_override": 1,
    "coverage_type": "string",
    "eligibility_last_verified_at": "string"
  }'
patch/api/v1/{org_id}/insurance/plans/{plan_uuid}

Update insurance plan

Update mutable fields on an existing insurance plan. Returns the updated plan and the count of active subscribers affected. Raises 404 if the plan does not exist. Raises 409 if base_version does not match (optimistic concurrency).

Parameters

Path Parameters
plan_uuidstringrequired
org_idstringrequired

Request Body

assignment_of_benefitsboolean
base_versionintegerrequired

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

benefit_year_start_monthinteger
carrier_uuidstring (uuid)
claim_form_typeenum
ada_2019cms_1500
claims_use_ucrboolean
cob_ruleenum
basiccarve_outsecondary_medicaidstandard
eclaim_send_behaviorenum
do_not_sendsecondary_onlysend
filing_codestring
filing_code_subtypestring
group_namestring
group_numberstring
is_hiddenboolean
is_medicalboolean
is_verification_exemptboolean
ortho_auto_claim_days_waitinteger
ortho_auto_claim_typeenum
initial_onlyinitial_plus_periodicinitial_plus_visitnone
ortho_auto_fee_amtnumber
ortho_auto_proc_codestring
plan_notestring
release_of_informationboolean
show_base_unitsboolean
substitution_code_behaviorenum
customdowngrade_to_amalgamnone

Responses

200Successful Response
planobjectrequired

Full insurance plan output.

subscriber_countintegerrequired

Number of active subscribers affected by this change.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assignment_of_benefits": null,
    "base_version": 1,
    "benefit_year_start_month": 1,
    "carrier_uuid": "string",
    "claim_form_type": "string"
  }'
patch/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits/{benefit_uuid}

Update benefit

Update mutable fields on a benefit rule. Raises 404 if the plan or benefit does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
plan_uuidstringrequired
benefit_uuidstringrequired
org_idstringrequired

Request Body

age_maxinteger
age_mininteger
base_versionintegerrequired

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

benefit_typestring
coverage_category_uuidstring (uuid)
is_deductible_exemptboolean
monetary_amtnumber
percentinteger
procedure_code_uuidstring (uuid)
quantityinteger
quantity_qualifierstring
substitution_code_uuidstring (uuid)
time_periodstring
waiting_period_monthsinteger

Responses

200Successful Response
age_maxinteger
age_mininteger
benefit_typestringrequired

Benefit type. One of: coinsurance, deductible, annual_max, ortho_lifetime_max, exclusion, limitation, waiting_period, copayment, family_deductible, family_annual_max.

coverage_categoryobject

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

created_atstring (date-time)required

Timestamp when the benefit was created.

deleted_atstring (date-time)
idstring (uuid)required

Benefit UUID.

insurance_planobject

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

is_deductible_exemptboolean

Whether exempt from the deductible.

monetary_amtstring
patient_planobject

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

percentinteger
procedure_codeobject

Brief procedure code info embedded in fee entries.

quantityinteger
quantity_qualifierstring
substitution_codeobject

Brief procedure code info embedded in fee entries.

time_periodstring
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Current version for optimistic concurrency.

waiting_period_monthsinteger
422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits/{benefit_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "age_max": 1,
    "age_min": 1,
    "base_version": 1,
    "benefit_type": "string",
    "coverage_category_uuid": "string"
  }'
patch/api/v1/{org_id}/insurance/settings

Update insurance settings

Update organization-level insurance settings. Raises 409 if base_version does not match (optimistic concurrency).

Parameters

Path Parameters
org_idstringrequired

Request Body

allow_fee_exceed_ucrboolean
allow_verification_without_appointmentboolean
auto_calculate_estimatesboolean
auto_flag_unverifiedboolean
base_versionintegerrequired

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

benefits_verify_daysinteger
color_code_proceduresboolean
days_before_appointment_flaginteger
default_benefit_year_typestring
default_cob_rulestring
default_fiscal_year_startinteger
default_insurance_tabstring
eligibility_verify_daysinteger
estimate_display_modestring
include_write_offboolean
show_alerts_on_check_inboolean
show_on_bannerboolean
show_on_treatment_plansboolean
show_remaining_benefitsboolean
write_off_methodstring
writeoff_on_exclusionboolean
writeoff_on_frequency_limitboolean
writeoff_on_max_reachedboolean

Responses

200Successful Response
allow_fee_exceed_ucrbooleanrequired

Whether insurance fees may exceed UCR.

allow_verification_without_appointmentbooleanrequired

Allow verification without appointment.

auto_calculate_estimatesbooleanrequired

Auto-calculate estimates.

auto_flag_unverifiedbooleanrequired

Auto-flag unverified insurance.

base_versionintegerrequired

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

benefits_verify_daysintegerrequired

Days between benefits re-verifications.

color_code_proceduresbooleanrequired

Color-code procedures by category.

created_atstring (date-time)required

Timestamp when settings were created.

days_before_appointment_flagintegerrequired

Days before appointment to flag.

default_benefit_year_typestringrequired

Benefit year type. One of: calendar, fiscal.

default_cob_rulestringrequired

Default COB rule. One of: basic, standard, carve_out, secondary_medicaid.

default_fiscal_year_startintegerrequired

Fiscal year start month (1-12).

default_insurance_tabstringrequired

Default tab. One of: benefits, claims, coverage.

eligibility_verify_daysintegerrequired

Days between eligibility re-verifications.

estimate_display_modestringrequired

How estimates are displayed.

idstring (uuid)required

Settings UUID.

include_write_offbooleanrequired

Include write-offs in estimates.

show_alerts_on_check_inbooleanrequired

Show alerts during check-in.

show_on_bannerbooleanrequired

Show insurance in patient banner.

show_on_treatment_plansbooleanrequired

Show estimates on treatment plans.

show_remaining_benefitsbooleanrequired

Show remaining benefits in banner.

updated_atstring (date-time)required

Timestamp of the last update.

write_off_methodstringrequired

Write-off method. One of: lesser_of_ucr_fee, fee_only, ucr_only.

writeoff_on_exclusionbooleanrequired

Auto write-off on exclusion.

writeoff_on_frequency_limitbooleanrequired

Auto write-off on frequency limit.

writeoff_on_max_reachedbooleanrequired

Auto write-off when annual max reached.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/settings" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_fee_exceed_ucr": null,
    "allow_verification_without_appointment": null,
    "auto_calculate_estimates": null,
    "auto_flag_unverified": null,
    "base_version": 1
  }'
patch/api/v1/{org_id}/insurance/subscriptions/{subscription_uuid}

Update subscription

Update mutable fields on a subscription. Raises 404 if the subscription does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
subscription_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

benefit_notesstring
date_effectivestring (date)
date_termstring (date)
last_verified_atstring (date-time)
last_verified_sourcestring
statusstring
subscriber_id_numberstring
subscriber_notestring

Responses

200Successful Response
benefit_notesstring
carrierobject

Brief carrier reference embedded in plan output.

created_atstring (date-time)required

Timestamp when the subscription was created.

date_effectivestring (date)
date_termstring (date)
deleted_atstring (date-time)
idstring (uuid)required

Subscription UUID.

insurance_planobject

Brief insurance plan reference embedded in subscription output.

last_verified_atstring (date-time)
last_verified_sourcestring
statusstringrequired

Subscription status. One of: active, terminated, pending_verification.

subscriberobjectrequired

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

subscriber_id_numberstringrequired

Subscriber ID number from the carrier.

subscriber_notestring
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/subscriptions/{subscription_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "benefit_notes": "string",
    "date_effective": "string",
    "date_term": "string",
    "last_verified_at": "string"
  }'
patch/api/v1/{org_id}/insurance/verifications/{verification_uuid}

Update verification

Update mutable fields on an existing verification. Raises 404 if the verification does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
verification_uuidstringrequired
org_idstringrequired

Request Body

assigned_to_user_uuidstring (uuid)
base_versionintegerrequired

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

call_duration_minutesinteger
carrier_ref_numberstring
carrier_rep_namestring
next_verification_duestring (date)
notesstring
verification_statusenum
failedpartialunable_to_verifyverified

Responses

200Successful Response
assigned_to_user_uuidstring (uuid)
call_duration_minutesinteger
carrier_ref_numberstring
carrier_rep_namestring
created_atstring (date-time)required

Timestamp when the record was created.

deleted_atstring (date-time)
idstring (uuid)required

Verification UUID.

insurance_plan_uuidstring (uuid)
next_verification_duestring (date)
notesstring
patient_plan_uuidstring (uuid)
raw_response_jsonobject
updated_atstring (date-time)required

Timestamp of the last update.

verification_sourceenumrequired

Source. One of: manual, phone, electronic, fax.

electronicfaxmanualphone
verification_statusenumrequired

Status. One of: verified, failed, partial, unable_to_verify.

failedpartialunable_to_verifyverified
verification_typeenumrequired

Type. One of: eligibility, benefits.

benefitseligibility
verified_atstring (date-time)required

Timestamp when the verification was performed.

verified_by_user_uuidstring (uuid)
versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/verifications/{verification_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assigned_to_user_uuid": "string",
    "base_version": 1,
    "call_duration_minutes": 1,
    "carrier_ref_number": "string",
    "carrier_rep_name": "string"
  }'
delete/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/spans/{span_uuid}

Delete coverage span

Permanently delete a procedure code span. Raises 404 if the category or span does not exist.

Parameters

Path Parameters
category_uuidstringrequired
span_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/insurance/coverage-categories/{category_uuid}/spans/{span_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/allowed-fees/{entry_uuid}

Delete allowed fee

Delete an allowed fee entry. Raises 404 if the estimate book or allowed fee does not exist.

Parameters

Path Parameters
book_uuidstringrequired
entry_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
allowed_feenumberrequired

Computed allowed fee amount.

computed_atstring (date-time)required

When the fee was computed.

confidencestring
created_atstring (date-time)required

Timestamp when the entry was created.

estimate_bookobjectrequired

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

estimate_book_rule_stepobject

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

estimate_book_runobject

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

expires_atstring (date-time)
group_numberstring
idstring (uuid)required

Allowed fee UUID.

procedure_codeobjectrequired

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

resolution_scope_identifierinteger
resolution_scope_typestringrequired

Scope. One of: insurance_plan, group_number, insurance_carrier.

sample_countintegerrequired

Number of evidence entries used.

updated_atstring (date-time)required

Timestamp of the last update.

422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/allowed-fees/{entry_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/rule-steps/{step_uuid}

Delete rule step

Delete a rule step from an estimate book. Raises 404 if the estimate book or rule step does not exist.

Parameters

Path Parameters
book_uuidstringrequired
step_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the step was created.

estimate_bookobjectrequired

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

idstring (uuid)required

Rule step UUID.

is_activebooleanrequired

Whether this step is active.

limit_typestringrequired

Limit type. One of: none, years, months, weeks, days.

limit_valueintegerrequired

Limit value (e.g., 2 for '2 years').

priority_orderintegerrequired

Execution order (lower runs first).

rule_typestringrequired

Rule type. One of: insurance_plan, group_number, insurance_carrier, insurance_carrier_group, manual_fee_schedule, provider_fee.

updated_atstring (date-time)required

Timestamp of the last update.

422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/insurance/estimate-books/{book_uuid}/rule-steps/{step_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/insurance/plans/{plan_uuid}/benefits/{benefit_uuid}

Delete benefit

Permanently delete a benefit rule. Raises 404 if the plan or benefit does not exist.

Parameters

Path Parameters
plan_uuidstringrequired
benefit_uuidstringrequired
org_idstringrequired

Responses

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

Fee Schedules

21 endpoints

get/api/v1/{org_id}/insurance/fee-schedules

List fee schedules

List fee schedules with optional filters. Use ``purpose`` to filter by the fee schedule's purpose category (e.g., ``office`` for UCR schedules, ``insurance`` for plan-specific schedules).

Parameters

Path Parameters
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

statusstring

Filter by status. One of: active, archived.

fee_sched_typestring

Filter by type. One of: normal, copay, out_of_network, fixed_benefit, allowed, manual_blue_book.

purposestring

Filter by purpose. One of: office, insurance, allowed.

searchstring

Text search on name and notes.

Responses

200Successful Response
itemsobject[]required

List of fee schedule records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching fee schedules.

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

Get fee schedule

Retrieve a single fee schedule by UUID. Raises 404 if the fee schedule does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
assignment_countinteger

Number of active assignments using this schedule.

created_atstring (date-time)required

Timestamp when the schedule was created.

deleted_atstring (date-time)
fee_sched_typeenumrequired

Schedule type. One of: normal, copay, out_of_network, fixed_benefit, allowed, manual_blue_book.

allowedcopayfixed_benefitmanual_blue_booknormalout_of_network
idstring (uuid)required

Fee schedule UUID.

namestringrequired

Display name.

notesstring
notes_countinteger

Number of note entries attached to this schedule.

purposeenumrequired

Purpose. One of: office, insurance, allowed.

allowedinsuranceoffice
statusenumrequired

Status. One of: active, archived.

activearchived
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/available-codes

List available codes

List procedure codes not yet in the fee schedule. Use this to populate the 'add code' dialog. Raises 404 if the fee schedule does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired
Query Parameters
searchstring

Search by procedure code or description.

categorystring

Filter by procedure code category.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of available procedure codes.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching codes.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/available-codes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees

List fees in schedule

List fees in a fee schedule with optional search, category filter, fee range, and sort. Raises 404 if the fee schedule does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired
Query Parameters
searchstring

Search by procedure code or description.

categorystring

Filter by procedure code category (e.g., 'Diagnostic').

fee_minnumber

Minimum fee amount (inclusive).

fee_maxnumber

Maximum fee amount (inclusive).

sort_colstring

Sort column. One of: code, description, category, amount.

sort_dirstring

Sort direction. One of: asc, desc.

Default: "asc"

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

List of fee records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching fees.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/history

Fee schedule audit history

Return audit log entries for a specific fee schedule. Shows create, update, archive, copy, and undulation actions, ordered newest-first. Raises 404 if the fee schedule does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired
Query Parameters
limitinteger

Max entries to return.

Default: 20

offsetinteger

Offset for pagination.

Default: 0

Responses

200Successful Response
itemsobject[]required

List of audit entries.

totalintegerrequired

Total number of audit entries.

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

List fee schedule notes

List notes attached to a fee schedule. Raises 404 if the fee schedule does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/notes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/insurance/fee-schedules/stats

Fee schedule stats

Batch stats for all active fee schedules — fee counts and assignment counts. Returns one entry per fee schedule. Designed for lazy-loading alongside the fee schedule list so the main table renders immediately.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
itemsobject[]required

One stats entry per fee schedule.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/stats" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/fee-schedules

Create fee schedule

Create a new fee schedule. The fee_sched_type field is immutable after creation. Raises 409 on idempotency conflict.

Parameters

Path Parameters
org_idstringrequired

Request Body

fee_sched_typeenumrequired

Immutable type for this schedule. One of: normal, copay, out_of_network, fixed_benefit, allowed, manual_blue_book.

allowedcopayfixed_benefitmanual_blue_booknormalout_of_network
namestringrequired

Display name for the fee schedule.

notesstring
purposeenum
allowedinsuranceoffice
statusenum
activearchived

Responses

201Successful Response
assignment_countinteger

Number of active assignments using this schedule.

created_atstring (date-time)required

Timestamp when the schedule was created.

deleted_atstring (date-time)
fee_sched_typeenumrequired

Schedule type. One of: normal, copay, out_of_network, fixed_benefit, allowed, manual_blue_book.

allowedcopayfixed_benefitmanual_blue_booknormalout_of_network
idstring (uuid)required

Fee schedule UUID.

namestringrequired

Display name.

notesstring
notes_countinteger

Number of note entries attached to this schedule.

purposeenumrequired

Purpose. One of: office, insurance, allowed.

allowedinsuranceoffice
statusenumrequired

Status. One of: active, archived.

activearchived
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fee_sched_type": "allowed",
    "name": "string",
    "notes": "string",
    "purpose": "string",
    "status": "string"
  }'
post/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/archive

Archive fee schedule

Soft-delete a fee schedule by setting deleted_at. Raises 404 if the fee schedule does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
assignment_countinteger

Number of active assignments using this schedule.

created_atstring (date-time)required

Timestamp when the schedule was created.

deleted_atstring (date-time)
fee_sched_typeenumrequired

Schedule type. One of: normal, copay, out_of_network, fixed_benefit, allowed, manual_blue_book.

allowedcopayfixed_benefitmanual_blue_booknormalout_of_network
idstring (uuid)required

Fee schedule UUID.

namestringrequired

Display name.

notesstring
notes_countinteger

Number of note entries attached to this schedule.

purposeenumrequired

Purpose. One of: office, insurance, allowed.

allowedinsuranceoffice
statusenumrequired

Status. One of: active, archived.

activearchived
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/copy

Copy fee schedule

Create a copy of a fee schedule with optional percentage adjustment. All fees are copied to the new schedule. Raises 404 if the source schedule does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Request Body

new_namestringrequired

Name for the copied fee schedule.

percentage_adjustmentnumber

Responses

201Successful Response
assignment_countinteger

Number of active assignments using this schedule.

created_atstring (date-time)required

Timestamp when the schedule was created.

deleted_atstring (date-time)
fee_sched_typeenumrequired

Schedule type. One of: normal, copay, out_of_network, fixed_benefit, allowed, manual_blue_book.

allowedcopayfixed_benefitmanual_blue_booknormalout_of_network
idstring (uuid)required

Fee schedule UUID.

namestringrequired

Display name.

notesstring
notes_countinteger

Number of note entries attached to this schedule.

purposeenumrequired

Purpose. One of: office, insurance, allowed.

allowedinsuranceoffice
statusenumrequired

Status. One of: active, archived.

activearchived
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/copy" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_name": "string",
    "percentage_adjustment": null
  }'
post/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees

Create fee

Create a single fee entry in a fee schedule. Raises 404 if the fee schedule or procedure code does not exist. Raises 409 on idempotency conflict.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Request Body

amountnumberrequired
clinic_uuidstring (uuid)
date_effectivestring (date)
patient_amountnumber
procedure_code_uuidstring (uuid)required

UUID of the procedure code.

provider_uuidstring (uuid)

Responses

201Successful Response
amountstringrequired

Fee amount.

clinicobject

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

created_atstring (date-time)required

Timestamp when the fee was created.

date_effectivestring (date)
fee_scheduleobjectrequired

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

idstring (uuid)required

Fee entry UUID.

patient_amountstring
procedure_codeobject

Brief procedure code info embedded in fee entries.

providerobject

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

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": null,
    "clinic_uuid": "string",
    "date_effective": "string",
    "patient_amount": null,
    "procedure_code_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees/bulk

Bulk create fees

Bulk-create fee entries in a fee schedule. Raises 404 if the fee schedule or any procedure code does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Request Body

feesobject[]required

List of fee entries to create.

Responses

201Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fees": []
  }'
post/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees/bulk-update

Bulk update fees

Batch-update fee amounts from inline edits on the fee schedule detail UI. Each item carries the fee UUID, new amount, and base_version for optimistic concurrency. Raises 409 on the first version mismatch. Raises 404 if the fee schedule or any fee does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Request Body

feesobject[]required

List of fee updates (max 500 per request).

Responses

200Successful Response
updatedintegerrequired

Number of fees successfully updated.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees/bulk-update" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fees": []
  }'
post/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/notes

Create fee schedule note

Add a note to a fee schedule. Raises 404 if the fee schedule does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Request Body

authorstring
date_entrystring (date)required

Date the note was entered.

notestringrequired

Note text content.

Responses

201Successful Response
authorstring
created_atstring (date-time)required

Timestamp when the note was created.

date_entrystring (date)required

Date the note was entered.

fee_scheduleobjectrequired

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

idstring (uuid)required

Note UUID.

notestringrequired

Note text content.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/notes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author": "string",
    "date_entry": "2025-01-15",
    "note": "string"
  }'
post/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/resolve

Resolve fee

Resolve the effective fee for a procedure code in a fee schedule. Considers clinic and provider overrides, and effective date. Returns null if no matching fee is found. Raises 404 if the fee schedule or procedure code does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Request Body

as_of_datestring (date)
clinic_uuidstring (uuid)
procedure_code_uuidstring (uuid)required

UUID of the procedure code to resolve.

provider_uuidstring (uuid)

Responses

200Successful Response
amountstringrequired

Fee amount.

clinicobject

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

created_atstring (date-time)required

Timestamp when the fee was created.

date_effectivestring (date)
fee_scheduleobjectrequired

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

idstring (uuid)required

Fee entry UUID.

patient_amountstring
procedure_codeobject

Brief procedure code info embedded in fee entries.

providerobject

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

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/resolve" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "as_of_date": "string",
    "clinic_uuid": "string",
    "procedure_code_uuid": "00000000-0000-0000-0000-000000000000",
    "provider_uuid": "string"
  }'
post/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/undulate

Apply undulation

Apply a percentage increase or decrease to all fees in a schedule. Raises 404 if the fee schedule does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

directionenumrequired

Direction of adjustment. One of: increase, decrease.

decreaseincrease
percentagenumberrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/undulate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "direction": "decrease",
    "percentage": null
  }'
post/api/v1/{org_id}/insurance/fee-schedules/compare

Compare fee schedules

Compare fees across 2-3 fee schedules side by side. Returns a paginated table of procedure codes with fee amounts from each schedule.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Items per page.

Default: 50

Request Body

schedule_uuidsstring (uuid)[]required

UUIDs of fee schedules to compare (2-3 required).

Responses

200Successful Response
pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

rowsobject[]required

Comparison rows, one per procedure code.

schedulesobjectrequired

Map of schedule UUID → schedule metadata.

totalintegerrequired

Total number of procedure codes in the comparison.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/compare" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_uuids": []
  }'
patch/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}

Update fee schedule

Update mutable fields on a fee schedule. Type and purpose cannot be changed while the schedule has active assignments (422). Raises 404 if the fee schedule does not exist. Raises 409 if base_version does not match. Raises 422 if type/purpose change is blocked by active assignments.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

fee_sched_typeenum
allowedcopayfixed_benefitmanual_blue_booknormalout_of_network
namestring
notesstring
purposeenum
allowedinsuranceoffice
statusenum
activearchived

Responses

200Successful Response
assignment_countinteger

Number of active assignments using this schedule.

created_atstring (date-time)required

Timestamp when the schedule was created.

deleted_atstring (date-time)
fee_sched_typeenumrequired

Schedule type. One of: normal, copay, out_of_network, fixed_benefit, allowed, manual_blue_book.

allowedcopayfixed_benefitmanual_blue_booknormalout_of_network
idstring (uuid)required

Fee schedule UUID.

namestringrequired

Display name.

notesstring
notes_countinteger

Number of note entries attached to this schedule.

purposeenumrequired

Purpose. One of: office, insurance, allowed.

allowedinsuranceoffice
statusenumrequired

Status. One of: active, archived.

activearchived
updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "fee_sched_type": "string",
    "name": "string",
    "notes": "string",
    "purpose": "string"
  }'
patch/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees/{fee_uuid}

Update fee

Update a single fee entry. Raises 404 if the fee does not exist. Raises 409 if base_version does not match.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
fee_uuidstringrequired
org_idstringrequired

Request Body

amountnumber
base_versionintegerrequired

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

clinic_uuidstring (uuid)
date_effectivestring (date)
patient_amountnumber
provider_uuidstring (uuid)

Responses

200Successful Response
amountstringrequired

Fee amount.

clinicobject

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

created_atstring (date-time)required

Timestamp when the fee was created.

date_effectivestring (date)
fee_scheduleobjectrequired

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

idstring (uuid)required

Fee entry UUID.

patient_amountstring
procedure_codeobject

Brief procedure code info embedded in fee entries.

providerobject

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

updated_atstring (date-time)required

Timestamp of the last update.

versionintegerrequired

Version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees/{fee_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": null,
    "base_version": 1,
    "clinic_uuid": "string",
    "date_effective": "string",
    "patient_amount": null
  }'
delete/api/v1/{org_id}/insurance/fee-schedules/{fee_schedule_uuid}/fees/{fee_uuid}

Delete fee

Permanently delete a fee entry from a fee schedule. Raises 404 if the fee does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
fee_uuidstringrequired
org_idstringrequired

Responses

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

Delete fee schedule note

Delete a note from a fee schedule. Raises 404 if the note does not exist.

Parameters

Path Parameters
fee_schedule_uuidstringrequired
note_uuidstringrequired
org_idstringrequired

Responses

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