@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,128 @@
+# API: LabTurnarounds
+
+**Source:** https://www.opendental.com/site/apilabturnarounds.html
+**DB Schema Ref:** labturnaround
+**Extracted:** 2026-04-22
+**Base Path:** `/labturnarounds`
+
+---
+
+## Overview
+
+LabTurnarounds represent the expected processing time for a specific service at a dental laboratory. Each record links to a laboratory and stores both a published turnaround time (as advertised by the lab) and an actual turnaround time (which may be longer due to travel). Actual days are used for due-date calculations on lab cases.
+
+---
+
+## Endpoints
+
+### GET /labturnarounds/{LabTurnaroundNum}
+
+**Version:** 24.2.29
+**Description:** Retrieves a single lab turnaround record by primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LabTurnaroundNum | integer | Yes | Primary key of the lab turnaround record |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| LabTurnaroundNum | integer | Primary key |
+| LaboratoryNum | bigint | FK to laboratory.LaboratoryNum |
+| Description | varchar(255) | Description of the service the lab is performing |
+| DaysPublished | smallint | Number of days the lab publishes as turnaround time |
+| DaysActual | smallint | Actual turnaround days including travel; used for due-date calculations |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /labturnarounds
+
+**Version:** 24.2.29
+**Description:** Retrieves multiple lab turnaround records, optionally filtered by laboratory.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| LaboratoryNum | integer | No | — | FK to laboratory.LaboratoryNum; filters results to a single lab |
+
+**Response:** array of objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### POST /labturnarounds
+
+**Version:** 24.4.13
+**Description:** Creates a new lab turnaround record for a laboratory.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LaboratoryNum | integer | Yes | FK to laboratory.LaboratoryNum |
+| Description | string | Yes | Description of the service the lab is performing |
+| DaysActual | integer | Yes | Actual turnaround days (used for due-date calculations) |
+| DaysPublished | integer | No | Days the lab publishes as turnaround time |
+
+**Response:** object — created record with assigned LabTurnaroundNum
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /labturnarounds/{LabTurnaroundNum}
+
+**Version:** 24.4.13
+**Description:** Updates an existing lab turnaround record. All body fields are optional.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LabTurnaroundNum | integer | Yes | Primary key of the record to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Description | string | No | Service description; overwrites existing value |
+| DaysPublished | integer | No | Published turnaround days |
+| DaysActual | integer | No | Actual turnaround days |
+
+**Response:** object — updated lab turnaround record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+
+- `DaysActual` is the value used by Open Dental for computing lab case due dates; it may exceed `DaysPublished` to account for shipping/travel time.
+- `LaboratoryNum` cannot be changed via PUT; to reassign a turnaround to a different lab, delete and recreate.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| Laboratories | Parent laboratory record (LaboratoryNum FK target) |

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

@@ -0,0 +1,170 @@
+# API: MedicationPats
+
+**Source:** https://www.opendental.com/site/apimedicationpats.html
+**DB Schema Ref:** medicationpat
+**Extracted:** 2026-04-22
+**Base Path:** `/medicationpats`
+
+---
+
+## Overview
+
+MedicationPats links medication records to individual patients, representing a patient's current or historical medication list. Records with `DateStop` prior to today are considered discontinued. For EHR purposes, a record containing `PatNote`, `ProvNum`, and `DateStart` is treated as a medication order.
+
+---
+
+## Endpoints
+
+### GET /medicationpats/{MedicationPatNum}
+
+**Version:** 25.4.14
+**Description:** Retrieves a single patient medication record by its primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| MedicationPatNum | integer | Yes | Patient medication primary key |
+
+**Response:** Single object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| MedicationPatNum | integer | Primary key |
+| PatNum | string | FK to patient.PatNum |
+| medName | string | Medication name (non-DB lowercase field) |
+| MedicationNum | integer | FK to medication.MedicationNum; 0 if from eRx import |
+| PatNote | string | Patient-specific instructions (e.g., dosage details) |
+| DateStart | string | Start date (yyyy-MM-dd); "0001-01-01" if unknown |
+| DateStop | string | Stop date (yyyy-MM-dd); "0001-01-01" if active/unknown |
+| ProvNum | integer | FK to provider.ProvNum |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /medicationpats
+
+**Version:** 21.3
+**Description:** Retrieves a list of patient medication records with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | No | — | Filter by patient (added 25.4.14) |
+| includeDiscontinued | string | No | "false" | "true"/"false" — include medications where DateStop is prior to today (added 25.4.14) |
+
+**Response:** Array of objects with same fields as single GET
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /medicationpats
+
+**Version:** 21.3
+**Description:** Creates a new patient medication record.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum |
+| MedicationNum | integer | Yes | FK to medication.MedicationNum |
+| PatNote | string | No | Patient-specific instructions |
+| DateStart | string | No | Start date (yyyy-MM-dd); default "0001-01-01" |
+| DateStop | string | No | Stop date (yyyy-MM-dd); default "0001-01-01" (active) |
+| ProvNum | integer | No | FK to provider.ProvNum; default 0 |
+
+**Response:** Created object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| MedicationPatNum | integer | Newly assigned primary key |
+| PatNum | integer | FK to patient.PatNum |
+| medName | string | Medication name |
+| MedicationNum | integer | FK to medication.MedicationNum |
+| PatNote | string | Patient-specific instructions |
+| DateTStamp | datetime | Server timestamp of record creation |
+| DateStart | string | Start date |
+| DateStop | string | Stop date |
+| ProvNum | integer | FK to provider.ProvNum |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /medicationpats/{MedicationPatNum}
+
+**Version:** 22.1
+**Description:** Updates an existing patient medication record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| MedicationPatNum | integer | Yes | Patient medication primary key |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNote | string | No | Replaces existing note |
+| DateStart | string | No | Start date (yyyy-MM-dd) |
+| DateStop | string | No | Stop date (yyyy-MM-dd) |
+| ProvNum | integer | No | FK to provider.ProvNum; can be set to 0 |
+
+**Response:** Updated object (same fields as POST response)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /medicationpats/{MedicationPatNum}
+
+**Version:** 22.1
+**Description:** Removes a patient medication record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| MedicationPatNum | integer | Yes | Patient medication primary key |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+
+- `DateStop` = "0001-01-01" is the sentinel value indicating the medication is active (not discontinued).
+- A medication is considered **discontinued** when `DateStop` is prior to today's date.
+- `MedicationNum` = 0 indicates the medication came from an eRx import (no matching medication table entry).
+- To qualify as an EHR medication order, a record must include `PatNote`, `ProvNum`, and `DateStart`.
+- `DateTStamp` is server-managed and not user-editable.
+- `includeDiscontinued` defaults to "false" — active medications only are returned by default.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /medications | The medication definition records referenced by MedicationNum |

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

@@ -0,0 +1,74 @@
+# API: Medications
+
+**Source:** https://www.opendental.com/site/apimedications.html
+**Extracted:** 2026-04-22
+**Base Path:** `/medications`
+
+---
+
+## Overview
+
+Medications manages the global medication definition list from which patient medications are drawn. This resource is rarely used directly; typical workflows use MedicationPats GET and POST instead. A medication record defines the drug name, generic reference, and notes.
+
+---
+
+## Endpoints
+
+### GET /medications
+
+**Version:** 21.3
+**Description:** Retrieves the list of all available medication definitions.
+
+**Response:** Array of objects
+
+| Field | Type | Description |
+|-------|------|-------------|
+| MedicationNum | integer | Primary key |
+| MedName | string | Medication name |
+| GenericNum | integer | FK referencing the generic medication record |
+| genericName | string | Generic name of the medication (non-DB lowercase field) |
+| Notes | string | Additional notes about the medication |
+| DateTStamp | string | Last modified timestamp (yyyy-MM-dd) |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+
+---
+
+### POST /medications
+
+**Version:** 21.3
+**Description:** Creates a new medication definition record.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| MedName | string | Yes | The medication name |
+| genericName | string | No | Generic name; defaults to MedName if omitted |
+| Notes | string | No | Supplementary information about the medication |
+
+**Response:** Created medication object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest — missing or invalid fields |
+| 404 | NotFound — specified genericName does not exist |
+
+---
+
+## Implementation Notes
+
+- This resource is **rarely used directly**. The recommended workflow is to use MedicationPats GET and POST for patient medication management.
+- If `genericName` is provided in POST but does not exist in the medication table, a 404 is returned.
+- If `genericName` is omitted in POST, it defaults to the value of `MedName`.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /medicationpats | Links medication definitions to individual patients |

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

@@ -0,0 +1,78 @@
+# API: Operatories
+
+**Source:** https://www.opendental.com/site/apioperatories.html
+**Extracted:** 2026-04-22
+**Base Path:** `/operatories`
+
+---
+
+## Overview
+
+Operatories represents the treatment rooms or chairs in a dental practice. Each operatory can be assigned a default dentist and hygienist, associated with a clinic, and configured for hygiene use or web scheduling. This resource is read-only.
+
+---
+
+## Endpoints
+
+### GET /operatories/{OperatoryNum}
+
+**Version:** 24.1.10
+**Description:** Retrieves a single operatory record by its primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| OperatoryNum | integer | Yes | Operatory primary key |
+
+**Response:** Single object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| OperatoryNum | integer | Primary key |
+| OpName | string | Operatory name |
+| Abbrev | string | Abbreviation |
+| ItemOrder | integer | Display order |
+| IsHidden | boolean | Whether operatory is hidden |
+| ProvDentist | integer | FK to provider — default assigned dentist |
+| ProvHygienist | integer | FK to provider — default assigned hygienist |
+| IsHygiene | boolean | Whether this is a hygiene operatory |
+| ClinicNum | integer | FK to clinic |
+| SetProspective | boolean | Prospective scheduling setting |
+| IsWebSched | boolean | Whether web scheduling is enabled for this operatory |
+| OperatoryType | integer | Numeric type classification |
+| operatoryType | string | Type description (non-DB lowercase field) |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /operatories
+
+**Version:** 21.1
+**Description:** Retrieves all operatories, optionally filtered by clinic.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| ClinicNum | integer | No | — | Filter results to a specific clinic |
+
+**Response:** Array of objects with same fields as single GET
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+
+- This resource is read-only; no POST, PUT, or DELETE endpoints exist.
+- Operatory configuration (name, providers, clinic assignment) must be managed through the Open Dental UI.
+- Omit `ClinicNum` in GET /operatories to retrieve operatories across all clinics.

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

@@ -0,0 +1,139 @@
+# API: PatFieldDefs
+
+**Source:** https://www.opendental.com/site/apipatfielddefs.html
+**DB Schema Ref:** patfielddef
+**Extracted:** 2026-04-22
+**Base Path:** `/patfielddefs`
+
+---
+
+## Overview
+
+PatFieldDefs manages the definitions for custom patient fields that offices create to capture additional patient information. Each definition specifies the field name, type, and visibility. PickList items are managed separately via the PatFieldPickItem table (as of version 24.1).
+
+---
+
+## Endpoints
+
+### GET /patfielddefs
+
+**Version:** 22.4.9
+**Description:** Retrieves a list of all patient field definitions.
+
+**Response:** Array of objects
+
+| Field | Type | Description |
+|-------|------|-------------|
+| PatFieldDefNum | integer | Primary key |
+| FieldName | string | Field name (treated as key; must be unique) |
+| FieldType | string | Field type: "Text", "PickList", "Date", "Checkbox", "Currency", "CareCreditStatus", "CareCreditPreApprovalAmt", "CareCreditAvailableCredit" |
+| PickList | string | Empty string in GET responses (deprecated; use patfieldpickitem table) |
+| IsHidden | string | "true" or "false"; hidden fields only show for patients where already in use |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+### POST /patfielddefs
+
+**Version:** 23.3.26
+**Description:** Creates a new patient field definition.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| FieldName | string | Yes | Must be unique across all PatFieldDefs |
+| FieldType | string | Yes | "Text", "PickList", "Date", "Checkbox", "Currency", "CareCreditStatus", "CareCreditPreApprovalAmt" (v24.1+), "CareCreditAvailableCredit" (v24.1+) |
+| PickList | string | If FieldType="PickList" | Items separated by `\r\n`; creates PatFieldPickItem entries |
+| IsHidden | string | No | "true"/"false"; default "false" |
+
+**Response:** Created PatFieldDef object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+
+---
+
+### PUT /patfielddefs/{PatFieldDefNum}
+
+**Version:** 23.3.26
+**Description:** Updates an existing patient field definition.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatFieldDefNum | integer | Yes | Patient field definition primary key |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| FieldName | string | No | Must remain unique; cannot change for in-use CareCredit fields |
+| FieldType | string | No | Same enum values as POST |
+| PickList | string | No | Only allowed when converting FieldType to "PickList" from another type; items separated by `\r\n`; cannot edit existing PickLists (added 24.1) |
+| IsHidden | string | No | "true"/"false" |
+
+**Response:** Updated PatFieldDef object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /patfielddefs/{PatFieldDefNum}
+
+**Version:** 23.3.26
+**Description:** Removes a patient field definition. Cannot delete definitions that are currently in use by any patient.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatFieldDefNum | integer | Yes | Patient field definition primary key |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### FieldType (enum: PatFieldType)
+
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Text | 0 | Free-text input |
+| PickList | 1 | Selection from a predefined list; items managed via patfieldpickitem |
+| Date | 2 | Date value; stored as entered (localized format); not standardized for DB queries |
+| Checkbox | 3 | Boolean; if checked, value stored as "1"; if unchecked, row is deleted |
+| Currency | 4 | Numeric values only |
+| InCaseOfEmergency | 5 | DEPRECATED (used 16.3.1, deprecated by 16.3.4) |
+| CareCreditStatus | 6 | CareCredit pre-approval status (e.g., "Pre-Approved") |
+| CareCreditPreApprovalAmt | 7 | CareCredit pre-approval amount |
+| CareCreditAvailableCredit | 8 | Remaining available CareCredit for cardholders |
+
+---
+
+## Implementation Notes
+
+- `FieldName` is treated as a unique key — duplicate names are not allowed.
+- `PickList` field in GET responses is always an empty string; use the PatFieldPickItem table to retrieve picklist items (deprecated in v24.1).
+- `PickList` in POST creates PatFieldPickItem entries; in PUT it is only allowed when converting a field to PickList type from another type.
+- Existing PickList items cannot be edited via the `PickList` body parameter in PUT (v24.1+).
+- CareCredit `FieldName` values cannot be changed while those fields are in use.
+- A hidden PatFieldDef (`IsHidden`="true") will still show for patients that already have a value assigned.
+- DELETE will fail (400) if the field definition is currently in use by any patient record.
+- `Checkbox` type stores "1" when checked; the row is deleted entirely when unchecked.
+- `Date` type stores dates in localized format as entered — not normalized for date-range queries.