@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,112 @@
+# API: PaySplits
+
+**Source:** https://www.opendental.com/site/apipaysplits.html
+**DB Schema Ref:** paysplit
+**Extracted:** 2026-04-22
+**Base Path:** `/paysplits`
+
+---
+
+## Overview
+
+PaySplits are the individual allocation records always attached to a payment. Each paysplit affects exactly one patient account and one provider. The sum of all paysplits for a payment must equal the payment's PayAmt. PaySplits are typically created automatically via the Payments API; this endpoint supports retrieval and limited updating.
+
+---
+
+## Endpoints
+
+### GET /paysplits
+
+**Version:** 22.4.16
+**Description:** Retrieves paysplit records with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | No (optional after v24.4.24) | — | FK to patient.PatNum; retrieve all paysplits for a patient |
+| PayNum | integer | No (optional after v24.4.24) | — | FK to payment.PayNum; retrieve all paysplits for a payment |
+| ProcNum | integer | No | — | FK to procedurelog.ProcNum; retrieve all paysplits for a procedure (v24.4.24+) |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| SplitNum | integer | Primary key |
+| SplitAmt | decimal | Amount of the split |
+| PatNum | integer | FK to patient.PatNum (may be guarantor PatNum for payment plan splits) |
+| PayNum | integer | FK to payment.PayNum |
+| ProvNum | integer | FK to provider.ProvNum |
+| PayPlanNum | integer | FK to payplan.PayPlanNum; 0 if not attached to a payment plan |
+| DatePay | date | Payment date; always in sync with the parent Payment date |
+| ProcNum | integer | FK to procedurelog.ProcNum; 0 if not attached to a procedure |
+| DateEntry | date | Date the paysplit was created; not user-editable |
+| UnearnedType | integer | FK to definition.DefNum; 0 if not unearned/prepayment |
+| unearnedType | string | Text representation of UnearnedType |
+| ClinicNum | integer | FK to clinic.ClinicNum; 0 if no clinic; need not match parent payment ClinicNum |
+| SecDateTEdit | datetime | Last edit timestamp (auto-managed by MySQL) |
+| AdjNum | integer | FK to adjustment.AdjNum; 0 if not counteracting an adjustment |
+| PayPlanChargeNum | integer | FK to payplancharge.PayPlanChargeNum; 0 if not counteracting a payment plan charge |
+| PayPlanDebitType | string | Enum: PayPlanDebitTypes |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /paysplits/{SplitNum}
+
+**Version:** 25.2.9
+**Description:** Updates an existing paysplit record. Only ProvNum and ClinicNum can be updated.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| SplitNum | integer | Yes | Primary key of the paysplit |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ProvNum | integer | No | FK to provider.ProvNum. Can always be updated when AllowPrepayProvider preference is enabled. Without that preference, can only be updated for paysplits that do not have an UnearnedType |
+| ClinicNum | integer | No | FK to clinic.ClinicNum |
+
+**Response:** object (same fields as GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### PayPlanDebitType (enum: PayPlanDebitTypes)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Unknown | 0 | Legacy splits associated with payment plans; did not specify principal vs. interest |
+| Principal | 1 | Split explicitly applied toward principal only |
+| Interest | 2 | Split explicitly applied toward interest only |
+
+---
+
+## Implementation Notes
+
+- Each paysplit affects exactly one patient account and one provider
+- The sum of all SplitAmts for a given PayNum must equal the payment's PayAmt
+- UnearnedType=0 means "None" (not a prepayment/unearned split); non-zero values are FKs to definition.DefNum
+- ProvNum can only be updated (via PUT) for paysplits without an UnearnedType, unless the AllowPrepayProvider preference is enabled
+- ClinicNum on a paysplit is independent of the parent payment's ClinicNum; payments can be split across clinics
+- PayPlanNum=0 means the split is not associated with a payment plan
+- ProcNum=0 means the split is not attached to a specific procedure
+- AdjNum=0 means the split does not counteract an adjustment
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| /payments | Parent payment record for each paysplit |
+| /payplans | Payment plan that a paysplit may be attached to |

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

@@ -0,0 +1,155 @@
+# API: PerioExams
+
+**Source:** https://www.opendental.com/site/apiperioexams.html
+**Extracted:** 2026-04-22
+**Base Path:** `/perioexams`
+
+---
+
+## Overview
+
+PerioExams represent periodontal examination sessions for a patient. Each exam contains metadata (date, provider, notes) and is associated with multiple PerioMeasure records that store individual tooth measurements. Deleting a PerioExam also deletes all associated periomeasures.
+
+---
+
+## Endpoints
+
+### GET /perioexams/{PerioExamNum}
+
+**Version:** 22.4.36
+**Description:** Retrieves a single periodontal exam record by primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PerioExamNum | integer | Yes | Primary key of the perioexam |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| PerioExamNum | integer | Primary key |
+| PatNum | integer | FK to patient.PatNum |
+| ExamDate | string | Exam date, format: yyyy-MM-dd |
+| ProvNum | integer | FK to provider.ProvNum |
+| DateTMeasureEdit | string | Last measure edit datetime |
+| Note | string | Exam notes |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### GET /perioexams
+
+**Version:** 22.4.36
+**Description:** Retrieves multiple periodontal exam records with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | No | — | FK to patient.PatNum |
+| ExamDate | string | No | — | Format: yyyy-MM-dd; retrieves exams on or after this date |
+
+**Response:** array of objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /perioexams
+
+**Version:** 23.1.20
+**Description:** Creates a new periodontal exam, optionally including surface measurement strings.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum |
+| UpperFacial | string | No | Measurement string for facial surfaces of upper teeth (1–16) |
+| UpperLingual | string | No | Measurement string for lingual surfaces of upper teeth (1–16) |
+| LowerLingual | string | No | Measurement string for lingual surfaces of lower teeth (17–32) |
+| LowerFacial | string | No | Measurement string for facial surfaces of lower teeth (17–32) |
+| ExamDate | string | No | Format: yyyy-MM-dd; defaults to today (v23.3.27+) |
+| ProvNum | integer | No | FK to provider.ProvNum; defaults to patient's primary provider (v23.3.27+) |
+| Note | string | No | Exam notes (v23.3.27+) |
+
+**Response:** object — created perioexam record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /perioexams/{PerioExamNum}
+
+**Version:** 23.3.27
+**Description:** Updates exam-level metadata for an existing perioexam. Note field overwrites existing value.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PerioExamNum | integer | Yes | Primary key of the perioexam |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ExamDate | string | No | Format: yyyy-MM-dd |
+| ProvNum | integer | No | FK to provider.ProvNum |
+| Note | string | No | Overwrites existing note |
+
+**Response:** object — updated perioexam record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /perioexams/{PerioExamNum}
+
+**Version:** 23.3.27
+**Description:** Deletes a periodontal exam and all of its associated periomeasure records.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PerioExamNum | integer | Yes | Primary key of the perioexam |
+
+**Response:** 200 OK
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+
+- Deleting a PerioExam cascades to delete all associated PerioMeasure records
+- Surface measurement strings in POST (UpperFacial, UpperLingual, LowerLingual, LowerFacial): each integer (0–9) is a probing measurement; optional letter flags can follow each digit: b=bleeding, s=suppuration, p=plaque, c=calculus
+- Measurement strings parse left-to-right, traversing surfaces right to left within each region
+- ExamDate defaults to today when not specified; ProvNum defaults to patient's primary provider
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| /periomeasures | Individual tooth measurements within this exam |

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

@@ -0,0 +1,162 @@
+# API: PerioMeasures
+
+**Source:** https://www.opendental.com/site/apiperiomeasures.html
+**Extracted:** 2026-04-22
+**Base Path:** `/periomeasures`
+
+---
+
+## Overview
+
+PerioMeasures store individual tooth measurements within a periodontal exam. One tooth can have multiple PerioMeasures on a single exam, but only one of each SequenceType per tooth. Measurements include probing depths, gingival margins, furcation, mobility, and bleeding/plaque flags. CAL (Clinical Attachment Level) is calculated (Probing + GingMargin) and is never persisted.
+
+---
+
+## Endpoints
+
+### GET /periomeasures
+
+**Version:** 22.4.32
+**Description:** Retrieves periomeasure records with optional filtering by exam.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PerioExamNum | integer | No | — | FK to perioexam.PerioExamNum; filter to a specific exam |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| PerioMeasureNum | integer | Primary key |
+| PerioExamNum | integer | FK to perioexam.PerioExamNum |
+| SequenceType | string | Type of measurement (enum) |
+| IntTooth | integer | Tooth number (1–32) |
+| ToothValue | integer | Single value for the whole tooth; -1 if not applicable |
+| MBvalue | integer | Mesial-buccal surface value; -1 if not applicable |
+| Bvalue | integer | Buccal surface value; -1 if not applicable |
+| DBvalue | integer | Distal-buccal surface value; -1 if not applicable |
+| MLvalue | integer | Mesial-lingual surface value; -1 if not applicable |
+| Lvalue | integer | Lingual surface value; -1 if not applicable |
+| DLvalue | integer | Distal-lingual surface value; -1 if not applicable |
+| SecDateTEdit | datetime | Last modification timestamp |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /periomeasures
+
+**Version:** 22.4.37
+**Description:** Creates a new periomeasure. New records are compared against existing records for the same exam and tooth to prevent duplicate SequenceType entries.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PerioExamNum | integer | Yes | FK to perioexam.PerioExamNum |
+| SequenceType | string | Yes | Measurement classification (enum) |
+| IntTooth | integer | Yes | Tooth number 1–32 |
+| ToothValue | integer | No | Whole-tooth measurement; default: -1 |
+| MBvalue | integer | No | Mesial-buccal surface value; default: -1 |
+| Bvalue | integer | No | Buccal surface value; default: -1 |
+| DBvalue | integer | No | Distal-buccal surface value; default: -1 |
+| MLvalue | integer | No | Mesial-lingual surface value; default: -1 |
+| Lvalue | integer | No | Lingual surface value; default: -1 |
+| DLvalue | integer | No | Distal-lingual surface value; default: -1 |
+
+**Response:** object — created periomeasure record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /periomeasures/{PerioMeasureNum}
+
+**Version:** 22.4.37
+**Description:** Updates measurement values on an existing periomeasure. Only value fields can be updated.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PerioMeasureNum | integer | Yes | Primary key |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ToothValue | integer | No | Updated whole-tooth measurement |
+| MBvalue | integer | No | Updated mesial-buccal surface value |
+| Bvalue | integer | No | Updated buccal surface value |
+| DBvalue | integer | No | Updated distal-buccal surface value |
+| MLvalue | integer | No | Updated mesial-lingual surface value |
+| Lvalue | integer | No | Updated lingual surface value |
+| DLvalue | integer | No | Updated distal-lingual surface value |
+
+**Response:** object — updated periomeasure record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /periomeasures/{PerioMeasureNum}
+
+**Version:** 23.3.27
+**Description:** Deletes a periomeasure. Only records with SequenceType "Mobility" or "SkipTooth" can be deleted.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PerioMeasureNum | integer | Yes | Primary key |
+
+**Response:** 200 OK
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### SequenceType (enum) with valid value ranges
+| Value | ToothValue | Surface Values (MB/B/DB/ML/L/DL) | Notes |
+|-------|------------|-----------------------------------|-------|
+| Mobility | 0–19 | Must all be -1 | Single value per tooth |
+| Furcation | Must be -1 | -1 or 0–19 | Per-surface furcation scores |
+| GingMargin | Must be -1 | -1, 0–19, or 101–119 | Values 101–119 represent negative (subtract 100) |
+| MGJ | Must be -1 | -1 or 0–19; MLvalue, Lvalue, DLvalue must be -1 for teeth 1–16 | Mucogingival junction |
+| Probing | Must be -1 | -1 or 0–19 | Standard probing depths |
+| SkipTooth | Must be 1 | Must all be -1 | Marks tooth as skipped |
+| BleedSupPlaqCalc | Must be -1 | 0–15 (bitfield sum) | bleeding=1, suppuration=2, plaque=4, calculus=8 |
+
+---
+
+## Implementation Notes
+
+- Sentinel value -1 means "not applicable" for any surface or tooth value field
+- Values greater than 100 represent negative values: subtract 100 to get the real value (e.g., 105 = -5mm gingival margin)
+- CAL (Clinical Attachment Level) = Probing + GingMargin; calculated only, never stored
+- Only one PerioMeasure per SequenceType per tooth per exam; POST checks for duplicates
+- DELETE is restricted to SequenceType "Mobility" and "SkipTooth" only
+- BleedSupPlaqCalc is a bitfield: values 0–15 are sums of bleeding (1), suppuration (2), plaque (4), calculus (8) flags
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| /perioexams | Parent exam that groups periomeasure records |

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

@@ -0,0 +1,78 @@
+# API: Pharmacies
+
+**Source:** https://www.opendental.com/site/apipharmacies.html
+**DB Schema Ref:** pharmacy
+**Extracted:** 2026-04-22
+**Base Path:** `/pharmacies`
+
+---
+
+## Overview
+
+Pharmacies stores individual pharmacy store records used when associating prescriptions with a dispensing location. Each record contains contact, address, and fax information. The `DateTStamp` field is system-managed and reflects the last modification time.
+
+---
+
+## Endpoints
+
+### GET /pharmacies/{PharmacyNum}
+
+**Version:** 24.2.35
+**Description:** Retrieves a single pharmacy record by primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PharmacyNum | integer | Yes | Primary key of the pharmacy |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| PharmacyNum | bigint | Primary key |
+| StoreName | varchar(255) | Pharmacy store name or common description |
+| Phone | varchar(255) | Phone number including all punctuation |
+| Fax | varchar(255) | Fax number including all punctuation |
+| Address | varchar(255) | Street address line 1 |
+| Address2 | varchar(255) | Street address line 2 (optional) |
+| City | varchar(255) | City |
+| State | varchar(255) | State abbreviation; two characters, uppercase |
+| Zip | varchar(255) | Postal code |
+| Note | text | Freeform notes (e.g., hours of operation) |
+| DateTStamp | datetime (timestamp) | Last modified date/time; not user-editable |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /pharmacies
+
+**Version:** 24.2.35
+**Description:** Retrieves all pharmacy records in the system as an array.
+
+**Response:** array of objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+## Implementation Notes
+
+- `DateTStamp` is automatically maintained by MySQL on insert/update and is not user-editable.
+- `State` is stored as a two-character uppercase abbreviation.
+- Phone and Fax fields store the full formatted string including punctuation.
+- The `PharmID` column (NCPDPID) exists in the DB schema but is not exposed in the API responses documented here.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| RxPats | Prescriptions that reference a PharmacyNum FK |

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

@@ -0,0 +1,127 @@
+# API: Popups
+
+**Source:** https://www.opendental.com/site/apipopups.html
+**DB Schema Ref:** popup
+**Extracted:** 2026-04-22
+**Base Path:** `/popups`
+
+---
+
+## Overview
+Popups are patient-facing alert messages that display when a patient is selected in Open Dental. They support Patient, Family, and SuperFamily levels and implement self-archiving: editing a popup's description creates an archived copy of the original before saving the change.
+
+---
+
+## Endpoints
+
+### GET /popups
+
+**Version:** 21.4
+**Description:** Retrieves active and disabled popups for a patient and associated Family and SuperFamily.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | Yes | — | Patient number to retrieve popups for |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| PopupNum | integer | Primary key |
+| PatNum | integer | FK to patient.PatNum |
+| Description | text | Popup message text |
+| IsDisabled | boolean | Deprecated in v22.2+; use DateTimeDisabled instead |
+| PopupLevel | string | "Patient", "Family", or "SuperFamily" (enum EnumPopupLevel) |
+| DateTimeEntry | string | Server creation timestamp (yyyy-MM-dd HH:mm:ss); does not change when level/IsDisabled changes, only when description changes |
+| IsArchived | boolean | True if this is an archived or "deleted" popup |
+| PopupNumArchive | integer | 0 for current popups; for archived popups, FK to parent popup's PopupNum |
+| DateTimeDisabled | string | Timestamp when popup disables (yyyy-MM-dd HH:mm:ss); "0001-01-01 00:00:00" means never disabled |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /popups
+
+**Version:** 21.1
+**Description:** Creates a new popup.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum |
+| Description | string | Yes | Popup message text |
+| PopupLevel | string | No | "Patient" (default), "Family", or "SuperFamily" |
+| DateTimeDisabled | string | No (v25.1.12+) | Disablement timestamp (yyyy-MM-dd HH:mm:ss); defaults to "0001-01-01 00:00:00" (never) |
+
+**Response:** object — created popup with all fields listed in GET response
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /popups/{PopupNum}
+
+**Version:** 25.1.12
+**Description:** Updates an existing popup. Modifying Description triggers self-archiving: a copy of the original is archived before the update is applied.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PopupNum | integer | Yes | Primary key of the popup to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Description | string | No | New popup message text |
+| PopupLevel | string | No | "Patient", "Family", or "SuperFamily" |
+| DateTimeDisabled | string | No | Disablement timestamp (yyyy-MM-dd HH:mm:ss) |
+
+**Response:** object — updated popup with all fields listed in GET response
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### PopupLevel (enum: EnumPopupLevel)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Patient | 0 | Popup applies to the individual patient |
+| Family | 1 | Popup applies to the entire family |
+| SuperFamily | 2 | Popup applies to the entire superfamily |
+| Automation | 3 | Not stored in DB; used only as a temporary display object in FormPopupsForFam |
+
+---
+
+## Implementation Notes
+- Popups tend to be annoying to users and are typically reserved for important notes.
+- Editing the Description field triggers automatic self-archiving: a copy of the existing popup is created as an archive before saving the update.
+- Archived or "deleted" popups have `IsArchived = true`; `IsArchived = false` indicates the current active popup.
+- `PopupNumArchive` is 0 for current popups; archived popups point to their parent popup.
+- `IsDisabled` is deprecated as of v22.2; use `DateTimeDisabled` instead.
+- `DateTimeDisabled` sentinel value "0001-01-01 00:00:00" means the popup will never be automatically disabled.
+- `UserNum` (FK to userod.UserNum) is stored in the DB but is not returned in the API response.
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| /patients | Retrieve PatNum values for popup queries |

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

@@ -0,0 +1,47 @@
+# API: Preferences
+
+**Source:** https://www.opendental.com/site/apipreferences.html
+**DB Schema Ref:** preference
+**Extracted:** 2026-04-22
+**Base Path:** `/preferences`
+
+---
+
+## Overview
+Preferences store small configuration values for the practice across a wide variety of purposes. Each preference is a key/value pair identified by `PrefName`. There are approximately 1,000 preferences; any data too small to warrant its own table is typically stored here.
+
+---
+
+## Endpoints
+
+### GET /preferences
+
+**Version:** 21.1
+**Description:** Retrieves one or more preference records. When no `PrefName` is specified, returns all preferences paginated.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PrefName | string | No | — | Filter for a specific preference by name (e.g., "RecallDaysPast"). Omit to return all preferences. |
+| Offset | integer | No | 0 | Pagination offset (e.g., Offset=200 to skip first 200 records) |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| PrefNum | integer | Primary key (not used for querying; all queries use PrefName) |
+| PrefName | varchar(255) | The preference name (key) |
+| ValueString | text | The preference value stored as a string |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+## Implementation Notes
+- All preference values are stored and returned as strings regardless of their underlying data type; callers must parse as needed.
+- Omitting `PrefName` returns all ~1,000 preferences; use `Offset` for pagination.
+- `PrefNum` is a primary key in the database but is not used for queries — always reference preferences by `PrefName`.
+- The `Comments` column in the DB is mostly deprecated in favor of XML code comments; it is not returned in the API response.
+- Consult the Preference Database Schema for details on individual preference names and their valid values.