Dental PMS

Scheduling

142 endpoints

Schedule

63 endpoints

get/api/v1/{org_id}/schedule/appointment-rules

List appointment rules

List appointment rules with optional filters. Returns paginated appointment rules. Supports filtering by location and appointment type. Raises 422 if pagination parameters are out of range.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location UUID. Returns org-wide rules when omitted.

appointment_type_uuidstring

Filter by appointment type UUID — matches rules where this type is either side of the pair.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of appointment rule records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get appointment rule

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

Parameters

Path Parameters
rule_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
allow_overlapbooleanrequired

Whether appointments of these two types are allowed to overlap in the schedule.

appointment_type_aobjectrequired

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

appointment_type_bobjectrequired

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

created_atstring (date-time)required

Timestamp when the rule was created.

idstring (uuid)required

Public UUID of the appointment rule.

locationobject

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

updated_atstring (date-time)required

Timestamp of the most recent update.

versionintegerrequired

Current version for optimistic concurrency.

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

Get daily calendar data

Load the full calendar view for a single day at a location. Returns all appointments, blockouts, and resolved provider schedules for the given date. Pass `fields` to include optional Tier 2 appointment fields (e.g., chart_number, mobile_phone, balance_due). Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstringrequired

UUID of the location to load the calendar for.

target_datestringrequired

Calendar date to load (YYYY-MM-DD).

fieldsstring

Comma-separated list of Tier 2 field keys to include (e.g., 'chart_number,mobile_phone').

Responses

200Successful Response
appointmentsobject[]required

All appointments scheduled for this day.

blockoutsobject[]required

All blockouts scheduled for this day.

datestring (date)required
day_hoursintegerrequired

Wall-clock hours in this day (23 on spring-forward, 25 on fall-back, 24 otherwise).

location_timezonestringrequired

IANA timezone identifier for the location (e.g., 'America/Chicago').

provider_schedulesobject[]required

Provider schedule summaries for this day.

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

Get monthly calendar summary

Load aggregate calendar metrics for an entire month. Returns per-day summaries with scheduled/completed production, appointment counts, production goals, and holiday blockout flags. Does NOT return individual appointment details. Raises 404 if the location does not exist. Raises 422 if month format is invalid.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstringrequired

UUID of the location.

monthstringrequired

Month to load in YYYY-MM format (e.g., '2026-03').

Responses

200Successful Response
daysobject[]required

One summary per calendar day in the month.

location_timezonestringrequired

IANA timezone identifier for the location.

monthstringrequired

Month in YYYY-MM format.

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

Get weekly calendar data

Load the full calendar view for a 7-day week at a location. Returns appointments, blockouts, and resolved provider schedules for all 7 days. Pass `fields` to include optional Tier 2 appointment fields (e.g., chart_number, mobile_phone, balance_due). Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstringrequired

UUID of the location to load the calendar for.

week_startstringrequired

First day of the week to load (YYYY-MM-DD, typically a Monday).

fieldsstring

Comma-separated list of Tier 2 field keys to include (e.g., 'chart_number,mobile_phone').

Responses

200Successful Response
daysobject[]required

Daily calendar data for each day in the week (7 entries).

location_timezonestringrequired

IANA timezone identifier for the location (e.g., 'America/Chicago').

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

Get all provider schedules for a date

Resolve all providers' schedules for a location on a given date. Returns time ranges for each provider with a template or override scheduled on that date. Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstringrequired

UUID of the location to look up.

datestringrequired

Date to resolve all provider schedules for (YYYY-MM-DD).

Responses

200Successful Response
datestring (date)required
locationobjectrequired

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

location_timezonestringrequired

IANA timezone identifier for the location (e.g., 'America/Chicago').

providersobject[]required

Resolved schedules for all scheduled providers at this location.

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

List patient flow statuses

List all patient flow status definitions for the organization. Ordered by item_order ascending.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
include_inactiveboolean

When true, includes inactive flow statuses in the results.

Default: true

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of flow status records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

List schedule notes

List per-location per-date schedule notes. Filter by location_uuid and/or a date range. Returns a paginated list ordered by note_date ascending.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location UUID.

date_fromstring

Filter notes on or after this date (inclusive).

date_tostring

Filter notes on or before this date (inclusive).

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

Schedule notes for the requested page.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching schedule notes.

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

Get schedule note

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

Parameters

Path Parameters
note_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the note was created.

idstring (uuid)required

Public UUID of the schedule note.

locationobjectrequired

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

notestringrequired

The note text displayed on the calendar.

note_datestring (date)required

The calendar date this note applies to.

updated_atstring (date-time)required

Timestamp when the note was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

List provider schedule overrides

List provider schedule overrides with optional date-range and entity filtering. Raises 404 if the provider or location does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
provider_uuidstring

Filter by provider UUID.

location_uuidstring

Filter by location UUID.

date_fromstring

Filter to overrides on or after this date (YYYY-MM-DD).

date_tostring

Filter to overrides on or before this date (YYYY-MM-DD).

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of provider schedule override records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get provider schedule override

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

Parameters

Path Parameters
override_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the override was created.

end_timestring (time)
idstring (uuid)required

Public UUID of the provider schedule override.

is_unavailablebooleanrequired

Whether the provider is fully unavailable for this date.

locationobjectrequired

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

notestringrequired

Optional note for this override.

operatoryobject

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

override_datestring (date)required

The specific calendar date being overridden.

override_reasonstringrequired

Reason for the override.

providerobjectrequired

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

start_timestring (time)
updated_atstring (date-time)required

Timestamp when the override was last updated.

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

List patient scheduling preferences

List patient scheduling preferences. Optionally filter by patient_uuid. Returns a paginated list ordered by record ID ascending.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
patient_uuidstring

Filter by patient UUID.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

Patient scheduling preferences for the requested page.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching preferences.

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

Get patient scheduling preference

Get a single patient scheduling preference by UUID. Raises 404 if the preference does not exist.

Parameters

Path Parameters
preference_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the preference was created.

idstring (uuid)required

Public UUID of the patient scheduling preference.

learned_from_historybooleanrequired

Whether this preference was inferred from appointment history rather than entered manually.

notesstringrequired

Free-text notes about scheduling preferences.

patientobjectrequired

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

preferred_contact_methodstring
preferred_daysinteger[]
preferred_operatoryobject

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

preferred_providerobject

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

preferred_time_endstring (time)
preferred_time_startstring (time)
updated_atstring (date-time)required

Timestamp when the preference was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

Get scheduling preference for a patient

Get the scheduling preference record for a specific patient. Returns the preference if it exists, or null if no preference has been set. Raises 404 if the patient does not exist.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the preference was created.

idstring (uuid)required

Public UUID of the patient scheduling preference.

learned_from_historybooleanrequired

Whether this preference was inferred from appointment history rather than entered manually.

notesstringrequired

Free-text notes about scheduling preferences.

patientobjectrequired

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

preferred_contact_methodstring
preferred_daysinteger[]
preferred_operatoryobject

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

preferred_providerobject

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

preferred_time_endstring (time)
preferred_time_startstring (time)
updated_atstring (date-time)required

Timestamp when the preference was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/schedule/patient-preferences/by-patient/{patient_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/schedule/production-goals

List production goals

List production goals with optional filters. Supports filtering by location, provider, and date range. Results are paginated. Raises 422 if pagination parameters are out of range.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location UUID.

provider_uuidstring

Filter by provider UUID.

date_fromstring

Include goals on or after this date (YYYY-MM-DD).

date_tostring

Include goals on or before this date (YYYY-MM-DD).

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of production goal records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get production goal

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

Parameters

Path Parameters
goal_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the record was created.

goal_amountstringrequired

Target production amount in dollars.

goal_datestring (date)required

Calendar date for this production target.

idstring (uuid)required

Public UUID of the production goal.

locationobjectrequired

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

providerobjectrequired

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

updated_atstring (date-time)required

Timestamp of the most recent update.

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

Get production summary

Get aggregated production analytics grouped by provider for a date range. Aggregates appointment production amounts by provider, split into scheduled, completed, and lost (broken + cancelled) buckets. Joins with production goals to compute attainment percentage. Raises 404 if location_uuid is not found. Raises 422 if date_from is after date_to.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstringrequired

UUID of the location to summarize production for.

date_fromstringrequired

Start date of the reporting range (inclusive, YYYY-MM-DD).

date_tostringrequired

End date of the reporting range (inclusive, YYYY-MM-DD).

Responses

200Successful Response
date_fromstring (date)required

Start of the reporting date range (inclusive).

date_tostring (date)required

End of the reporting date range (inclusive).

overall_attainment_pctnumberrequired

Overall completed production as a percentage of total goal (0.0 if no goal set).

providersobject[]required

Per-provider production breakdown.

total_completedstringrequired

Grand total of completed production across all providers.

total_goalstringrequired

Grand total of production goals across all providers.

total_loststringrequired

Grand total of lost production (broken + cancelled) across all providers.

total_scheduledstringrequired

Grand total of scheduled production across all providers.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/schedule/production-goals/production-summary" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/schedule/provider-availability

Get provider availability for a date

Resolve a single provider's schedule for a given date and location. Returns the effective time ranges from either a weekly template or a date-specific override. Raises 404 if the provider or location does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
provider_uuidstringrequired

UUID of the provider to look up.

location_uuidstringrequired

UUID of the location to look up.

datestringrequired

Date to resolve the schedule for (YYYY-MM-DD).

Responses

200Successful Response
datestring (date)required
is_overridebooleanrequired

True if the schedule comes from a date-specific override rather than the weekly template.

location_timezonestringrequired

IANA timezone identifier for the location (e.g., 'America/Chicago').

providerobjectrequired

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

time_rangesobject[]required

Resolved scheduled time ranges for the provider.

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

List saved searches

List saved searches for the current user. Results are automatically scoped to the authenticated user — no user_uuid parameter is accepted. Raises 422 if pagination parameters are out of range.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
search_typestring

Filter by search type (e.g., 'find_free_time').

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of items per page.

Default: 50

Responses

200Successful Response
itemsobject[]required

Saved searches for the requested page.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching saved searches.

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

Get saved search

Retrieve a single saved search by UUID. Only returns the search if it belongs to the authenticated user. Raises 404 if the saved search does not exist or belongs to a different user.

Parameters

Path Parameters
search_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the saved search was created.

criteriaobjectrequired

Search criteria parameters as a JSON object. Keys are user-defined and returned as-is.

idstring (uuid)required

Public UUID of the saved search.

is_defaultbooleanrequired

Whether this is the user's default search for the given search_type.

namestringrequired

Display name of this saved search.

search_typestringrequired

Category of search this criteria applies to (e.g., 'find_free_time').

updated_atstring (date-time)required

Timestamp when the saved search was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

List appointment tags

List all appointment tags, optionally filtered by location and active status. Supports pagination via page and page_size parameters.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location UUID. Returns org-wide and location tags when provided.

is_activeboolean

Filter by active status. Omit to return both active and inactive tags.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of items per page (1–200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of appointment tag records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching tags across all pages.

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

Get appointment tag

Get a single appointment tag by UUID. Raises 404 if the tag does not exist or has been deleted.

Parameters

Path Parameters
tag_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
colorstringrequired

Hex color string for the tag.

created_atstring (date-time)required

Timestamp when the tag was created.

idstring (uuid)required

Public UUID of the tag.

is_activebooleanrequired

Whether the tag is active and available for use.

locationobject

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

namestringrequired

Display name of the tag.

updated_atstring (date-time)required

Timestamp when the tag was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

List provider schedule templates

List provider schedule templates with optional filtering. Raises 404 if the provider or location does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
provider_uuidstring

Filter by provider UUID.

location_uuidstring

Filter by location UUID.

day_of_weekinteger

Filter by day of week (0=Monday, 6=Sunday).

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of provider schedule template records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get provider schedule template

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

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the template was created.

day_of_weekintegerrequired

Day of week this template applies to (0=Monday, 6=Sunday).

effective_fromstring (date)required

Date from which this template is active (inclusive).

effective_tostring (date)
end_timestring (time)required

Scheduled end time for the provider (local time).

idstring (uuid)required

Public UUID of the provider schedule template.

locationobjectrequired

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

notestringrequired

Optional note for this schedule template.

operatoryobject

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

providerobjectrequired

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

start_timestring (time)required

Scheduled start time for the provider (local time).

updated_atstring (date-time)required

Timestamp when the template was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

List schedule views

List saved schedule views for a location. Returns views scoped to the given location, ordered by name. Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location UUID. Returns views for all locations if omitted.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of schedule view records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get schedule view

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

Parameters

Path Parameters
view_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
auto_scroll_to_current_timebooleanrequired

Whether the calendar auto-scrolls to current time on load.

bubble_enabledbooleanrequired

Whether appointment bubbles are enabled in weekly view.

bubble_layoutobject
card_layoutobject
color_configobject
compact_modebooleanrequired

Whether compact appointment block rendering is enabled.

created_atstring (date-time)required

Timestamp when the view was created.

dynamic_op_filteringbooleanrequired

Whether operatories with no scheduled providers are automatically hidden.

end_timestring (time)required

Latest time shown on the calendar.

font_sizestringrequired

Base font size for appointment blocks — one of: xs, sm, md, lg.

idstring (uuid)required

Public UUID of the schedule view.

is_defaultbooleanrequired

Whether this is the current user's default view for the location. Derived from UserViewPreference — not stored on the view itself.

keyboard_shortcutinteger
locationobjectrequired

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

min_operatory_width_pxintegerrequired

Minimum operatory column width in pixels. 0 means no minimum (auto).

namestringrequired

Display name of the schedule view.

operatory_uuidsstring (uuid)[]
privacy_modebooleanrequired

Whether patient names and details are obscured for privacy.

provider_uuidsstring (uuid)[]
show_business_days_onlybooleanrequired

Whether weekend columns are hidden in weekly view.

show_missed_appointmentsbooleanrequired

Whether missed/broken appointment slots are displayed on the schedule.

show_productionbooleanrequired

Whether production amounts are shown on appointment blocks.

show_provider_barsbooleanrequired

Whether provider availability bars are shown.

start_timestring (time)required

Earliest time shown on the calendar.

time_incrementintegerrequired

Time slot increment in minutes.

updated_atstring (date-time)required

Timestamp when the view was last updated.

versionintegerrequired

Current version for optimistic concurrency.

view_typestringrequired

View mode — one of: daily, weekly.

visibilitystringrequired

View visibility — one of: shared, personal.

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

List preset view templates

Return the 6 preset view templates. Templates define default card layouts, bubble sections, and color schemes. Apply a template by copying its card_layout, bubble_layout, and color_config into a view via the create or update endpoint.

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
templatesobject[]required

Available preset view templates.

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

Create appointment rule

Create a new appointment rule for a type pair. Raises 409 if a rule already exists for the (type_a, type_b, location) combination. Raises 404 if the appointment type or location UUID does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

allow_overlapbooleanrequired

Whether appointments of these two types are allowed to overlap in the schedule.

appointment_type_uuid_astring (uuid)required

UUID of the first appointment type in the pair.

appointment_type_uuid_bstring (uuid)required

UUID of the second appointment type in the pair.

location_uuidstring (uuid)

Responses

201Successful Response
allow_overlapbooleanrequired

Whether appointments of these two types are allowed to overlap in the schedule.

appointment_type_aobjectrequired

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

appointment_type_bobjectrequired

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

created_atstring (date-time)required

Timestamp when the rule was created.

idstring (uuid)required

Public UUID of the appointment rule.

locationobject

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

updated_atstring (date-time)required

Timestamp of the most recent update.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/appointment-rules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_overlap": false,
    "appointment_type_uuid_a": "00000000-0000-0000-0000-000000000000",
    "appointment_type_uuid_b": "00000000-0000-0000-0000-000000000000",
    "location_uuid": "string"
  }'
post/api/v1/{org_id}/schedule/flow-statuses

Create patient flow status

Create a new patient flow status definition. Raises 422 if the name is missing or invalid.

Parameters

Path Parameters
org_idstringrequired

Request Body

colorstring
is_activeboolean

Whether this flow status is active and available for use.

item_orderinteger

Display order among flow statuses (ascending).

namestringrequired

Display name for the flow status (e.g., 'Arrived', 'In Chair').

Responses

201Successful Response
colorstringrequired

Hex color string for this status.

created_atstring (date-time)required

Timestamp when the flow status was created.

idstring (uuid)required

Public UUID of the flow status.

is_activebooleanrequired

Whether this flow status is active and available for use.

item_orderintegerrequired

Display order among flow statuses.

namestringrequired

Display name of the flow status.

slugstringrequired

URL-safe identifier derived from the name.

updated_atstring (date-time)required

Timestamp when the flow status was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/flow-statuses" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "string",
    "is_active": true,
    "item_order": 0,
    "name": "string"
  }'
post/api/v1/{org_id}/schedule/notes

Create schedule note

Create a new per-location per-date schedule note. Raises 409 if a note already exists for the same location and date (unique constraint). Raises 422 if required fields are missing or invalid.

Parameters

Path Parameters
org_idstringrequired

Request Body

location_uuidstring (uuid)required

UUID of the location this note belongs to.

notestringrequired

The note text displayed at the top of the calendar for this date.

note_datestring (date)required

The calendar date this note applies to.

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the note was created.

idstring (uuid)required

Public UUID of the schedule note.

locationobjectrequired

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

notestringrequired

The note text displayed on the calendar.

note_datestring (date)required

The calendar date this note applies to.

updated_atstring (date-time)required

Timestamp when the note was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

Create provider schedule override

Create a provider schedule override for a specific date. Raises 404 if the provider, location, or operatory does not exist. Raises 422 if override_reason is not a valid value.

Parameters

Path Parameters
org_idstringrequired

Request Body

end_timestring (time)
is_unavailableboolean

When true, marks the provider as fully unavailable for this date.

location_uuidstring (uuid)required

UUID of the location this override is scoped to.

notestring
operatory_uuidstring (uuid)
override_datestring (date)required

The specific calendar date being overridden (YYYY-MM-DD).

override_reasonstring
provider_uuidstring (uuid)required

UUID of the provider this override applies to.

start_timestring (time)

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the override was created.

end_timestring (time)
idstring (uuid)required

Public UUID of the provider schedule override.

is_unavailablebooleanrequired

Whether the provider is fully unavailable for this date.

locationobjectrequired

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

notestringrequired

Optional note for this override.

operatoryobject

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

override_datestring (date)required

The specific calendar date being overridden.

override_reasonstringrequired

Reason for the override.

providerobjectrequired

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

start_timestring (time)
updated_atstring (date-time)required

Timestamp when the override was last updated.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/overrides" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "end_time": "string",
    "is_unavailable": false,
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "note": "string",
    "operatory_uuid": "string",
    "override_date": "2025-01-15",
    "provider_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/schedule/patient-preferences

Create patient scheduling preference

Create a new scheduling preference record for a patient. Raises 409 if a preference already exists for the same patient (unique constraint). Raises 404 if the patient, provider, or operatory UUID does not resolve. Raises 422 if required fields are missing or invalid.

Parameters

Path Parameters
org_idstringrequired

Request Body

notesstring

Free-text notes about scheduling preferences.

patient_uuidstring (uuid)required

UUID of the patient this preference belongs to.

preferred_contact_methodstring
preferred_daysinteger[]
preferred_operatory_uuidstring (uuid)
preferred_provider_uuidstring (uuid)
preferred_time_endstring (time)
preferred_time_startstring (time)

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the preference was created.

idstring (uuid)required

Public UUID of the patient scheduling preference.

learned_from_historybooleanrequired

Whether this preference was inferred from appointment history rather than entered manually.

notesstringrequired

Free-text notes about scheduling preferences.

patientobjectrequired

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

preferred_contact_methodstring
preferred_daysinteger[]
preferred_operatoryobject

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

preferred_providerobject

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

preferred_time_endstring (time)
preferred_time_startstring (time)
updated_atstring (date-time)required

Timestamp when the preference was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/patient-preferences" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "",
    "patient_uuid": "00000000-0000-0000-0000-000000000000",
    "preferred_contact_method": "string",
    "preferred_days": null,
    "preferred_operatory_uuid": "string"
  }'
post/api/v1/{org_id}/schedule/production-goals

Create production goal

Create a new per-provider daily production goal. Raises 422 if required fields are missing or if a goal already exists for the (provider, location, date) combination — use PUT /upsert instead for idempotent create-or-update.

Parameters

Path Parameters
org_idstringrequired

Request Body

goal_amountnumberrequired
goal_datestring (date)required

Calendar date for this production target (YYYY-MM-DD).

location_uuidstring (uuid)required

UUID of the location this goal is scoped to.

provider_uuidstring (uuid)required

UUID of the provider this goal targets.

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the record was created.

goal_amountstringrequired

Target production amount in dollars.

goal_datestring (date)required

Calendar date for this production target.

idstring (uuid)required

Public UUID of the production goal.

locationobjectrequired

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

providerobjectrequired

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

updated_atstring (date-time)required

Timestamp of the most recent update.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/production-goals" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_amount": null,
    "goal_date": "2025-01-15",
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "provider_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/schedule/saved-searches

Create saved search

Create a new saved search for the current user. The user_id is auto-injected from the authenticated actor — clients cannot specify a different user. If is_default is true, any existing default for the same search_type is unset automatically. Raises 422 if required fields are missing or invalid.

Parameters

Path Parameters
org_idstringrequired

Request Body

criteriaobjectrequired

Search criteria parameters as a JSON object (user-defined keys — e.g., provider UUIDs, appointment types, date range). Keys are preserved as-is.

is_defaultboolean

Whether this is the default search for the user's search_type. Setting to true unsets any existing default for the same search_type.

namestringrequired

Display name for this saved search (max 100 characters).

search_typestring

Category of search this criteria applies to (e.g., 'find_free_time'). Defaults to 'find_free_time'.

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the saved search was created.

criteriaobjectrequired

Search criteria parameters as a JSON object. Keys are user-defined and returned as-is.

idstring (uuid)required

Public UUID of the saved search.

is_defaultbooleanrequired

Whether this is the user's default search for the given search_type.

namestringrequired

Display name of this saved search.

search_typestringrequired

Category of search this criteria applies to (e.g., 'find_free_time').

updated_atstring (date-time)required

Timestamp when the saved search was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/saved-searches" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "criteria": {},
    "is_default": false,
    "name": "string",
    "search_type": "find_free_time"
  }'
post/api/v1/{org_id}/schedule/tags

Create appointment tag

Create a new appointment tag. Raises 409 if a tag with the same name already exists for the given location.

Parameters

Path Parameters
org_idstringrequired

Request Body

colorstring

Hex color string for the tag (e.g. '#FF5733'). Defaults to '#9E9E9E'.

location_uuidstring (uuid)
namestringrequired

Display name of the tag (max 50 characters).

Responses

201Successful Response
colorstringrequired

Hex color string for the tag.

created_atstring (date-time)required

Timestamp when the tag was created.

idstring (uuid)required

Public UUID of the tag.

is_activebooleanrequired

Whether the tag is active and available for use.

locationobject

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

namestringrequired

Display name of the tag.

updated_atstring (date-time)required

Timestamp when the tag was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/tags" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "#9E9E9E",
    "location_uuid": "string",
    "name": "string"
  }'
post/api/v1/{org_id}/schedule/tags/{tag_uuid}/assign

Assign tag to appointment

Assign a tag to an appointment. Raises 404 if the tag or appointment does not exist. Raises 422 if the tag is soft-deleted. Operation is idempotent — safe to call multiple times.

Parameters

Path Parameters
tag_uuidstringrequired
org_idstringrequired

Request Body

appointment_uuidstring (uuid)required

UUID of the appointment to assign the tag to.

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/tags/{tag_uuid}/assign" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/schedule/templates

Create provider schedule template

Create a new provider schedule template. Raises 404 if the provider, location, or operatory does not exist. Raises 422 if day_of_week is not 0–6.

Parameters

Path Parameters
org_idstringrequired

Request Body

day_of_weekintegerrequired

Day of week this template applies to (0=Monday, 6=Sunday).

effective_fromstring (date)required

Date from which this template becomes active (inclusive).

effective_tostring (date)
end_timestring (time)required

Scheduled end time for the provider (local time).

location_uuidstring (uuid)required

UUID of the location this template is scoped to.

notestring
operatory_uuidstring (uuid)
provider_uuidstring (uuid)required

UUID of the provider this template applies to.

start_timestring (time)required

Scheduled start time for the provider (local time).

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the template was created.

day_of_weekintegerrequired

Day of week this template applies to (0=Monday, 6=Sunday).

effective_fromstring (date)required

Date from which this template is active (inclusive).

effective_tostring (date)
end_timestring (time)required

Scheduled end time for the provider (local time).

idstring (uuid)required

Public UUID of the provider schedule template.

locationobjectrequired

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

notestringrequired

Optional note for this schedule template.

operatoryobject

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

providerobjectrequired

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

start_timestring (time)required

Scheduled start time for the provider (local time).

updated_atstring (date-time)required

Timestamp when the template was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/templates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "day_of_week": 0,
    "effective_from": "2025-01-15",
    "effective_to": "string",
    "end_time": "09:00:00",
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "provider_uuid": "00000000-0000-0000-0000-000000000000",
    "start_time": "09:00:00"
  }'
post/api/v1/{org_id}/schedule/views

Create schedule view

Create a new schedule view for a location. Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

auto_scroll_to_current_timeboolean

Whether to auto-scroll the calendar to the current time on load.

bubble_enabledboolean

Whether appointment bubbles are enabled in weekly view.

bubble_layoutobject
card_layoutobject
color_configobject
compact_modeboolean

Whether to use compact (condensed) appointment block rendering.

dynamic_op_filteringboolean

Whether to automatically hide operatories with no scheduled providers.

end_timestring (time)

Latest time shown on the calendar (local time).

font_sizestring

Base font size for appointment blocks — one of: xs, sm, md, lg.

location_uuidstring (uuid)required

UUID of the location this view is scoped to.

min_operatory_width_pxinteger

Minimum operatory column width in pixels. 0 means no minimum (auto).

namestringrequired

Display name for this schedule view.

operatory_uuidsstring (uuid)[]
privacy_modeboolean

Whether to obscure patient names and details for privacy (e.g., public-facing displays).

provider_uuidsstring (uuid)[]
show_business_days_onlyboolean

Whether to hide weekend columns in weekly view.

show_missed_appointmentsboolean

Whether to display missed/broken appointment slots on the schedule.

show_productionboolean

Whether to display production amounts on appointment blocks.

show_provider_barsboolean

Whether to show provider availability bars on the calendar.

start_timestring (time)

Earliest time shown on the calendar (local time).

time_incrementinteger

Time slot increment in minutes (e.g., 10, 15, 20).

view_typestring

View mode — one of: daily, weekly.

visibilitystring

Responses

201Successful Response
auto_scroll_to_current_timebooleanrequired

Whether the calendar auto-scrolls to current time on load.

bubble_enabledbooleanrequired

Whether appointment bubbles are enabled in weekly view.

bubble_layoutobject
card_layoutobject
color_configobject
compact_modebooleanrequired

Whether compact appointment block rendering is enabled.

created_atstring (date-time)required

Timestamp when the view was created.

dynamic_op_filteringbooleanrequired

Whether operatories with no scheduled providers are automatically hidden.

end_timestring (time)required

Latest time shown on the calendar.

font_sizestringrequired

Base font size for appointment blocks — one of: xs, sm, md, lg.

idstring (uuid)required

Public UUID of the schedule view.

is_defaultbooleanrequired

Whether this is the current user's default view for the location. Derived from UserViewPreference — not stored on the view itself.

keyboard_shortcutinteger
locationobjectrequired

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

min_operatory_width_pxintegerrequired

Minimum operatory column width in pixels. 0 means no minimum (auto).

namestringrequired

Display name of the schedule view.

operatory_uuidsstring (uuid)[]
privacy_modebooleanrequired

Whether patient names and details are obscured for privacy.

provider_uuidsstring (uuid)[]
show_business_days_onlybooleanrequired

Whether weekend columns are hidden in weekly view.

show_missed_appointmentsbooleanrequired

Whether missed/broken appointment slots are displayed on the schedule.

show_productionbooleanrequired

Whether production amounts are shown on appointment blocks.

show_provider_barsbooleanrequired

Whether provider availability bars are shown.

start_timestring (time)required

Earliest time shown on the calendar.

time_incrementintegerrequired

Time slot increment in minutes.

updated_atstring (date-time)required

Timestamp when the view was last updated.

versionintegerrequired

Current version for optimistic concurrency.

view_typestringrequired

View mode — one of: daily, weekly.

visibilitystringrequired

View visibility — one of: shared, personal.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/views" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_scroll_to_current_time": true,
    "bubble_enabled": true,
    "bubble_layout": null,
    "card_layout": null,
    "color_config": null,
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "name": "string"
  }'
post/api/v1/{org_id}/schedule/views/{view_uuid}/set-default

Set view as default

Set this view as the default for its user and location. Clears is_default on all other views belonging to the same user at the same location, then sets is_default=true on the target view. Raises 404 if the view does not exist.

Parameters

Path Parameters
view_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
auto_scroll_to_current_timebooleanrequired

Whether the calendar auto-scrolls to current time on load.

bubble_enabledbooleanrequired

Whether appointment bubbles are enabled in weekly view.

bubble_layoutobject
card_layoutobject
color_configobject
compact_modebooleanrequired

Whether compact appointment block rendering is enabled.

created_atstring (date-time)required

Timestamp when the view was created.

dynamic_op_filteringbooleanrequired

Whether operatories with no scheduled providers are automatically hidden.

end_timestring (time)required

Latest time shown on the calendar.

font_sizestringrequired

Base font size for appointment blocks — one of: xs, sm, md, lg.

idstring (uuid)required

Public UUID of the schedule view.

is_defaultbooleanrequired

Whether this is the current user's default view for the location. Derived from UserViewPreference — not stored on the view itself.

keyboard_shortcutinteger
locationobjectrequired

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

min_operatory_width_pxintegerrequired

Minimum operatory column width in pixels. 0 means no minimum (auto).

namestringrequired

Display name of the schedule view.

operatory_uuidsstring (uuid)[]
privacy_modebooleanrequired

Whether patient names and details are obscured for privacy.

provider_uuidsstring (uuid)[]
show_business_days_onlybooleanrequired

Whether weekend columns are hidden in weekly view.

show_missed_appointmentsbooleanrequired

Whether missed/broken appointment slots are displayed on the schedule.

show_productionbooleanrequired

Whether production amounts are shown on appointment blocks.

show_provider_barsbooleanrequired

Whether provider availability bars are shown.

start_timestring (time)required

Earliest time shown on the calendar.

time_incrementintegerrequired

Time slot increment in minutes.

updated_atstring (date-time)required

Timestamp when the view was last updated.

versionintegerrequired

Current version for optimistic concurrency.

view_typestringrequired

View mode — one of: daily, weekly.

visibilitystringrequired

View visibility — one of: shared, personal.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/views/{view_uuid}/set-default" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/schedule/views/{view_uuid}/set-shortcut

Set keyboard shortcut

Assign a keyboard shortcut (Ctrl+1 through Ctrl+9) to this view for the current user. Clears any existing shortcut with the same number for this user at this location. Raises 404 if the view does not exist.

Parameters

Path Parameters
view_uuidstringrequired
org_idstringrequired
Query Parameters
shortcutintegerrequired

Keyboard shortcut number (1-9).

Responses

200Successful Response
auto_scroll_to_current_timebooleanrequired

Whether the calendar auto-scrolls to current time on load.

bubble_enabledbooleanrequired

Whether appointment bubbles are enabled in weekly view.

bubble_layoutobject
card_layoutobject
color_configobject
compact_modebooleanrequired

Whether compact appointment block rendering is enabled.

created_atstring (date-time)required

Timestamp when the view was created.

dynamic_op_filteringbooleanrequired

Whether operatories with no scheduled providers are automatically hidden.

end_timestring (time)required

Latest time shown on the calendar.

font_sizestringrequired

Base font size for appointment blocks — one of: xs, sm, md, lg.

idstring (uuid)required

Public UUID of the schedule view.

is_defaultbooleanrequired

Whether this is the current user's default view for the location. Derived from UserViewPreference — not stored on the view itself.

keyboard_shortcutinteger
locationobjectrequired

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

min_operatory_width_pxintegerrequired

Minimum operatory column width in pixels. 0 means no minimum (auto).

namestringrequired

Display name of the schedule view.

operatory_uuidsstring (uuid)[]
privacy_modebooleanrequired

Whether patient names and details are obscured for privacy.

provider_uuidsstring (uuid)[]
show_business_days_onlybooleanrequired

Whether weekend columns are hidden in weekly view.

show_missed_appointmentsbooleanrequired

Whether missed/broken appointment slots are displayed on the schedule.

show_productionbooleanrequired

Whether production amounts are shown on appointment blocks.

show_provider_barsbooleanrequired

Whether provider availability bars are shown.

start_timestring (time)required

Earliest time shown on the calendar.

time_incrementintegerrequired

Time slot increment in minutes.

updated_atstring (date-time)required

Timestamp when the view was last updated.

versionintegerrequired

Current version for optimistic concurrency.

view_typestringrequired

View mode — one of: daily, weekly.

visibilitystringrequired

View visibility — one of: shared, personal.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/schedule/views/{view_uuid}/set-shortcut" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
put/api/v1/{org_id}/schedule/patient-preferences/by-patient/{patient_uuid}

Upsert scheduling preference for a patient

Create or update the scheduling preference for a patient. If no preference exists for the patient, a new one is created. If a preference already exists, base_version is required for optimistic concurrency. Raises 404 if the patient, provider, or operatory UUID does not resolve. Raises 409 if a preference already exists and base_version is stale. Raises 422 if base_version is omitted when updating an existing preference.

Parameters

Path Parameters
patient_uuidstringrequired
org_idstringrequired

Request Body

base_versioninteger
learned_from_historyboolean

Whether this preference was inferred from appointment history rather than entered manually.

notesstring

Free-text notes about scheduling preferences.

preferred_contact_methodstring
preferred_daysinteger[]
preferred_operatory_uuidstring (uuid)
preferred_provider_uuidstring (uuid)
preferred_time_endstring (time)
preferred_time_startstring (time)

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the preference was created.

idstring (uuid)required

Public UUID of the patient scheduling preference.

learned_from_historybooleanrequired

Whether this preference was inferred from appointment history rather than entered manually.

notesstringrequired

Free-text notes about scheduling preferences.

patientobjectrequired

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

preferred_contact_methodstring
preferred_daysinteger[]
preferred_operatoryobject

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

preferred_providerobject

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

preferred_time_endstring (time)
preferred_time_startstring (time)
updated_atstring (date-time)required

Timestamp when the preference was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PUT "https://api.example.com/api/v1/{org_id}/schedule/patient-preferences/by-patient/{patient_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "learned_from_history": false,
    "notes": "",
    "preferred_contact_method": "string",
    "preferred_days": null
  }'
put/api/v1/{org_id}/schedule/production-goals/upsert

Upsert production goal

Create or update a production goal by (provider, location, date). If a goal already exists for the given provider + location + date, updates the goal_amount. Otherwise creates a new record. This is the preferred endpoint for bulk calendar imports. Raises 404 if the provider or location UUID does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

goal_amountnumberrequired
goal_datestring (date)required

Calendar date for this production target (YYYY-MM-DD).

location_uuidstring (uuid)required

UUID of the location this goal is scoped to.

provider_uuidstring (uuid)required

UUID of the provider this goal targets.

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the record was created.

goal_amountstringrequired

Target production amount in dollars.

goal_datestring (date)required

Calendar date for this production target.

idstring (uuid)required

Public UUID of the production goal.

locationobjectrequired

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

providerobjectrequired

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

updated_atstring (date-time)required

Timestamp of the most recent update.

422Validation Error
detailobject[]
curl
curl -X PUT "https://api.example.com/api/v1/{org_id}/schedule/production-goals/upsert" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_amount": null,
    "goal_date": "2025-01-15",
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "provider_uuid": "00000000-0000-0000-0000-000000000000"
  }'
patch/api/v1/{org_id}/schedule/appointment-rules/{rule_uuid}

Update appointment rule

Update the allow_overlap field of an existing appointment rule. The appointment_type pair and location are immutable after creation. Raises 404 if the appointment rule does not exist. Raises 409 if base_version does not match the current version (optimistic concurrency).

Parameters

Path Parameters
rule_uuidstringrequired
org_idstringrequired

Request Body

allow_overlapbooleanrequired

Whether appointments of these two types are allowed to overlap in the schedule.

base_versionintegerrequired

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

Responses

200Successful Response
allow_overlapbooleanrequired

Whether appointments of these two types are allowed to overlap in the schedule.

appointment_type_aobjectrequired

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

appointment_type_bobjectrequired

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

created_atstring (date-time)required

Timestamp when the rule was created.

idstring (uuid)required

Public UUID of the appointment rule.

locationobject

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

updated_atstring (date-time)required

Timestamp of the most recent update.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/appointment-rules/{rule_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_overlap": false,
    "base_version": 1
  }'
patch/api/v1/{org_id}/schedule/flow-statuses/{flow_status_uuid}

Update patient flow status

Update a patient flow status definition. Raises 404 if the flow status does not exist. Raises 409 if base_version is stale.

Parameters

Path Parameters
flow_status_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

colorstring
is_activeboolean
item_orderinteger
namestring

Responses

200Successful Response
colorstringrequired

Hex color string for this status.

created_atstring (date-time)required

Timestamp when the flow status was created.

idstring (uuid)required

Public UUID of the flow status.

is_activebooleanrequired

Whether this flow status is active and available for use.

item_orderintegerrequired

Display order among flow statuses.

namestringrequired

Display name of the flow status.

slugstringrequired

URL-safe identifier derived from the name.

updated_atstring (date-time)required

Timestamp when the flow status was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/flow-statuses/{flow_status_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "color": "string",
    "is_active": null,
    "item_order": 1,
    "name": "string"
  }'
patch/api/v1/{org_id}/schedule/notes/{note_uuid}

Update schedule note

Update a schedule note. Only the `note` field is mutable. Requires `base_version` for optimistic concurrency. Raises 404 if the note does not exist. Raises 409 if `base_version` is stale.

Parameters

Path Parameters
note_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

notestring

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the note was created.

idstring (uuid)required

Public UUID of the schedule note.

locationobjectrequired

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

notestringrequired

The note text displayed on the calendar.

note_datestring (date)required

The calendar date this note applies to.

updated_atstring (date-time)required

Timestamp when the note was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/notes/{note_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "note": "string"
  }'
patch/api/v1/{org_id}/schedule/overrides/{override_uuid}

Update provider schedule override

Update a provider schedule override. Raises 404 if the override or operatory does not exist. Raises 422 if override_reason is not a valid value.

Parameters

Path Parameters
override_uuidstringrequired
org_idstringrequired

Request Body

end_timestring (time)
is_unavailableboolean
notestring
operatory_uuidstring (uuid)
override_reasonstring
start_timestring (time)

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the override was created.

end_timestring (time)
idstring (uuid)required

Public UUID of the provider schedule override.

is_unavailablebooleanrequired

Whether the provider is fully unavailable for this date.

locationobjectrequired

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

notestringrequired

Optional note for this override.

operatoryobject

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

override_datestring (date)required

The specific calendar date being overridden.

override_reasonstringrequired

Reason for the override.

providerobjectrequired

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

start_timestring (time)
updated_atstring (date-time)required

Timestamp when the override was last updated.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/overrides/{override_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "end_time": "string",
    "is_unavailable": null,
    "note": "string",
    "operatory_uuid": "string",
    "override_reason": "string"
  }'
patch/api/v1/{org_id}/schedule/patient-preferences/{preference_uuid}

Update patient scheduling preference

Update a patient scheduling preference. Requires base_version for optimistic concurrency. Raises 404 if the preference does not exist. Raises 409 if base_version is stale. Raises 422 if validation fails. The patient_id field is immutable and cannot be changed via update.

Parameters

Path Parameters
preference_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

learned_from_historyboolean
notesstring
preferred_contact_methodstring
preferred_daysinteger[]
preferred_operatory_uuidstring (uuid)
preferred_provider_uuidstring (uuid)
preferred_time_endstring (time)
preferred_time_startstring (time)

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the preference was created.

idstring (uuid)required

Public UUID of the patient scheduling preference.

learned_from_historybooleanrequired

Whether this preference was inferred from appointment history rather than entered manually.

notesstringrequired

Free-text notes about scheduling preferences.

patientobjectrequired

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

preferred_contact_methodstring
preferred_daysinteger[]
preferred_operatoryobject

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

preferred_providerobject

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

preferred_time_endstring (time)
preferred_time_startstring (time)
updated_atstring (date-time)required

Timestamp when the preference was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/patient-preferences/{preference_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "learned_from_history": null,
    "notes": "string",
    "preferred_contact_method": "string",
    "preferred_days": null
  }'
patch/api/v1/{org_id}/schedule/production-goals/{goal_uuid}

Update production goal

Update the goal_amount of an existing production goal. Raises 404 if the production goal does not exist.

Parameters

Path Parameters
goal_uuidstringrequired
org_idstringrequired

Request Body

goal_amountnumberrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the record was created.

goal_amountstringrequired

Target production amount in dollars.

goal_datestring (date)required

Calendar date for this production target.

idstring (uuid)required

Public UUID of the production goal.

locationobjectrequired

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

providerobjectrequired

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

updated_atstring (date-time)required

Timestamp of the most recent update.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/production-goals/{goal_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_amount": null
  }'
patch/api/v1/{org_id}/schedule/saved-searches/{search_uuid}

Update saved search

Update a saved search. Requires base_version for optimistic concurrency. If is_default is set to true, the previous default for the same user + search_type is unset. Only updates the search if it belongs to the authenticated user. Raises 404 if the saved search does not exist or belongs to a different user. Raises 409 if base_version is stale. Raises 422 if required fields are missing or invalid.

Parameters

Path Parameters
search_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

criteriaobject
is_defaultboolean
namestring
search_typestring

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the saved search was created.

criteriaobjectrequired

Search criteria parameters as a JSON object. Keys are user-defined and returned as-is.

idstring (uuid)required

Public UUID of the saved search.

is_defaultbooleanrequired

Whether this is the user's default search for the given search_type.

namestringrequired

Display name of this saved search.

search_typestringrequired

Category of search this criteria applies to (e.g., 'find_free_time').

updated_atstring (date-time)required

Timestamp when the saved search was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/saved-searches/{search_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "criteria": null,
    "is_default": null,
    "name": "string",
    "search_type": "string"
  }'
patch/api/v1/{org_id}/schedule/tags/{tag_uuid}

Update appointment tag

Update an existing appointment tag. Raises 404 if the tag does not exist. Raises 409 if base_version is stale (version mismatch). Raises 409 if the new name conflicts with an existing tag at the same location.

Parameters

Path Parameters
tag_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

colorstring
is_activeboolean
namestring

Responses

200Successful Response
colorstringrequired

Hex color string for the tag.

created_atstring (date-time)required

Timestamp when the tag was created.

idstring (uuid)required

Public UUID of the tag.

is_activebooleanrequired

Whether the tag is active and available for use.

locationobject

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

namestringrequired

Display name of the tag.

updated_atstring (date-time)required

Timestamp when the tag was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/tags/{tag_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "color": "string",
    "is_active": null,
    "name": "string"
  }'
patch/api/v1/{org_id}/schedule/templates/{template_uuid}

Update provider schedule template

Update a provider schedule template. Raises 404 if the template or operatory does not exist. Raises 409 if base_version is stale.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

day_of_weekinteger
effective_fromstring (date)
effective_tostring (date)
end_timestring (time)
notestring
operatory_uuidstring (uuid)
start_timestring (time)

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the template was created.

day_of_weekintegerrequired

Day of week this template applies to (0=Monday, 6=Sunday).

effective_fromstring (date)required

Date from which this template is active (inclusive).

effective_tostring (date)
end_timestring (time)required

Scheduled end time for the provider (local time).

idstring (uuid)required

Public UUID of the provider schedule template.

locationobjectrequired

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

notestringrequired

Optional note for this schedule template.

operatoryobject

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

providerobjectrequired

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

start_timestring (time)required

Scheduled start time for the provider (local time).

updated_atstring (date-time)required

Timestamp when the template was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/templates/{template_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "day_of_week": 1,
    "effective_from": "string",
    "effective_to": "string",
    "end_time": "string"
  }'
patch/api/v1/{org_id}/schedule/views/{view_uuid}

Update schedule view

Update a schedule view's configuration. Raises 404 if the view does not exist. Raises 409 if base_version is stale.

Parameters

Path Parameters
view_uuidstringrequired
org_idstringrequired

Request Body

auto_scroll_to_current_timeboolean
base_versionintegerrequired

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

bubble_enabledboolean
bubble_layoutobject
card_layoutobject
color_configobject
compact_modeboolean
dynamic_op_filteringboolean
end_timestring (time)
font_sizestring
min_operatory_width_pxinteger
namestring
operatory_uuidsstring (uuid)[]
privacy_modeboolean
provider_uuidsstring (uuid)[]
show_business_days_onlyboolean
show_missed_appointmentsboolean
show_productionboolean
show_provider_barsboolean
start_timestring (time)
time_incrementinteger
view_typestring
visibilitystring

Responses

200Successful Response
auto_scroll_to_current_timebooleanrequired

Whether the calendar auto-scrolls to current time on load.

bubble_enabledbooleanrequired

Whether appointment bubbles are enabled in weekly view.

bubble_layoutobject
card_layoutobject
color_configobject
compact_modebooleanrequired

Whether compact appointment block rendering is enabled.

created_atstring (date-time)required

Timestamp when the view was created.

dynamic_op_filteringbooleanrequired

Whether operatories with no scheduled providers are automatically hidden.

end_timestring (time)required

Latest time shown on the calendar.

font_sizestringrequired

Base font size for appointment blocks — one of: xs, sm, md, lg.

idstring (uuid)required

Public UUID of the schedule view.

is_defaultbooleanrequired

Whether this is the current user's default view for the location. Derived from UserViewPreference — not stored on the view itself.

keyboard_shortcutinteger
locationobjectrequired

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

min_operatory_width_pxintegerrequired

Minimum operatory column width in pixels. 0 means no minimum (auto).

namestringrequired

Display name of the schedule view.

operatory_uuidsstring (uuid)[]
privacy_modebooleanrequired

Whether patient names and details are obscured for privacy.

provider_uuidsstring (uuid)[]
show_business_days_onlybooleanrequired

Whether weekend columns are hidden in weekly view.

show_missed_appointmentsbooleanrequired

Whether missed/broken appointment slots are displayed on the schedule.

show_productionbooleanrequired

Whether production amounts are shown on appointment blocks.

show_provider_barsbooleanrequired

Whether provider availability bars are shown.

start_timestring (time)required

Earliest time shown on the calendar.

time_incrementintegerrequired

Time slot increment in minutes.

updated_atstring (date-time)required

Timestamp when the view was last updated.

versionintegerrequired

Current version for optimistic concurrency.

view_typestringrequired

View mode — one of: daily, weekly.

visibilitystringrequired

View visibility — one of: shared, personal.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/schedule/views/{view_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_scroll_to_current_time": null,
    "base_version": 1,
    "bubble_enabled": null,
    "bubble_layout": null,
    "card_layout": null
  }'
delete/api/v1/{org_id}/schedule/appointment-rules/{rule_uuid}

Delete appointment rule

Permanently delete an appointment rule. This is a hard delete — the record is removed from the database. Raises 404 if the appointment rule does not exist.

Parameters

Path Parameters
rule_uuidstringrequired
org_idstringrequired

Responses

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

Delete patient flow status

Delete a patient flow status definition. This is irreversible. Raises 404 if the flow status does not exist.

Parameters

Path Parameters
flow_status_uuidstringrequired
org_idstringrequired

Responses

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

Delete schedule note

Hard-delete a schedule note. This action is irreversible. Raises 404 if the note does not exist.

Parameters

Path Parameters
note_uuidstringrequired
org_idstringrequired

Responses

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

Delete provider schedule override

Delete a provider schedule override. This is irreversible. Raises 404 if the override does not exist.

Parameters

Path Parameters
override_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/schedule/overrides/{override_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/schedule/patient-preferences/{preference_uuid}

Delete patient scheduling preference

Hard-delete a patient scheduling preference. This action is irreversible. Raises 404 if the preference does not exist.

Parameters

Path Parameters
preference_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/schedule/patient-preferences/{preference_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/schedule/production-goals/{goal_uuid}

Delete production goal

Permanently delete a production goal. This is a hard delete — the record is removed from the database. Raises 404 if the production goal does not exist.

Parameters

Path Parameters
goal_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/schedule/production-goals/{goal_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/schedule/saved-searches/{search_uuid}

Delete saved search

Hard-delete a saved search. This action is irreversible. Raises 404 if the saved search does not exist.

Parameters

Path Parameters
search_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/schedule/saved-searches/{search_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/schedule/tags/{tag_uuid}

Delete appointment tag

Soft-delete an appointment tag. Raises 404 if the tag does not exist. The tag is not hard-deleted — existing assignment records are preserved.

Parameters

Path Parameters
tag_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/schedule/tags/{tag_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/schedule/tags/{tag_uuid}/assign/{appointment_uuid}

Unassign tag from appointment

Remove a tag from an appointment. Raises 404 if the tag does not exist. If the assignment does not exist, the operation is a no-op.

Parameters

Path Parameters
tag_uuidstringrequired
appointment_uuidstringrequired
org_idstringrequired

Responses

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

Delete provider schedule template

Delete a provider schedule template. This is irreversible. Raises 404 if the template does not exist.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

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

Delete schedule view

Delete a schedule view. This is irreversible. Raises 404 if the view does not exist.

Parameters

Path Parameters
view_uuidstringrequired
org_idstringrequired

Responses

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

Appointments

29 endpoints

get/api/v1/{org_id}/appointments

List appointments

List appointments with optional filters. Returns a paginated list of appointments. Raises 404 if location_uuid or patient_uuid is not found. Date filters are expanded to local-day boundaries when no time component is provided and a location is specified.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter appointments to this location UUID.

patient_uuidstring

Filter appointments to this patient UUID.

statusstring

Filter by appointment status. Accepts a single value or comma-separated list (e.g., 'scheduled,complete').

date_fromstring

Return appointments starting at or after this datetime. When a date-only value is given, expands to the start of that day in the location's local timezone.

date_tostring

Return appointments starting before or at this datetime. When a date-only value is given, expands to the end of that day in the location's local timezone.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of appointments to return per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of appointment records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of appointments matching the query filters.

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

Get appointment

Retrieve a single appointment by UUID. Staff callers (Cognito JWT) get the full ``AppointmentOut`` shape, with location-scoped permission enforcement. Raises 404 if the appointment is not found.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

List appointment history

List the change history for an appointment in reverse chronological order. Returns paginated audit trail entries showing status transitions, moves, and field updates. Raises 404 if the appointment is not found.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of history entries to return per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of history records for the appointment.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of history entries for the appointment.

422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/history" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/appointments/{appointment_uuid}/patient-flow-events

List patient flow events

List all patient flow events for an appointment in chronological order. Returns a paginated timeline of flow status transitions (e.g., arrived, in_chair, checkout). Raises 404 if the appointment is not found.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of flow events to return per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of patient flow event records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get patient flow stats

Get patient flow duration statistics for an appointment. Returns time spent in each flow status segment and aggregate totals. Raises 404 if the appointment is not found.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired
Query Parameters
include_openboolean

When true, includes the currently open (in-progress) flow segment in duration calculations.

Default: true

Responses

200Successful Response
appointment_uuidstring (uuid)required

Public UUID of the appointment these stats belong to.

current_flow_statusobject

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

segmentsobject[]required

Ordered list of flow status segments.

totalsobject[]required

Aggregated time totals per flow status.

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

List appointment procedures

List all procedures linked to an appointment ordered by item_order. Raises 404 if the appointment is not found.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/procedures" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/appointments/{appointment_uuid}/providers

List appointment providers

List all providers assigned to an appointment with their roles and scheduled time ranges. Raises 404 if the appointment is not found.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/providers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/appointments/confirmation-statuses

List appointment confirmation statuses

List confirmation-status values configured for the practice. These are the legal target values for ``PATCH /appointments/{id}/confirmation-status``. Reference data — low cardinality, stable. Staff callers receive the full ``DefinitionListOut`` shape (same as ``GET /definitions?category=ApptConfirmed``).

Parameters

Path Parameters
org_idstringrequired

Responses

200Successful Response
itemsobject[]required
pageintegerrequired
page_sizeintegerrequired
totalintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/appointments/confirmation-statuses" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/appointments/counts/by-location

Count appointments by location

Return location-level appointment counts without exposing appointment rows.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
date_fromstringrequired

Inclusive local start date, YYYY-MM-DD.

date_tostringrequired

Exclusive local end date, YYYY-MM-DD.

status_setstring[]

Appointment statuses to include. Repeat the query param for multiple values. Defaults to scheduled when omitted by Agent-MS.

Responses

200Successful Response
date_fromstring (date)required

Inclusive local start date used for every location.

date_tostring (date)required

Exclusive local end date used for every location.

group_bystring

Aggregate grouping dimension.

itemsobject[]required

One count item per active location.

status_setstring[]required

Appointment statuses included in the count.

totalintegerrequired

Sum of all location counts in this response.

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

List appointments (cursor-paginated)

List appointments with cursor-based pagination and optional filters. Returns a cursor-paginated list of appointments. Use the ``after`` parameter with the ``end_cursor`` value from the previous response to fetch the next page. This endpoint uses keyset pagination for stable, performant traversal of large result sets. Error conditions: - 404: Referenced location, patient, operatory, or provider not found. - 422: Invalid or malformed cursor value.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
firstinteger

Maximum number of records to return per page.

Default: 50

afterstring

Opaque cursor from a previous page_info.end_cursor.

sort_by"created_at" | "start_time" | "status" | "updated_at"

Sort field. One of: start_time, created_at, updated_at, status. Defaults to start_time when not specified.

sort_dir"asc" | "desc"

Sort direction. One of: asc, desc.

ascdesc

Default: "asc"

statusstring

Filter by appointment status (e.g. 'scheduled', 'complete').

location_uuidstring

Filter by location UUID.

patient_uuidstring

Filter by patient UUID.

operatory_uuidstring

Filter by operatory UUID.

provider_uuidstring

Filter by provider UUID (appointments with this provider assigned).

date_fromstring

Filter appointments starting at or after this UTC datetime.

date_tostring

Filter appointments starting before this UTC datetime.

Responses

200Successful Response
dataobject[]required

Page of records.

org_uuidstring (uuid)required

Organisation that owns these appointment records.

page_infoobjectrequired

Pagination metadata.

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

List pinboard appointments

List all pinboard (unscheduled) appointments for a location. Returns appointments that have been moved to the pinboard and are awaiting placement on the schedule. Raises 404 if location_uuid is not found.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstringrequired

UUID of the location whose pinboard appointments to list.

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/appointments/pinboard" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/appointments/procedure-frequency-check

Check procedure frequency

Check when a procedure was last performed for a patient. Returns the most recent completion date and days since for the given procedure code. Useful for frequency validation before scheduling. Raises 404 if patient_uuid is not found or the procedure code does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
patient_uuidstringrequired

UUID of the patient to check procedure history for.

procedure_codestringrequired

CDT procedure code to look up (e.g., 'D0120').

Responses

200Successful Response
days_sinceinteger
last_performed_datestring (date)
procedure_codestringrequired

CDT procedure code that was checked (e.g., 'D0120').

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

Create appointment

Create a new appointment for a patient at a location. Staff callers send the full ``CreateAppointmentIn`` payload and receive ``AppointmentOut``. Raises 404 if any referenced UUID (patient, location, operatory, appointment_type) is not found. Raises 409 if another appointment occupies the same operatory time slot and allow_overlap is false. Raises 422 if required fields are missing or status is invalid.

Parameters

Path Parameters
org_idstringrequired

Request Body

allow_overlapboolean

When true, bypasses operatory conflict detection and permits overlapping appointments.

appointment_type_uuidstring (uuid)
ask_to_arrive_timestring (time)
color_overridestring
end_timestring (time)
is_new_patientboolean

Whether this appointment is for a new patient visit.

location_uuidstring (uuid)required

UUID of the location where the appointment will take place. References the Location entity.

notestring
operatory_uuidstring (uuid)
patient_uuidstring (uuid)required

UUID of the patient being scheduled. References the Patient entity.

priorityinteger

Scheduling priority; higher values indicate higher priority.

schedule_datestring (date)
start_timestring (time)
statusstring

Initial appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

Responses

201Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_overlap": false,
    "appointment_type_uuid": "string",
    "ask_to_arrive_time": "string",
    "color_override": "string",
    "end_time": "string",
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "patient_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/appointments/{appointment_uuid}/break

Break appointment

Mark an appointment as broken (patient missed without prior notice). Raises 404 if the appointment or broken_reason_uuid is not found. Raises 409 if base_version is stale.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

broken_reason_uuidstring (uuid)
notestring

Responses

200Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/break" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "broken_reason_uuid": "string",
    "note": "string"
  }'
post/api/v1/{org_id}/appointments/{appointment_uuid}/cancel

Cancel appointment

Cancel an appointment with an optional reason and note. Raises 404 if the appointment or cancel_reason_uuid is not found. Raises 409 if base_version is stale.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

cancel_reason_uuidstring (uuid)
cancelled_byenum
patientpractice
notestring

Responses

200Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/cancel" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "cancel_reason_uuid": "string",
    "cancelled_by": "string",
    "note": "string"
  }'
post/api/v1/{org_id}/appointments/{appointment_uuid}/move

Move appointment

Move (reschedule) an appointment to a new date, time, and optionally a different operatory. Raises 404 if the appointment or operatory UUID is not found. Raises 409 if base_version is stale or the target time slot has a conflict and allow_overlap is false. Raises 422 if the time falls in a DST gap.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

allow_overlapboolean

When true, bypasses operatory conflict detection and permits overlapping appointments.

base_versionintegerrequired

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

end_timestring (time)required

New local wall-clock end time for the appointment.

notestring
operatory_uuidstring (uuid)
schedule_datestring (date)required

New local calendar date for the appointment (YYYY-MM-DD).

start_timestring (time)required

New local wall-clock start time for the appointment.

Responses

200Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/move" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_overlap": false,
    "base_version": 1,
    "end_time": "09:00:00",
    "note": "string",
    "operatory_uuid": "string",
    "schedule_date": "2025-01-15",
    "start_time": "09:00:00"
  }'
post/api/v1/{org_id}/appointments/{appointment_uuid}/patient-flow-status

Set patient flow status

Set the current patient flow status for an appointment, creating an audit event. Raises 404 if the appointment or flow_status_uuid is not found. Raises 422 if the appointment is not in a state that allows flow status updates.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

change_notestring
flow_status_uuidstring (uuid)required

UUID of the flow status to assign to the appointment.

Responses

200Successful Response
change_notestringrequired

Optional note attached to this flow status change.

changed_atstring (date-time)required

Timestamp when the flow status changed.

changed_bystring
flow_statusobject

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

idstring (uuid)required

Public UUID of the flow event.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/patient-flow-status" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "change_note": "string",
    "flow_status_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/appointments/{appointment_uuid}/pinboard

Send appointment to pinboard

Move a scheduled appointment to the pinboard without cancelling it. The appointment retains all details and procedures but is removed from the calendar grid. Raises 404 if the appointment is not found. Raises 409 if base_version is stale.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

notestring

Responses

200Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/pinboard" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "note": "string"
  }'
post/api/v1/{org_id}/appointments/{appointment_uuid}/place

Place appointment from pinboard

Place a pinboard appointment back onto the schedule at the specified time and operatory. Raises 404 if the appointment or operatory_uuid is not found. Raises 409 if base_version is stale or the target time slot has a conflict and allow_overlap is false. Raises 422 if the time falls in a DST gap.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

allow_overlapboolean

When true, bypasses operatory conflict detection and permits overlapping appointments.

base_versionintegerrequired

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

end_timestring (time)required

Local wall-clock end time for the placed appointment.

operatory_uuidstring (uuid)required

UUID of the operatory to assign when placing the appointment. References the Operatory entity.

schedule_datestring (date)required

Local calendar date on which to place the appointment (YYYY-MM-DD).

start_timestring (time)required

Local wall-clock start time for the placed appointment.

Responses

200Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/place" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_overlap": false,
    "base_version": 1,
    "end_time": "09:00:00",
    "operatory_uuid": "00000000-0000-0000-0000-000000000000",
    "schedule_date": "2025-01-15",
    "start_time": "09:00:00"
  }'
post/api/v1/{org_id}/appointments/{appointment_uuid}/procedures

Add procedure to appointment

Add a procedure to an appointment. Raises 404 if the appointment, procedure_code_uuid, or provider_uuid is not found. Raises 409 if base_version is stale. Raises 422 if the appointment is in a state that does not allow adding procedures.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

Current version of the parent appointment for optimistic concurrency — rejected with 409 if stale.

charted_procedure_uuidstring (uuid)
feenumber
item_orderinteger

Display order of this procedure within the appointment's procedure list.

procedure_code_uuidstring (uuid)required

UUID of the procedure code to link. References the ProcedureCode entity.

provider_uuidstring (uuid)

Responses

201Successful Response
appointmentobjectrequired

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

charted_procedure_uuidstring (uuid)
created_atstring (date-time)required

UTC timestamp when this procedure record was created.

feestringrequired

Fee amount charged for this procedure.

idstring (uuid)required

Public UUID of the appointment procedure record.

item_orderintegerrequired

Display order of this procedure within the appointment.

procedure_codeobjectrequired

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

procedure_code_descriptionstring

Short description of the procedure code.

procedure_code_valuestring

ADA procedure code string (e.g., 'D0120').

providerobject

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

statusstringrequired

Current status of this procedure (e.g., planned, completed).

updated_atstring (date-time)required

UTC timestamp when this procedure record was last updated.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/procedures" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "charted_procedure_uuid": "string",
    "fee": "0",
    "item_order": 0,
    "procedure_code_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/appointments/{appointment_uuid}/transition

Transition appointment status

Transition an appointment to a new status following the allowed status state machine. Staff body (``TransitionStatusIn``) accepts ``auto_generate_claim`` — an internal billing toggle. Valid statuses: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard. Raises 404 if the appointment is not found. Raises 409 if base_version is stale or the transition is not permitted from the current status. Raises 422 if the target status value is invalid.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

auto_generate_claimboolean
base_versionintegerrequired

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

statusstringrequired

Target status to transition to. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

Responses

200Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/transition" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_generate_claim": null,
    "base_version": 1,
    "status": "string"
  }'
post/api/v1/{org_id}/appointments/bulk

Bulk import appointments

Bulk import multiple appointments in a single request (max 500 rows). Each row is processed independently; failures are reported per-row without aborting the batch. Raises 422 if any row fails schema validation.

Parameters

Path Parameters
org_idstringrequired

Request Body

metaobject

Top-level execution options for a bulk request.

rowsobject[]required

Responses

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

Bulk confirm appointments

Bulk-confirm multiple appointments with a single confirmation status. Not-found UUIDs are collected in 'skipped' instead of failing the batch. Version conflicts are collected in 'conflicts'. Raises 404 if confirmation_status_uuid is not found.

Parameters

Path Parameters
org_idstringrequired

Request Body

appointment_uuidsstring (uuid)[]required

List of appointment UUIDs to confirm in bulk.

confirmation_status_uuidstring (uuid)required

UUID of the confirmation status definition to apply to all listed appointments. References the Definition entity.

Responses

200Successful Response
confirmedobject[]required

Appointments that were successfully confirmed.

conflictsstring[]

UUIDs of appointments that had version conflicts and were not updated.

skippedstring[]

UUIDs of appointments that were not found and skipped.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/bulk-confirm" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_uuids": [],
    "confirmation_status_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/appointments/check-conflicts

Check scheduling conflicts

Preview scheduling conflicts for a proposed appointment time. Returns list of conflicting appointments and blockouts without making any changes. Useful for inline form validation before creating or moving an appointment. Raises 404 if location_uuid or operatory_uuid is not found. Raises 422 if the proposed time falls in a DST gap.

Parameters

Path Parameters
org_idstringrequired

Request Body

end_timestring (time)required

Local wall-clock end time (HH:MM) for the proposed appointment.

exclude_appointment_uuidstring (uuid)
location_uuidstring (uuid)required

UUID of the location to check conflicts in. References the Location entity.

operatory_uuidstring (uuid)required

UUID of the operatory to check for conflicts. References the Operatory entity.

schedule_datestring (date)required

Local calendar date of the proposed appointment (YYYY-MM-DD).

start_timestring (time)required

Local wall-clock start time (HH:MM) for the proposed appointment.

Responses

200Successful Response
conflictsobject

Conflict details grouped by type: appointments, providers, blockouts.

has_conflictsbooleanrequired

Whether any scheduling conflicts were detected for the proposed time.

reason_codesstring[]

List of conflict reason codes. One of: APPOINTMENT_OVERLAP, PROVIDER_OVERLAP, BLOCKED_TIME_CONFLICT.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointments/check-conflicts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "end_time": "09:00:00",
    "exclude_appointment_uuid": "string",
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "operatory_uuid": "00000000-0000-0000-0000-000000000000",
    "schedule_date": "2025-01-15",
    "start_time": "09:00:00"
  }'
put/api/v1/{org_id}/appointments/{appointment_uuid}/providers

Replace appointment providers

Replace all provider assignments on an appointment with a new set. Existing assignments are deleted and replaced atomically. Raises 404 if the appointment or any provider_uuid is not found. Raises 409 if base_version is stale. Raises 422 if a time falls in a DST gap.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

providersobject[]required

Complete list of provider assignments to set; existing assignments are deleted and replaced.

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X PUT "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/providers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "providers": []
  }'
patch/api/v1/{org_id}/appointments/{appointment_uuid}

Update appointment

Update appointment details such as operatory, type, time, notes, and financial estimates. Raises 404 if the appointment or any referenced UUID is not found. Raises 409 if base_version is stale. Raises 422 if a field value is invalid.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

appointment_type_uuidstring (uuid)
ask_to_arrive_timestring (time)
base_versionintegerrequired

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

color_overridestring
end_timestring (time)
estimated_insurancenumber
estimated_patient_portionnumber
is_time_lockedboolean
notestring
operatory_uuidstring (uuid)
priorityinteger
production_amountnumber
schedule_datestring (date)
start_timestring (time)

Responses

200Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_type_uuid": "string",
    "ask_to_arrive_time": "string",
    "base_version": 1,
    "color_override": "string",
    "end_time": "string"
  }'
patch/api/v1/{org_id}/appointments/{appointment_uuid}/confirmation-status

Update confirmation status

Update the confirmation-status (outreach workflow) of an appointment. Distinct from the appointment **lifecycle** status (scheduled → complete / broken / cancelled / unscheduled) — confirmation tracks the front-desk outreach progress: ``Unconfirmed``, ``Not Called``, ``Left Message``, ``Current``, ``Confirmed``. Practices configure their own set; discoverable via ``GET /api/v1/{org_id}/appointments/confirmation-statuses``. Staff callers send the full ``UpdateConfirmationStatusIn`` (with ``confirmation_status_uuid``), carrying ``base_version`` for optimistic concurrency. Raises 404 if the appointment or confirmation status is not found. Raises 409 if base_version is stale.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

confirmation_status_uuidstring (uuid)

Responses

200Successful Response
appointment_typeobject

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

broken_reasonobject

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

cancel_reasonobject

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

cancelled_bystring
color_overridestring
confirmation_statusobject

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

confirmation_status_labelstring
created_atstring (date-time)required

UTC timestamp when this appointment was created.

datetime_ask_to_arrivestring (date-time)
end_timestring (date-time)
estimated_insurancestring
estimated_patient_portionstring
flow_statusobject

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

idstring (uuid)required

Public UUID of the appointment.

is_new_patientbooleanrequired

Whether this appointment is for a new patient visit.

is_time_lockedbooleanrequired

When true, the appointment time is locked and cannot be automatically adjusted.

item_orderintegerrequired

Display order of this appointment within its time slot.

locationobjectrequired

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

location_timezonestring

IANA timezone identifier for the appointment's location (e.g., 'America/New_York').

notestringrequired

Free-text note or instructions for this appointment.

operatoryobject

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

patientobjectrequired

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

priorityintegerrequired

Scheduling priority; higher values indicate higher priority.

production_amountstringrequired

Total expected production amount for this appointment.

providerobject

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

providersobject[]

References to all assigned providers (id + name), ordered by appointment provider item_order.

recallobject

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

start_timestring (date-time)
statusstringrequired

Current appointment status. One of: planned, scheduled, complete, broken, cancelled, unscheduled, pinboard.

tagsobject[]

Appointment tags assigned to this appointment.

updated_atstring (date-time)required

UTC timestamp when this appointment was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/appointments/{appointment_uuid}/confirmation-status" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "confirmation_status_uuid": "string"
  }'
delete/api/v1/{org_id}/appointments/{appointment_uuid}

Delete appointment

Permanently delete an appointment. This action is irreversible. Prefer the cancel or break endpoints for normal clinical workflows. Raises 404 if the appointment is not found.

Parameters

Path Parameters
appointment_uuidstringrequired
org_idstringrequired

Responses

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

Remove procedure from appointment

Remove a procedure from an appointment. This action is irreversible. Raises 404 if the appointment or procedure is not found. Raises 409 if base_version is stale. Raises 422 if the appointment is in a state that does not allow removing procedures.

Parameters

Path Parameters
appointment_uuidstringrequired
procedure_uuidstringrequired
org_idstringrequired
Query Parameters
base_versionintegerrequired

Current version of the parent appointment for optimistic concurrency — rejected with 409 if stale.

Responses

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

Appointment Types

5 endpoints

get/api/v1/{org_id}/appointment-types

List appointment types

List appointment types defined by this practice. Staff callers receive the full ``AppointmentTypeListOut`` shape.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
pageinteger

Default: 1

page_sizeinteger

Default: 50

statusstring
searchstring

Responses

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

Get appointment type

Retrieve a single appointment type by UUID. Staff callers receive the full ``AppointmentTypeOut`` shape.

Parameters

Path Parameters
appointment_type_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
abbrevstring
blockout_onlyboolean
colorstring
created_atstring (date-time)required
deleted_atstring (date-time)
duration_minutesinteger
effective_time_patternstring
idstring (uuid)required
is_hiddenboolean
item_orderinteger
locationsobject[]
namestringrequired
procedure_codes_to_addstring[]
require_allboolean
required_procedure_codesstring[]
statusstring
time_patternstring
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/appointment-types/{appointment_type_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/appointment-types

Create Appointment Type

Parameters

Path Parameters
org_idstringrequired

Request Body

abbrevstring
blockout_onlyboolean
colorstring
duration_minutesinteger
is_hiddenboolean
item_orderinteger
location_uuidsstring (uuid)[]
namestringrequired
procedure_codes_to_addstring[]
require_allboolean
required_procedure_codesstring[]
time_patternstring

Responses

201Successful Response
abbrevstring
blockout_onlyboolean
colorstring
created_atstring (date-time)required
deleted_atstring (date-time)
duration_minutesinteger
effective_time_patternstring
idstring (uuid)required
is_hiddenboolean
item_orderinteger
locationsobject[]
namestringrequired
procedure_codes_to_addstring[]
require_allboolean
required_procedure_codesstring[]
statusstring
time_patternstring
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointment-types" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "abbrev": "",
    "blockout_only": false,
    "color": "#42A5F5",
    "duration_minutes": 30,
    "is_hidden": false,
    "name": "string"
  }'
post/api/v1/{org_id}/appointment-types/{appointment_type_uuid}/archive

Archive Appointment Type

Parameters

Path Parameters
appointment_type_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
abbrevstring
blockout_onlyboolean
colorstring
created_atstring (date-time)required
deleted_atstring (date-time)
duration_minutesinteger
effective_time_patternstring
idstring (uuid)required
is_hiddenboolean
item_orderinteger
locationsobject[]
namestringrequired
procedure_codes_to_addstring[]
require_allboolean
required_procedure_codesstring[]
statusstring
time_patternstring
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/appointment-types/{appointment_type_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
patch/api/v1/{org_id}/appointment-types/{appointment_type_uuid}

Update Appointment Type

Parameters

Path Parameters
appointment_type_uuidstringrequired
org_idstringrequired

Request Body

abbrevstring
base_versionintegerrequired
blockout_onlyboolean
colorstring
duration_minutesinteger
is_hiddenboolean
item_orderinteger
location_uuidsstring (uuid)[]
namestring
procedure_codes_to_addstring[]
require_allboolean
required_procedure_codesstring[]
time_patternstring

Responses

200Successful Response
abbrevstring
blockout_onlyboolean
colorstring
created_atstring (date-time)required
deleted_atstring (date-time)
duration_minutesinteger
effective_time_patternstring
idstring (uuid)required
is_hiddenboolean
item_orderinteger
locationsobject[]
namestringrequired
procedure_codes_to_addstring[]
require_allboolean
required_procedure_codesstring[]
statusstring
time_patternstring
updated_atstring (date-time)required
versionintegerrequired
422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/appointment-types/{appointment_type_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "abbrev": "string",
    "base_version": 1,
    "blockout_only": null,
    "color": "string",
    "duration_minutes": 1
  }'

Blockouts

22 endpoints

get/api/v1/{org_id}/blockouts/instances

List blockouts

List blockout instances with optional date-range and location filtering. Staff callers receive the full ``BlockoutListOut`` shape. Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location UUID.

date_fromstring

Filter to blockouts on or after this date (YYYY-MM-DD).

date_tostring

Filter to blockouts on or before this date (YYYY-MM-DD).

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of blockout records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get blockout

Retrieve a single blockout instance by UUID. Staff callers receive the full ``BlockoutOut`` shape with per-actor location enforcement. Raises 404 if the blockout does not exist.

Parameters

Path Parameters
blockout_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
blockout_group_uuidstring (uuid)
blockout_typeobjectrequired

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

created_atstring (date-time)required

Timestamp when the blockout was created.

end_timestring (time)required

Local end time of the blockout.

idstring (uuid)required

Public UUID of the blockout.

locationobjectrequired

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

notestringrequired

Note attached to the blockout (empty string if none).

operatoryobject

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

schedule_datestring (date)required

Date of the blockout (YYYY-MM-DD).

start_timestring (time)required

Local start time of the blockout.

statusstringrequired

Current status of the blockout — one of: active, cancelled.

updated_atstring (date-time)required

Timestamp when the blockout was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

List block schedule templates

List block schedule templates with optional filtering. Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location UUID. Returns org-wide templates when omitted.

include_hiddenboolean

When true, includes hidden templates in the results.

Default: false

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of block schedule template records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get block schedule template

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

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the template was created.

day_of_weekinteger
descriptionstringrequired

Optional description of the template.

idstring (uuid)required

Public UUID of the block schedule template.

is_hiddenbooleanrequired

Whether this template is hidden from the UI.

item_orderintegerrequired

Display order among templates.

locationobject

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

namestringrequired

Display name of the template.

statusstringrequired

Current status — one of: active, inactive.

updated_atstring (date-time)required

Timestamp when the template was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

List block schedule template items

List all time slot items within a block schedule template. Raises 404 if the template does not exist.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

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

List blockout types

List all blockout type definitions for the organization. Ordered by item_order ascending.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
include_hiddenboolean

When true, includes hidden blockout types in the results.

Default: false

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of blockout type records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get blockout type

Retrieve a single blockout type definition by UUID. Raises 404 if the blockout type does not exist.

Parameters

Path Parameters
blockout_type_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
abbreviationstring
colorstringrequired

Hex color string for this blockout type.

created_atstring (date-time)required

Timestamp when the blockout type was created.

idstring (uuid)required

Public UUID of the blockout type.

is_do_not_copybooleanrequired

Whether this blockout is excluded from copy operations.

is_hiddenbooleanrequired

Whether this blockout type is hidden from the UI.

is_no_schedulebooleanrequired

Whether no appointments may be scheduled during this blockout.

item_orderintegerrequired

Display order among blockout types.

namestringrequired

Display name of the blockout type.

statusstringrequired

Current status — one of: active, inactive.

updated_atstring (date-time)required

Timestamp when the blockout type was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

Create blockout

Create one or more blockout instances for a date and location. If operatory_uuids is provided, creates one blockout per operatory. Raises 404 if the location, blockout type, or any operatory does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

blockout_type_uuidstring (uuid)required

UUID of the blockout type to apply.

end_timestring (time)required

Local end time of the blockout.

location_uuidstring (uuid)required

UUID of the location where the blockout applies.

notestring
operatory_uuidsstring (uuid)[]
schedule_datestring (date)required

Date of the blockout (YYYY-MM-DD).

start_timestring (time)required

Local start time of the blockout.

Responses

201Successful Response
itemsobject[]required

List of created blockout instances.

warningsstring[]

Any non-fatal warnings encountered during creation (e.g., overlap skipped).

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/blockouts/instances" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "blockout_type_uuid": "00000000-0000-0000-0000-000000000000",
    "end_time": "09:00:00",
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "note": "string",
    "operatory_uuids": null,
    "schedule_date": "2025-01-15",
    "start_time": "09:00:00"
  }'
post/api/v1/{org_id}/blockouts/instances/copy-day

Copy blockouts for a day

Copy all non-do-not-copy blockouts from one day to another. Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

location_uuidstring (uuid)required

UUID of the location whose blockouts are being copied.

source_datestring (date)required

The date to copy blockouts from (YYYY-MM-DD).

target_datestring (date)required

The date to copy blockouts to (YYYY-MM-DD).

Responses

200Successful Response
countintegerrequired

Number of blockout instances created.

warningsstring[]

Any non-fatal warnings encountered during the operation.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/blockouts/instances/copy-day" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "source_date": "2025-01-15",
    "target_date": "2025-01-15"
  }'
post/api/v1/{org_id}/blockouts/instances/copy-week

Copy blockouts for a week

Copy all non-do-not-copy blockouts from one week to another. Both source_week_start and target_week_start should be Mondays. Returns count and warnings for skipped dates (holidays). Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

location_uuidstring (uuid)required

UUID of the location whose blockouts are being copied.

source_week_startstring (date)required

Monday of the source week (YYYY-MM-DD).

target_week_startstring (date)required

Monday of the target week (YYYY-MM-DD).

Responses

200Successful Response
countintegerrequired

Number of blockout instances created.

warningsstring[]

Any non-fatal warnings encountered during the operation.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/blockouts/instances/copy-week" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "source_week_start": "2025-01-15",
    "target_week_start": "2025-01-15"
  }'
post/api/v1/{org_id}/blockouts/instances/repeat-weeks

Repeat blockout week pattern

Repeat a weekly blockout pattern for num_weeks subsequent weeks. Returns count and warnings for skipped dates (holidays). Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

location_uuidstring (uuid)required

UUID of the location whose blockout pattern is being repeated.

num_weeksintegerrequired

Number of subsequent weeks to apply the pattern to (1-52).

source_week_startstring (date)required

Monday of the source week to repeat (YYYY-MM-DD).

Responses

200Successful Response
countintegerrequired

Number of blockout instances created.

warningsstring[]

Any non-fatal warnings encountered during the operation.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/blockouts/instances/repeat-weeks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "num_weeks": 1,
    "source_week_start": "2025-01-15"
  }'
post/api/v1/{org_id}/blockouts/templates

Create block schedule template

Create a new block schedule template. Raises 404 if the location does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

day_of_weekinteger
descriptionstring
is_hiddenboolean

Whether this template is hidden from the UI.

item_orderinteger

Display order among templates (ascending).

location_uuidstring (uuid)
namestringrequired

Display name for this template.

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the template was created.

day_of_weekinteger
descriptionstringrequired

Optional description of the template.

idstring (uuid)required

Public UUID of the block schedule template.

is_hiddenbooleanrequired

Whether this template is hidden from the UI.

item_orderintegerrequired

Display order among templates.

locationobject

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

namestringrequired

Display name of the template.

statusstringrequired

Current status — one of: active, inactive.

updated_atstring (date-time)required

Timestamp when the template was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/blockouts/templates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "day_of_week": 1,
    "description": "string",
    "is_hidden": false,
    "item_order": 0,
    "location_uuid": "string",
    "name": "string"
  }'
post/api/v1/{org_id}/blockouts/templates/{template_uuid}/apply

Apply block schedule template to a date

Apply a block schedule template to a specific date. Creates blockout instances for each item in the template at the given location and date. Raises 404 if the template or location does not exist.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Request Body

location_uuidstring (uuid)required

UUID of the location to apply the template to.

target_datestring (date)required

The date to apply the template to (YYYY-MM-DD).

Responses

200Successful Response
countintegerrequired

Number of blockout instances created.

warningsstring[]

Any non-fatal warnings encountered during the operation.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/blockouts/templates/{template_uuid}/apply" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "target_date": "2025-01-15"
  }'
post/api/v1/{org_id}/blockouts/templates/{template_uuid}/items

Add item to block schedule template

Add a new time slot item to a block schedule template. Raises 404 if the template, blockout type, or operatory does not exist.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Request Body

blockout_type_uuidstring (uuid)required

UUID of the blockout type for this item.

end_timestring (time)required

Local end time of this blockout item.

item_orderinteger

Display order of this item within the template (ascending).

operatory_uuidstring (uuid)
start_timestring (time)required

Local start time of this blockout item.

Responses

201Successful Response
blockout_typeobjectrequired

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

end_timestring (time)required

Local end time of this blockout item.

idstring (uuid)required

Public UUID of the template item.

item_orderintegerrequired

Display order within the template.

operatoryobject

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

start_timestring (time)required

Local start time of this blockout item.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/blockouts/templates/{template_uuid}/items" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "blockout_type_uuid": "00000000-0000-0000-0000-000000000000",
    "end_time": "09:00:00",
    "item_order": 0,
    "operatory_uuid": "string",
    "start_time": "09:00:00"
  }'
post/api/v1/{org_id}/blockouts/types

Create blockout type

Create a new blockout type definition. Raises 422 if required fields are missing or invalid.

Parameters

Path Parameters
org_idstringrequired

Request Body

abbreviationstring
colorstring
is_do_not_copyboolean

When true, this blockout is excluded from copy-day/copy-week operations.

is_hiddenboolean

When true, this blockout type is hidden from the UI.

is_no_scheduleboolean

When true, no appointments may be scheduled during this blockout.

item_orderinteger

Display order among blockout types (ascending).

namestringrequired

Display name for this blockout type (e.g., 'Lunch', 'Staff Meeting').

Responses

201Successful Response
abbreviationstring
colorstringrequired

Hex color string for this blockout type.

created_atstring (date-time)required

Timestamp when the blockout type was created.

idstring (uuid)required

Public UUID of the blockout type.

is_do_not_copybooleanrequired

Whether this blockout is excluded from copy operations.

is_hiddenbooleanrequired

Whether this blockout type is hidden from the UI.

is_no_schedulebooleanrequired

Whether no appointments may be scheduled during this blockout.

item_orderintegerrequired

Display order among blockout types.

namestringrequired

Display name of the blockout type.

statusstringrequired

Current status — one of: active, inactive.

updated_atstring (date-time)required

Timestamp when the blockout type was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/blockouts/types" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "abbreviation": "string",
    "color": "string",
    "is_do_not_copy": false,
    "is_hidden": false,
    "is_no_schedule": false,
    "name": "string"
  }'
patch/api/v1/{org_id}/blockouts/instances/{blockout_uuid}

Update blockout

Update a blockout instance. Set apply_to_group=true to propagate changes to all blockouts in the same recurrence group. Raises 404 if the blockout, blockout type, or operatory does not exist. Raises 409 if base_version is stale.

Parameters

Path Parameters
blockout_uuidstringrequired
org_idstringrequired

Request Body

allow_overlapboolean

When true, skips overlap validation for this update.

apply_to_groupboolean

When true, applies this update to all blockouts in the same recurrence group.

base_versionintegerrequired

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

blockout_type_uuidstring (uuid)
end_timestring (time)
notestring
operatory_uuidstring (uuid)
schedule_datestring (date)
start_timestring (time)

Responses

200Successful Response
blockout_group_uuidstring (uuid)
blockout_typeobjectrequired

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

created_atstring (date-time)required

Timestamp when the blockout was created.

end_timestring (time)required

Local end time of the blockout.

idstring (uuid)required

Public UUID of the blockout.

locationobjectrequired

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

notestringrequired

Note attached to the blockout (empty string if none).

operatoryobject

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

schedule_datestring (date)required

Date of the blockout (YYYY-MM-DD).

start_timestring (time)required

Local start time of the blockout.

statusstringrequired

Current status of the blockout — one of: active, cancelled.

updated_atstring (date-time)required

Timestamp when the blockout was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/blockouts/instances/{blockout_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_overlap": false,
    "apply_to_group": false,
    "base_version": 1,
    "blockout_type_uuid": "string",
    "end_time": "string"
  }'
patch/api/v1/{org_id}/blockouts/templates/{template_uuid}

Update block schedule template

Update a block schedule template. Raises 404 if the template or location does not exist. Raises 409 if base_version is stale.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

day_of_weekinteger
descriptionstring
is_hiddenboolean
item_orderinteger
location_uuidstring (uuid)
namestring
statusstring

Responses

200Successful Response
created_atstring (date-time)required

Timestamp when the template was created.

day_of_weekinteger
descriptionstringrequired

Optional description of the template.

idstring (uuid)required

Public UUID of the block schedule template.

is_hiddenbooleanrequired

Whether this template is hidden from the UI.

item_orderintegerrequired

Display order among templates.

locationobject

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

namestringrequired

Display name of the template.

statusstringrequired

Current status — one of: active, inactive.

updated_atstring (date-time)required

Timestamp when the template was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/blockouts/templates/{template_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "day_of_week": 1,
    "description": "string",
    "is_hidden": null,
    "item_order": 1
  }'
patch/api/v1/{org_id}/blockouts/types/{blockout_type_uuid}

Update blockout type

Update a blockout type definition. Raises 404 if the blockout type does not exist. Raises 409 if base_version is stale.

Parameters

Path Parameters
blockout_type_uuidstringrequired
org_idstringrequired

Request Body

abbreviationstring
base_versionintegerrequired

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

colorstring
is_do_not_copyboolean
is_hiddenboolean
is_no_scheduleboolean
item_orderinteger
namestring
statusstring

Responses

200Successful Response
abbreviationstring
colorstringrequired

Hex color string for this blockout type.

created_atstring (date-time)required

Timestamp when the blockout type was created.

idstring (uuid)required

Public UUID of the blockout type.

is_do_not_copybooleanrequired

Whether this blockout is excluded from copy operations.

is_hiddenbooleanrequired

Whether this blockout type is hidden from the UI.

is_no_schedulebooleanrequired

Whether no appointments may be scheduled during this blockout.

item_orderintegerrequired

Display order among blockout types.

namestringrequired

Display name of the blockout type.

statusstringrequired

Current status — one of: active, inactive.

updated_atstring (date-time)required

Timestamp when the blockout type was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/blockouts/types/{blockout_type_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "abbreviation": "string",
    "base_version": 1,
    "color": "string",
    "is_do_not_copy": null,
    "is_hidden": null
  }'
delete/api/v1/{org_id}/blockouts/instances/{blockout_uuid}

Delete blockout

Delete a single blockout instance. This is irreversible. Only deletes the targeted instance — other blockouts in the same recurrence group are unaffected. Raises 404 if the blockout does not exist.

Parameters

Path Parameters
blockout_uuidstringrequired
org_idstringrequired

Responses

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

Delete block schedule template

Delete a block schedule template and all its items. This is irreversible. Existing blockouts previously created from this template are not affected. Raises 404 if the template does not exist.

Parameters

Path Parameters
template_uuidstringrequired
org_idstringrequired

Responses

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

Remove item from block schedule template

Remove a time slot item from a block schedule template. This action is irreversible. Raises 404 if the template or item does not exist.

Parameters

Path Parameters
template_uuidstringrequired
item_uuidstringrequired
org_idstringrequired

Responses

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

Delete blockout type

Delete a blockout type definition. This is irreversible. Raises 404 if the blockout type does not exist.

Parameters

Path Parameters
blockout_type_uuidstringrequired
org_idstringrequired

Responses

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

Recalls

13 endpoints

get/api/v1/{org_id}/recalls/patient-recalls

List patient recalls

List patient recall records with optional filtering. Raises 404 if the patient or recall type does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
patient_uuidstring

Filter by patient UUID.

recall_type_uuidstring

Filter by recall type UUID.

statusstring

Filter by recall status (e.g., 'due', 'scheduled', 'completed', 'overdue').

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of patient recall records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get patient recall

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

Parameters

Path Parameters
recall_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
appointmentobject

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

created_atstring (date-time)required

Timestamp when the recall was created.

date_duestring (date)
date_previousstring (date)
date_scheduledstring (date)
idstring (uuid)required

Public UUID of the patient recall.

intervalobjectrequired

Recall interval for this patient (e.g., {'months': 6}).

is_disabledbooleanrequired

Whether this recall is disabled.

notestringrequired

Optional note about this patient recall.

patientobjectrequired

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

patient_phonestring
recall_typeobjectrequired

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

statusstringrequired

Current recall status — one of: due, scheduled, completed, overdue.

updated_atstring (date-time)required

Timestamp when the recall was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

List due patient recalls

List patient recalls that are past their due date and not yet completed. Ordered by date_due ascending (most overdue first).

Parameters

Path Parameters
org_idstringrequired
Query Parameters
pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

due_onstring

Return recalls due on or before this date. Defaults to today.

Responses

200Successful Response
itemsobject[]required

Page of due patient recall records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

List recall triggers

List all recall triggers for a given recall type. Raises 404 if the recall type does not exist.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
recall_type_uuidstringrequired

UUID of the recall type to list triggers for.

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/recalls/triggers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
get/api/v1/{org_id}/recalls/types

List recall types

List recall type definitions for the organization. Ordered by item_order ascending.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
is_activeboolean

Filter by active status. Returns all recall types when omitted.

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of results per page (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

Page of recall type records.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of items per page.

totalintegerrequired

Total number of matching records.

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

Get recall type

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

Parameters

Path Parameters
recall_type_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
appointment_typeobject

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

created_atstring (date-time)required

Timestamp when the recall type was created.

default_intervalobjectrequired

Default recall interval as a duration dict (e.g., {'months': 6}).

descriptionstringrequired

Description of this recall type.

idstring (uuid)required

Public UUID of the recall type.

is_activebooleanrequired

Whether this recall type is active.

item_orderintegerrequired

Display order among recall types.

namestringrequired

Display name of the recall type.

updated_atstring (date-time)required

Timestamp when the recall type was last updated.

versionintegerrequired

Current version for optimistic concurrency.

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

Create patient recall

Create a new patient recall record. Raises 404 if the patient or recall type does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

date_duestring (date)
intervalobject

Recall interval for this patient (e.g., {'months': 6}). Overrides the recall type's default_interval.

notestring

Optional note about this patient recall.

patient_uuidstring (uuid)required

UUID of the patient this recall belongs to.

recall_type_uuidstring (uuid)required

UUID of the recall type to apply.

Responses

201Successful Response
appointmentobject

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

created_atstring (date-time)required

Timestamp when the recall was created.

date_duestring (date)
date_previousstring (date)
date_scheduledstring (date)
idstring (uuid)required

Public UUID of the patient recall.

intervalobjectrequired

Recall interval for this patient (e.g., {'months': 6}).

is_disabledbooleanrequired

Whether this recall is disabled.

notestringrequired

Optional note about this patient recall.

patientobjectrequired

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

patient_phonestring
recall_typeobjectrequired

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

statusstringrequired

Current recall status — one of: due, scheduled, completed, overdue.

updated_atstring (date-time)required

Timestamp when the recall was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/recalls/patient-recalls" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date_due": "string",
    "interval": {
      "months": 6
    },
    "note": "",
    "patient_uuid": "00000000-0000-0000-0000-000000000000",
    "recall_type_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/recalls/triggers

Create recall trigger

Create a recall trigger linking a procedure code to a recall type. When the procedure code is performed for a patient, it triggers the associated recall. Raises 404 if the recall type or procedure code does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

procedure_code_uuidstring (uuid)required

UUID of the procedure code that triggers the recall.

recall_type_uuidstring (uuid)required

UUID of the recall type this trigger fires.

Responses

201Successful Response
created_atstring (date-time)required

Timestamp when the trigger was created.

idstring (uuid)required

Public UUID of the recall trigger.

procedure_codeobjectrequired

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

recall_typeobjectrequired

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}/recalls/triggers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "procedure_code_uuid": "00000000-0000-0000-0000-000000000000",
    "recall_type_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/recalls/types

Create recall type

Create a new recall type definition. Raises 404 if the appointment_type_uuid does not exist.

Parameters

Path Parameters
org_idstringrequired

Request Body

appointment_type_uuidstring (uuid)
default_intervalobject

Default recall interval as a duration dict (e.g., {'months': 6} or {'months': 3}).

descriptionstring

Optional description of this recall type.

is_activeboolean

Whether this recall type is active and available for use.

item_orderinteger

Display order among recall types (ascending).

namestringrequired

Display name for this recall type (e.g., 'Prophy', 'Perio Maintenance').

Responses

201Successful Response
appointment_typeobject

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

created_atstring (date-time)required

Timestamp when the recall type was created.

default_intervalobjectrequired

Default recall interval as a duration dict (e.g., {'months': 6}).

descriptionstringrequired

Description of this recall type.

idstring (uuid)required

Public UUID of the recall type.

is_activebooleanrequired

Whether this recall type is active.

item_orderintegerrequired

Display order among recall types.

namestringrequired

Display name of the recall type.

updated_atstring (date-time)required

Timestamp when the recall type was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/recalls/types" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_type_uuid": "string",
    "default_interval": {
      "months": 6
    },
    "description": "",
    "is_active": true,
    "item_order": 0,
    "name": "string"
  }'
patch/api/v1/{org_id}/recalls/patient-recalls/{recall_uuid}

Update patient recall

Update a patient recall record. Raises 404 if the patient recall does not exist. Raises 409 if base_version is stale.

Parameters

Path Parameters
recall_uuidstringrequired
org_idstringrequired

Request Body

base_versionintegerrequired

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

date_duestring (date)
date_scheduledstring (date)
intervalobject
is_disabledboolean
notestring
statusstring

Responses

200Successful Response
appointmentobject

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

created_atstring (date-time)required

Timestamp when the recall was created.

date_duestring (date)
date_previousstring (date)
date_scheduledstring (date)
idstring (uuid)required

Public UUID of the patient recall.

intervalobjectrequired

Recall interval for this patient (e.g., {'months': 6}).

is_disabledbooleanrequired

Whether this recall is disabled.

notestringrequired

Optional note about this patient recall.

patientobjectrequired

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

patient_phonestring
recall_typeobjectrequired

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

statusstringrequired

Current recall status — one of: due, scheduled, completed, overdue.

updated_atstring (date-time)required

Timestamp when the recall was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/recalls/patient-recalls/{recall_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "date_due": "string",
    "date_scheduled": "string",
    "interval": null,
    "is_disabled": null
  }'
patch/api/v1/{org_id}/recalls/types/{recall_type_uuid}

Update recall type

Update a recall type definition. Raises 404 if the recall type or appointment type does not exist. Raises 409 if base_version is stale.

Parameters

Path Parameters
recall_type_uuidstringrequired
org_idstringrequired

Request Body

appointment_type_uuidstring (uuid)
base_versionintegerrequired

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

default_intervalobject
descriptionstring
is_activeboolean
item_orderinteger
namestring

Responses

200Successful Response
appointment_typeobject

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

created_atstring (date-time)required

Timestamp when the recall type was created.

default_intervalobjectrequired

Default recall interval as a duration dict (e.g., {'months': 6}).

descriptionstringrequired

Description of this recall type.

idstring (uuid)required

Public UUID of the recall type.

is_activebooleanrequired

Whether this recall type is active.

item_orderintegerrequired

Display order among recall types.

namestringrequired

Display name of the recall type.

updated_atstring (date-time)required

Timestamp when the recall type was last updated.

versionintegerrequired

Current version for optimistic concurrency.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/recalls/types/{recall_type_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_type_uuid": "string",
    "base_version": 1,
    "default_interval": null,
    "description": "string",
    "is_active": null
  }'
delete/api/v1/{org_id}/recalls/triggers/{trigger_uuid}

Delete recall trigger

Delete a recall trigger. This is irreversible. Raises 404 if the trigger does not exist.

Parameters

Path Parameters
trigger_uuidstringrequired
org_idstringrequired

Responses

204Successful Response
422Validation Error
detailobject[]
curl
curl -X DELETE "https://api.example.com/api/v1/{org_id}/recalls/triggers/{trigger_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
delete/api/v1/{org_id}/recalls/types/{recall_type_uuid}

Delete recall type

Delete a recall type. This is irreversible. Raises 404 if the recall type does not exist.

Parameters

Path Parameters
recall_type_uuidstringrequired
org_idstringrequired

Responses

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

Waitlist

10 endpoints

get/api/v1/{org_id}/waitlist/entries

List ASAP entries

List ASAP entries with filtering, sorting, and pagination. Supports cross-location matching: entries with location_scope='selected' or 'any' that match the given location are included when include_cross_location is true.

Parameters

Path Parameters
org_idstringrequired
Query Parameters
location_uuidstring

Filter by location UUID.

patient_uuidstring

Filter by patient UUID.

provider_uuidstring

Filter by preferred provider UUID.

appointment_type_uuidstring

Filter by appointment type UUID.

statusstring

Comma-separated status filter (e.g., 'waiting,contacted,offered').

urgencystring

Filter by urgency: urgent, soon, routine, flexible.

sourcestring

Filter by source: manual, appointment_flag, recall, treatment_plan, online.

include_cross_locationboolean

Include cross-location entries matching this location.

Default: true

sort_bystring

Sort field: urgency, score, days_waiting, created_at, treatment_value.

Default: "created_at"

sort_dirstring

Sort direction: asc or desc.

Default: "desc"

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Page size (max 200).

Default: 50

Responses

200Successful Response
itemsobject[]required

List of ASAP entries for the current page.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of entries per page.

totalintegerrequired

Total number of matching entries.

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

Get ASAP entry detail

Get a single ASAP entry with full details. Raises 404 if not found.

Parameters

Path Parameters
entry_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
additional_locationsobject[]

Additional locations (when scope='selected').

appointmentobject

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

appointment_typeobject

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

contact_attemptsinteger

Number of contact attempts made.

contact_method_usedstring
contacted_atstring (date-time)
created_atstring (date-time)required

When the entry was created.

date_range_endstring (date)
date_range_startstring (date)
days_waitingintegerrequired

Computed: number of days since entry was created.

estimated_duration_minsinteger
idstring (uuid)required

Entry UUID.

last_offered_slotobject
locationobjectrequired

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

location_scopestringrequired

How broadly to match: home_only, selected, any.

notestring

Free-text note.

patientobjectrequired

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

patient_responsestring
patient_scoreinteger
preferred_daysinteger[]
preferred_time_endstring (time)
preferred_time_startstring (time)
priorityobject

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

providerobject

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

recallobject

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

responded_atstring (date-time)
score_calculated_atstring (date-time)
score_detailsobject
sourcestringrequired

How the entry was created. One of: manual, appointment_flag, recall, treatment_plan, online.

statusstringrequired

One of: waiting, contacted, offered, scheduled, removed, expired.

treatment_valuestring
updated_atstring (date-time)required

When the entry was last updated.

urgencystringrequired

One of: urgent, soon, routine, flexible.

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

Get contact history

Get the full contact history for an ASAP entry. Returns contact log entries ordered by most recent first. Raises 404 if entry not found.

Parameters

Path Parameters
entry_uuidstringrequired
org_idstringrequired

Responses

200Successful Response
422Validation Error
detailobject[]
curl
curl -X GET "https://api.example.com/api/v1/{org_id}/waitlist/entries/{entry_uuid}/contact-log" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
post/api/v1/{org_id}/waitlist/entries

Create ASAP entry

Add a patient to the ASAP list. Raises 404 if patient, location, provider, or appointment type not found. Raises 409 if a duplicate active entry exists (same patient + location + appointment_type). Raises 422 if validation fails (e.g., date_range_start > date_range_end).

Parameters

Path Parameters
org_idstringrequired

Request Body

additional_location_uuidsstring (uuid)[]
appointment_type_uuidstring (uuid)
appointment_uuidstring (uuid)
date_range_endstring (date)
date_range_startstring (date)
estimated_duration_minsinteger
location_scopestring

How broadly to match across locations. One of: home_only, selected, any.

location_uuidstring (uuid)required

Primary location for this entry.

notestring

Free-text note (e.g., 'mornings only').

patient_uuidstring (uuid)required

Patient to add to the ASAP list.

preferred_daysinteger[]
preferred_time_endstring (time)
preferred_time_startstring (time)
priority_uuidstring (uuid)
provider_uuidstring (uuid)
recall_uuidstring (uuid)
sourcestring

How the entry was created. One of: manual, appointment_flag, recall, treatment_plan, online.

treatment_valuenumber
urgencystring

How quickly the patient needs to be seen. One of: urgent, soon, routine, flexible.

Responses

201Successful Response
additional_locationsobject[]

Additional locations (when scope='selected').

appointmentobject

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

appointment_typeobject

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

contact_attemptsinteger

Number of contact attempts made.

contact_method_usedstring
contacted_atstring (date-time)
created_atstring (date-time)required

When the entry was created.

date_range_endstring (date)
date_range_startstring (date)
days_waitingintegerrequired

Computed: number of days since entry was created.

estimated_duration_minsinteger
idstring (uuid)required

Entry UUID.

last_offered_slotobject
locationobjectrequired

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

location_scopestringrequired

How broadly to match: home_only, selected, any.

notestring

Free-text note.

patientobjectrequired

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

patient_responsestring
patient_scoreinteger
preferred_daysinteger[]
preferred_time_endstring (time)
preferred_time_startstring (time)
priorityobject

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

providerobject

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

recallobject

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

responded_atstring (date-time)
score_calculated_atstring (date-time)
score_detailsobject
sourcestringrequired

How the entry was created. One of: manual, appointment_flag, recall, treatment_plan, online.

statusstringrequired

One of: waiting, contacted, offered, scheduled, removed, expired.

treatment_valuestring
updated_atstring (date-time)required

When the entry was last updated.

urgencystringrequired

One of: urgent, soon, routine, flexible.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/waitlist/entries" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "additional_location_uuids": null,
    "appointment_type_uuid": "string",
    "appointment_uuid": "string",
    "date_range_end": "string",
    "date_range_start": "string",
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "patient_uuid": "00000000-0000-0000-0000-000000000000"
  }'
post/api/v1/{org_id}/waitlist/entries/{entry_uuid}/contact

Log a contact attempt

Record that a patient was contacted about an opening. Updates the entry's contact tracking fields and creates a contact log record. Transitions status from 'waiting' to 'contacted' automatically. Raises 404 if entry or slot location not found.

Parameters

Path Parameters
entry_uuidstringrequired
org_idstringrequired

Request Body

contact_methodstringrequired

How the patient was contacted. One of: sms, email, phone, app_notification.

initiated_bystring

Who initiated the contact. One of: staff, smart_fill.

message_idstring
slot_datestring (date)required

Date of the opening offered.

slot_location_uuidstring (uuid)required

Location of the opening offered.

slot_start_timestring (time)required

Start time of the opening offered.

Responses

200Successful Response
additional_locationsobject[]

Additional locations (when scope='selected').

appointmentobject

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

appointment_typeobject

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

contact_attemptsinteger

Number of contact attempts made.

contact_method_usedstring
contacted_atstring (date-time)
created_atstring (date-time)required

When the entry was created.

date_range_endstring (date)
date_range_startstring (date)
days_waitingintegerrequired

Computed: number of days since entry was created.

estimated_duration_minsinteger
idstring (uuid)required

Entry UUID.

last_offered_slotobject
locationobjectrequired

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

location_scopestringrequired

How broadly to match: home_only, selected, any.

notestring

Free-text note.

patientobjectrequired

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

patient_responsestring
patient_scoreinteger
preferred_daysinteger[]
preferred_time_endstring (time)
preferred_time_startstring (time)
priorityobject

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

providerobject

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

recallobject

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

responded_atstring (date-time)
score_calculated_atstring (date-time)
score_detailsobject
sourcestringrequired

How the entry was created. One of: manual, appointment_flag, recall, treatment_plan, online.

statusstringrequired

One of: waiting, contacted, offered, scheduled, removed, expired.

treatment_valuestring
updated_atstring (date-time)required

When the entry was last updated.

urgencystringrequired

One of: urgent, soon, routine, flexible.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/waitlist/entries/{entry_uuid}/contact" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_method": "string",
    "initiated_by": "staff",
    "message_id": "string",
    "slot_date": "2025-01-15",
    "slot_location_uuid": "00000000-0000-0000-0000-000000000000",
    "slot_start_time": "09:00:00"
  }'
post/api/v1/{org_id}/waitlist/entries/{entry_uuid}/response

Record patient response

Record a patient's response to an outreach attempt. When patient_response='accepted', the entry status transitions to 'scheduled'. When patient_response='declined' or 'expired', the entry returns to 'waiting'. Raises 404 if entry not found.

Parameters

Path Parameters
entry_uuidstringrequired
org_idstringrequired

Request Body

contact_methodstring
message_idstring
patient_responsestringrequired

Patient's response. One of: accepted, declined, no_answer, slot_taken, expired.

Responses

200Successful Response
additional_locationsobject[]

Additional locations (when scope='selected').

appointmentobject

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

appointment_typeobject

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

contact_attemptsinteger

Number of contact attempts made.

contact_method_usedstring
contacted_atstring (date-time)
created_atstring (date-time)required

When the entry was created.

date_range_endstring (date)
date_range_startstring (date)
days_waitingintegerrequired

Computed: number of days since entry was created.

estimated_duration_minsinteger
idstring (uuid)required

Entry UUID.

last_offered_slotobject
locationobjectrequired

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

location_scopestringrequired

How broadly to match: home_only, selected, any.

notestring

Free-text note.

patientobjectrequired

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

patient_responsestring
patient_scoreinteger
preferred_daysinteger[]
preferred_time_endstring (time)
preferred_time_startstring (time)
priorityobject

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

providerobject

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

recallobject

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

responded_atstring (date-time)
score_calculated_atstring (date-time)
score_detailsobject
sourcestringrequired

How the entry was created. One of: manual, appointment_flag, recall, treatment_plan, online.

statusstringrequired

One of: waiting, contacted, offered, scheduled, removed, expired.

treatment_valuestring
updated_atstring (date-time)required

When the entry was last updated.

urgencystringrequired

One of: urgent, soon, routine, flexible.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/waitlist/entries/{entry_uuid}/response" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_method": "string",
    "message_id": "string",
    "patient_response": "string"
  }'
post/api/v1/{org_id}/waitlist/entries/bulk-remove

Bulk remove ASAP entries

Remove multiple ASAP entries at once. Useful for list cleanup. Sets status to 'removed' for all specified entries.

Parameters

Path Parameters
org_idstringrequired

Request Body

entry_uuidsstring (uuid)[]required

Entry UUIDs to remove.

Responses

200Successful Response
removed_countintegerrequired

Number of entries removed.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/waitlist/entries/bulk-remove" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entry_uuids": []
  }'
post/api/v1/{org_id}/waitlist/quick-fill

Find matching ASAP entries for an opening

Given an opening (date, time, location, provider), find matching ASAP entries ranked by urgency, priority, and score. Supports cross-location matching when include_cross_location is true. Returns match metadata (quality, provider_match, location_match, duration_fit) for each result.

Parameters

Path Parameters
org_idstringrequired

Request Body

appointment_type_uuidstring (uuid)
include_cross_locationboolean

Include entries with 'selected' or 'any' location scope.

location_uuidstring (uuid)required

Location of the opening.

max_resultsinteger

Maximum number of matches to return.

provider_uuidstring (uuid)
slot_datestring (date)required

Date of the opening.

slot_end_timestring (time)required

End time of the opening.

slot_start_timestring (time)required

Start time of the opening.

Responses

200Successful Response
matchesobject[]required

Ranked list of matching ASAP entries.

total_matchesintegerrequired

Total number of matches found.

422Validation Error
detailobject[]
curl
curl -X POST "https://api.example.com/api/v1/{org_id}/waitlist/quick-fill" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_type_uuid": "string",
    "include_cross_location": true,
    "location_uuid": "00000000-0000-0000-0000-000000000000",
    "max_results": 25,
    "provider_uuid": "string",
    "slot_date": "2025-01-15",
    "slot_end_time": "09:00:00",
    "slot_start_time": "09:00:00"
  }'
patch/api/v1/{org_id}/waitlist/entries/{entry_uuid}

Update ASAP entry

Update an ASAP entry's preferences, urgency, or status. Raises 404 if entry not found.

Parameters

Path Parameters
entry_uuidstringrequired
org_idstringrequired

Request Body

additional_location_uuidsstring (uuid)[]
appointment_type_uuidstring (uuid)
appointment_uuidstring (uuid)
date_range_endstring (date)
date_range_startstring (date)
estimated_duration_minsinteger
location_scopestring
notestring
preferred_daysinteger[]
preferred_time_endstring (time)
preferred_time_startstring (time)
priority_uuidstring (uuid)
provider_uuidstring (uuid)
statusstring
treatment_valuenumber
urgencystring

Responses

200Successful Response
additional_locationsobject[]

Additional locations (when scope='selected').

appointmentobject

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

appointment_typeobject

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

contact_attemptsinteger

Number of contact attempts made.

contact_method_usedstring
contacted_atstring (date-time)
created_atstring (date-time)required

When the entry was created.

date_range_endstring (date)
date_range_startstring (date)
days_waitingintegerrequired

Computed: number of days since entry was created.

estimated_duration_minsinteger
idstring (uuid)required

Entry UUID.

last_offered_slotobject
locationobjectrequired

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

location_scopestringrequired

How broadly to match: home_only, selected, any.

notestring

Free-text note.

patientobjectrequired

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

patient_responsestring
patient_scoreinteger
preferred_daysinteger[]
preferred_time_endstring (time)
preferred_time_startstring (time)
priorityobject

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

providerobject

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

recallobject

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

responded_atstring (date-time)
score_calculated_atstring (date-time)
score_detailsobject
sourcestringrequired

How the entry was created. One of: manual, appointment_flag, recall, treatment_plan, online.

statusstringrequired

One of: waiting, contacted, offered, scheduled, removed, expired.

treatment_valuestring
updated_atstring (date-time)required

When the entry was last updated.

urgencystringrequired

One of: urgent, soon, routine, flexible.

422Validation Error
detailobject[]
curl
curl -X PATCH "https://api.example.com/api/v1/{org_id}/waitlist/entries/{entry_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "additional_location_uuids": null,
    "appointment_type_uuid": "string",
    "appointment_uuid": "string",
    "date_range_end": "string",
    "date_range_start": "string"
  }'
delete/api/v1/{org_id}/waitlist/entries/{entry_uuid}

Remove ASAP entry

Remove a patient from the ASAP list. Raises 404 if entry not found.

Parameters

Path Parameters
entry_uuidstringrequired
org_idstringrequired

Responses

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