@rinse-dental/open-dental 3.4.2 → 4.0.2

package/docs/Open Dental 2026-04-22/apiapptfielddefs.md

@@ -0,0 +1,130 @@
+# API: ApptFieldDefs
+
+**Source:** https://www.opendental.com/site/apiapptfielddefs.html
+**DB Schema Ref:** apptfielddef
+**Extracted:** 2026-04-22
+**Base Path:** `/apptfielddefs`
+
+---
+
+## Overview
+ApptFieldDefs define custom fields that appear in the Edit Appointment window (bottom-left section). Each definition specifies a field name and type (free-text or pick list). These definitions must exist before ApptFields can be created for appointments.
+
+---
+
+## Endpoints
+
+### GET /apptfielddefs
+
+**Version:** 21.4
+**Description:** Retrieves all appointment field definitions.
+
+**Response:** Array of apptfielddef objects
+| Field | Type | Description |
+|-------|------|-------------|
+| ApptFieldDefNum | integer | Primary key |
+| FieldName | string | The custom field's name; duplicates are not allowed |
+| FieldType | string (enum) | "Text" or "PickList"; see Field Reference |
+| PickList | string | Pick list items separated by `\r\n`; empty if FieldType is "Text" |
+| ItemOrder | integer | Zero-based display order |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+### GET /apptfielddefs/{ApptFieldDefNum}
+
+**Version:** 26.1
+**Description:** Retrieves a single appointment field definition.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ApptFieldDefNum | integer | Yes | Primary key of the field definition |
+
+**Response:** Single apptfielddef object (same fields as GET list)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### POST /apptfielddefs
+
+**Version:** 21.4
+**Description:** Creates a new appointment field definition. Duplicate FieldNames are not allowed.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| FieldName | string | Yes | The field's display name; must be unique |
+| FieldType | string (enum) | No | "Text" or "PickList"; defaults to "Text" |
+| PickList | string | No* | Items separated by `\r\n`; required if FieldType is "PickList" |
+
+**Response:** Created apptfielddef object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+
+---
+
+### PUT /apptfielddefs/{ApptFieldDefNum}
+
+**Version:** 26.1
+**Description:** Updates an existing appointment field definition.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ApptFieldDefNum | integer | Yes | Primary key of the field definition to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| FieldName | string | No | The field's display name |
+| FieldType | string (enum) | No | "Text" or "PickList" |
+| PickList | string | No | Items separated by `\r\n` |
+
+**Response:** Updated apptfielddef object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### FieldType (enum: ApptFieldType)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Text | 0 | Free-form text entry in the Edit Appointment window |
+| PickList | 1 | User selects from predefined list items |
+
+---
+
+## Implementation Notes
+- Duplicate `FieldName` values are rejected; field names must be unique across all ApptFieldDefs.
+- `PickList` is required when `FieldType` is "PickList"; items are separated by `\r\n`.
+- `FieldName` in the `apptfielddef` table acts as a functional FK — `apptfield.FieldName` references `apptfielddef.FieldName` directly (not by numeric ID).
+- `ItemOrder` is zero-based and controls display order in the Edit Appointment window.
+- ApptFieldDefs must be created via the Open Dental UI or this API before ApptFields can reference them.
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| ApptFields | Individual field values on appointments; references FieldName from this resource |

package/docs/Open Dental 2026-04-22/apiapptfields.md

@@ -0,0 +1,147 @@
+# API: ApptFields
+
+**Source:** https://www.opendental.com/site/apiapptfields.html
+**DB Schema Ref:** apptfield
+**Extracted:** 2026-04-22
+**Base Path:** `/apptfields`
+
+---
+
+## Overview
+ApptFields are the individual values of custom appointment fields for specific appointments. Each ApptField links a particular appointment to a named field definition and stores the user-entered value. Field definitions must be created first via ApptFieldDefs.
+
+---
+
+## Endpoints
+
+### GET /apptfields/{ApptFieldNum}
+
+**Version:** 26.1
+**Description:** Retrieves a single appointment field record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ApptFieldNum | integer | Yes | Primary key of the apptfield record |
+
+**Response:** Single apptfield object
+| Field | Type | Description |
+|-------|------|-------------|
+| ApptFieldNum | integer | Primary key |
+| AptNum | integer | FK to appointment.AptNum |
+| FieldName | string | FK to apptfielddef.FieldName |
+| FieldValue | string | The current value stored for this field |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /apptfields
+
+**Version:** 21.1
+**Description:** Retrieves multiple appointment field records with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| AptNum | integer | No (required before v26.1) | — | Filter by appointment number |
+| FieldName | string | No (optional from v26.1) | — | Filter by field name |
+
+**Response:** Array of apptfield objects (same fields as GET single)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+### POST /apptfields
+
+**Version:** 26.1
+**Description:** Creates a new appointment field value.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| AptNum | integer | Yes | FK to appointment.AptNum |
+| FieldName | string | Yes* | FK to apptfielddef.FieldName; required if apptFieldDefNum not provided |
+| FieldValue | string | Yes | Field value; must match a PickList item if FieldType is "PickList" |
+| apptFieldDefNum | integer | No* | Alternative to FieldName; FK to apptfielddef.ApptFieldDefNum |
+
+**Response:** Created apptfield object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+
+---
+
+### PUT /apptfields/{ApptFieldNum}
+
+**Version:** 21.1
+**Description:** Updates an existing appointment field value.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ApptFieldNum | integer | Yes | Primary key of the apptfield record to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| AptNum | integer | No (optional from v26.1) | Associated appointment |
+| FieldName | string | No (optional from v26.1) | Field name |
+| FieldValue | string | Yes | New field value |
+
+**Response:** Updated apptfield object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+
+---
+
+### DELETE /apptfields/{ApptFieldNum}
+
+**Version:** 26.1
+**Description:** Removes an appointment field record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ApptFieldNum | integer | Yes | Primary key of the apptfield record to delete |
+
+**Response:** 200 OK (no content body)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+- ApptFieldDefs (field definitions) must be set up in Open Dental UI or via the ApptFieldDefs API before creating ApptField records.
+- `FieldName` is a string FK to `apptfielddef.FieldName` — the field name itself, not a numeric ID.
+- On POST, either `FieldName` or `apptFieldDefNum` can be used to identify the field definition.
+- `FieldValue` must match one of the PickList items exactly if the field definition's `FieldType` is "PickList".
+- Prior to v26.1, `AptNum` was required on GET and `AptNum`/`FieldName` were required on PUT.
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| ApptFieldDefs | Defines the custom field names and types referenced by FieldName |
+| Appointments | AptNum source |

package/docs/Open Dental 2026-04-22/apiasapcomms.md

@@ -0,0 +1,141 @@
+# API: AsapComms
+
+**Source:** https://www.opendental.com/site/apiasapcomms.html
+**Extracted:** 2026-04-22
+**Base Path:** `/asapcomms`
+
+---
+
+## Overview
+The AsapComms API manages text message communications for the Web Sched ASAP feature, which notifies patients about last-minute appointment openings. Requires active subscriptions to both WebSched ASAP and Integrated Texting eServices.
+
+---
+
+## Endpoints
+
+### GET /asapcomms/{AsapCommNum}
+
+**Version:** 23.3.3
+**Description:** Retrieves a single ASAP communication record by its identifier.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| AsapCommNum | integer | Yes | ASAP communication record identifier |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| AsapCommNum | integer | Unique identifier |
+| FKey | integer | Foreign key identifier (points to appointment or recall based on FKeyType) |
+| FKeyType | string | Type of record FKey references (see Field Reference) |
+| ScheduleNum | integer | FK to schedule blockout created for this ASAP slot |
+| PatNum | integer | FK to patient |
+| ClinicNum | integer | FK to clinic |
+| DateTimeEntry | datetime | Creation timestamp |
+| DateTimeExpire | datetime | Expiration time for the ASAP offer |
+| DateTimeSmsScheduled | datetime | Scheduled SMS send time |
+| SmsSendStatus | string | SMS send status (see Field Reference) |
+| DateTimeSmsSent | datetime | Actual SMS send timestamp |
+| ResponseStatus | string | Patient response status (see Field Reference) |
+| DateTimeOrig | datetime | Original appointment or recall date/time |
+| TemplateText | string | SMS message template with placeholders |
+| Note | string | Additional notes |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /asapcomms
+
+**Version:** 23.3.3
+**Description:** Retrieves a filtered list of ASAP communication records.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| ClinicNum | integer | No | — | Filter by clinic |
+| date | string | No | — | Single day filter (format: "yyyy-mm-dd"); mutually exclusive with dateStart/dateEnd |
+| dateStart | string | No | 7 days prior | Records on or after this date (format: "yyyy-mm-dd") |
+| dateEnd | string | No | today midnight | Records before this date (format: "yyyy-mm-dd") |
+
+**Response:** array of objects (same fields as GET single)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /asapcomms
+
+**Version:** 23.3.3
+**Description:** Creates an ASAP communication record and associated Web Sched ASAP blockout. Requires WebSched ASAP and Integrated Texting eService subscriptions.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| op | integer | Yes | FK to operatory.OperatoryNum |
+| aptNum | integer | Conditional | FK to appointment.AptNum; required if `recallNum` is omitted |
+| recallNum | integer | Conditional | FK to recall.RecallNum; required if `aptNum` is omitted (added v25.2.9) |
+| dateTimeStart | string | Yes | Blockout start date/time (format: "yyyy-MM-dd HH:mm:ss") |
+
+**Response:** object — created ASAP comm record with all fields
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### FKeyType (enum)
+| Value | Description |
+|-------|-------------|
+| ScheduledAppt | FKey points to a scheduled appointment |
+| UnscheduledAppt | FKey points to an unscheduled appointment |
+| PlannedAppt | FKey points to a planned appointment |
+| Broken | FKey points to a broken appointment |
+| Recall | FKey points to a recall record |
+
+### SmsSendStatus (enum)
+| Value | Description |
+|-------|-------------|
+| SendSuccessful | SMS was sent successfully |
+| DoNotSend | SMS should not be sent |
+| SendNotAttempted | SMS has not yet been attempted |
+
+### ResponseStatus (enum)
+| Value | Description |
+|-------|-------------|
+| PendingRsvp | Awaiting patient response |
+| UnableToSend | Communication could not be sent |
+| Failed | Communication failed |
+| AwaitingTransmit | Queued for transmission |
+
+---
+
+## Implementation Notes
+- Requires active subscriptions to both WebSched ASAP and Integrated Texting eServices.
+- For POST: obtain `aptNum` via Appointments GET ASAP endpoint; use Appointments GET Slots or GET (multiple) plus Schedules GET (multiple) to find available time slots.
+- The referenced appointment (`aptNum`) or recall (`recallNum`) must have Priority = 1 (ASAP) for the POST to succeed.
+- POST will fail if the new appointment would overlap with an existing appointment or blockout that does not allow overlap.
+- `recallNum` parameter was added in version 25.2.9; versions prior to that require `aptNum`.
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| Appointments | Retrieve ASAP appointments and available slots |
+| Schedules | Retrieve available schedule slots for blockout placement |
+| Recalls | Retrieve recall records for ASAP recall notifications |

package/docs/Open Dental 2026-04-22/apiautonotecontrols.md

@@ -0,0 +1,111 @@
+# API: AutoNoteControls
+
+**Source:** https://www.opendental.com/site/apiautonotecontrols.html
+**Extracted:** 2026-04-22
+**Base Path:** `/autonotecontrols`
+
+---
+
+## Overview
+AutoNoteControls are interactive prompts embedded within Auto Notes. When an Auto Note is rendered, each control presents the user with either a free-text entry or a selection list. Controls are referenced in Auto Note `MainText` by their `Descript` field.
+
+---
+
+## Endpoints
+
+### GET /autonotecontrols
+
+**Version:** 22.3.22
+**Description:** Retrieves a list of all AutoNoteControls.
+
+**Response:** Array of autonotecontrol objects
+| Field | Type | Description |
+|-------|------|-------------|
+| AutoNoteControlNum | integer | Primary key |
+| Descript | string | Display name of the control; referenced in Auto Note templates |
+| ControlType | string (enum) | "Text", "OneResponse", or "MultiResponse" |
+| ControlLabel | string | Prompt text shown to the user |
+| ControlOptions | string | Response options separated by `\r\n`; empty if ControlType is "Text" |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+
+---
+
+### POST /autonotecontrols
+
+**Version:** 22.3
+**Description:** Creates a new AutoNoteControl.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Descript | string | Yes | Description/display name for this control |
+| ControlType | string (enum) | Yes | "Text", "OneResponse", or "MultiResponse" |
+| ControlLabel | string | Yes | Prompt text shown to the user |
+| ControlOptions | string | Yes (for non-Text types) | Response options separated by `\r\n`; required if ControlType is "OneResponse" or "MultiResponse" |
+
+**Response:** Created autonotecontrol object (same fields as GET response)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+
+---
+
+### PUT /autonotecontrols/{AutoNoteControlNum}
+
+**Version:** 22.3
+**Description:** Updates an existing AutoNoteControl. All body fields are optional.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| AutoNoteControlNum | integer | Yes | Primary key of the control to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Descript | string | No | Display name of the control |
+| ControlType | string (enum) | No | "Text", "OneResponse", or "MultiResponse" |
+| ControlLabel | string | No | Prompt text |
+| ControlOptions | string | No | Response options separated by `\r\n` |
+
+**Response:** Updated autonotecontrol object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### ControlType (enum)
+| Value | Description |
+|-------|-------------|
+| Text | Free-form text entry; ControlOptions not applicable |
+| OneResponse | User selects exactly one option from ControlOptions |
+| MultiResponse | User selects one or more options from ControlOptions |
+
+---
+
+## Implementation Notes
+- `ControlOptions` is required on POST when `ControlType` is "OneResponse" or "MultiResponse"; it should be omitted or left empty for "Text" type.
+- Options in `ControlOptions` are newline-separated using `\r\n`.
+- AutoNoteControls are referenced by `Descript` in Auto Note `MainText` templates using the syntax: `[Prompt:"autonotecontrol.Descript"]`.
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| AutoNotes | Templates that embed AutoNoteControls via Descript reference |

package/docs/Open Dental 2026-04-22/apiautonotes.md

@@ -0,0 +1,103 @@
+# API: AutoNotes
+
+**Source:** https://www.opendental.com/site/apiautonotes.html
+**Extracted:** 2026-04-22
+**Base Path:** `/autonotes`
+
+---
+
+## Overview
+AutoNotes are text templates that combine static content with dynamic prompts. When rendered, embedded AutoNoteControl prompts allow users to fill in or select values. AutoNotes can be organized into categories defined via definitions (category=41).
+
+---
+
+## Endpoints
+
+### GET /autonotes
+
+**Version:** 22.3.22
+**Description:** Retrieves a list of Auto Notes, optionally filtered by category.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| Category | integer | No | — | FK to definition.DefNum where definition.Category=41 |
+
+**Response:** Array of autonote objects
+| Field | Type | Description |
+|-------|------|-------------|
+| AutoNoteNum | integer | Primary key |
+| AutoNoteName | string | Identifying name for this Auto Note |
+| MainText | string | Template content; static text mixed with prompts formatted as `[Prompt:"autonotecontrol.Descript"]` |
+| Category | integer | FK to definition.DefNum (category=41); 0 if uncategorized |
+| category | string | Human-readable category name |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+### POST /autonotes
+
+**Version:** 22.3.33
+**Description:** Creates a new Auto Note.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| AutoNoteName | string | Yes | Identifying name for this Auto Note |
+| MainText | string | Yes | Template content; embed prompts as `[Prompt:"autonotecontrol.Descript"]` |
+| Category | integer | No | FK to definition.DefNum (category=41); use 0 for uncategorized; defaults to 0 |
+
+**Response:** Created autonote object (same fields as GET response)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+
+---
+
+### PUT /autonotes/{AutoNoteNum}
+
+**Version:** 22.3.33
+**Description:** Updates an existing Auto Note. All body fields are optional.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| AutoNoteNum | integer | Yes | Primary key of the Auto Note to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| AutoNoteName | string | No | Identifying name |
+| MainText | string | No | Template content |
+| Category | integer | No | FK to definition.DefNum (category=41); use 0 for uncategorized |
+
+**Response:** Updated autonote object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+- Prompts in `MainText` are embedded using the syntax: `[Prompt:"autonotecontrol.Descript"]` where the value in quotes matches the `Descript` field of an existing AutoNoteControl.
+- `Category` value of 0 means uncategorized.
+- Categories are definition records where `definition.Category=41`.
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| AutoNoteControls | Defines the prompts referenced in MainText |
+| Definitions (category=41) | Category values for AutoNotes |