@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,171 @@
+# API: InsSubs
+
+**Source:** https://www.opendental.com/site/apiinssubs.html
+**DB Schema Ref:** inssub
+**Extracted:** 2026-04-22
+**Base Path:** `/inssubs`
+
+---
+
+## Overview
+
+InsSubs links an insurance plan (InsPlan) to a subscriber (patient). Multiple subscribers can share the same insurance plan. The PatPlan table determines actual coverage for individual family members. InsSubs manages the subscriber-level relationship including subscriber ID, effective dates, and benefit assignment flags.
+
+---
+
+## Endpoints
+
+### GET /inssubs/{InsSubNum}
+
+**Version:** 22.4.28
+**Description:** Retrieves a single insurance subscription record by its primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| InsSubNum | integer | Yes | Insurance subscription primary key |
+
+**Response:** Single object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| InsSubNum | integer | Primary key |
+| PlanNum | integer | FK to insplan.PlanNum |
+| Subscriber | integer | FK to patient.PatNum — the subscribing patient |
+| DateEffective | string | Plan effective date (yyyy-MM-dd); "0001-01-01" if not set |
+| DateTerm | string | Plan termination date (yyyy-MM-dd); "0001-01-01" if not set |
+| SubscriberID | string | Number assigned by insurance company; no dashes; cannot be blank |
+| BenefitNotes | string | Automated benefit notes (subscriber-specific; may show another subscriber's notes if blank) |
+| ReleaseInfo | string | "true" or "false" — release of information signature on file |
+| AssignBen | string | "true" or "false" — assignment of benefits signature on file |
+| SubscNote | string | Additional coverage information |
+| SecDateTEdit | string | Last modified timestamp (auto-updated by MySQL) |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### GET /inssubs
+
+**Version:** 22.4.28
+**Description:** Retrieves a list of insurance subscription records with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PlanNum | integer | No | — | Filter by insurance plan |
+| Subscriber | integer | No | — | Filter by patient (PatNum) |
+| SecDateTEdit | string | No | — | Returns records modified on or after this date |
+
+**Response:** Array of objects with same fields as single GET
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /inssubs
+
+**Version:** 21.1
+**Description:** Creates a new insurance subscription, linking a plan to a subscriber patient.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PlanNum | integer | Yes | FK to insplan.PlanNum |
+| Subscriber | integer | Yes | FK to patient.PatNum |
+| SubscriberID | string | Yes | Insurance company-assigned number (no dashes) |
+| DateEffective | string | No | Plan effective date (yyyy-MM-dd) |
+| DateTerm | string | No | Plan termination date (yyyy-MM-dd) |
+| BenefitNotes | string | No | Automated benefit notes (version 21.1+) |
+| ReleaseInfo | string | No | "true"/"false"; default "true" (added 21.4) |
+| AssignBen | string | No | "true"/"false" (added 21.4) |
+| SubscNote | string | No | Additional coverage info (added 22.4.26) |
+
+**Response:** Complete InsSub object including assigned `InsSubNum` and auto-generated `SecDateTEdit`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+
+---
+
+### PUT /inssubs/{InsSubNum}
+
+**Version:** 21.1
+**Description:** Updates an existing insurance subscription. `SecDateTEdit` is updated automatically and cannot be set by developers.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| InsSubNum | integer | Yes | Insurance subscription primary key |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PlanNum | integer | No | Change associated insurance plan |
+| Subscriber | integer | No | Change subscriber patient (added 21.4) |
+| SubscriberID | string | No | Insurance company-assigned number (added 21.4) |
+| DateEffective | string | No | Plan effective date (added 21.4) |
+| DateTerm | string | No | Plan termination date (added 21.4) |
+| BenefitNotes | string | No | Automated benefit notes |
+| ReleaseInfo | string | No | "true"/"false" |
+| AssignBen | string | No | "true"/"false" |
+| SubscNote | string | No | Additional coverage info (added 22.4.26) |
+
+**Response:** 200 OK
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /inssubs/{InsSubNum}
+
+**Version:** 21.1
+**Description:** Deletes an insurance subscription. Will fail if any PatPlans reference this InsSub.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| InsSubNum | integer | Yes | Insurance subscription primary key |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+
+---
+
+## Implementation Notes
+
+- DELETE will fail if any PatPlan records exist referencing this InsSub.
+- `SecDateTEdit` is automatically updated by MySQL and cannot be set by developers.
+- `DateEffective` and `DateTerm` are stored as "0001-01-01" when not set (sentinel value).
+- `BenefitNotes` are subscriber-specific; if blank, the UI may display notes from another subscriber on the same plan.
+- Updating `PlanNum` or `Subscriber` does not affect associated PatPlans or family member coverage.
+- To obtain `InsSubNum` for delete/update operations, retrieve it via the FamilyModules GET Insurance endpoint.
+- This API creates subscriber-to-plan links only; it does not create insurance plans or modify benefits.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /insplans | The insurance plan being subscribed to |
+| /insverifies | Verification records for enrollment/benefits |

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

@@ -0,0 +1,123 @@
+# API: InsVerifies
+
+**Source:** https://www.opendental.com/site/apiinsverifies.html
+**DB Schema Ref:** insverify
+**Extracted:** 2026-04-22
+**Base Path:** `/insverifies`
+
+---
+
+## Overview
+
+InsVerifies tracks the most recent insurance verification for each insurance plan (benefit verification) or patient plan enrollment (eligibility verification). Each record represents the current verification state; historical entries are always retained in the `insverifyhist` table. A new row with no date is created automatically when a new plan is created.
+
+---
+
+## Endpoints
+
+### GET /insverifies/{InsVerifyNum}
+
+**Version:** 23.2.23
+**Description:** Retrieves a single insurance verification record by its primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| InsVerifyNum | integer | Yes | Insurance verification primary key |
+
+**Response:** Single object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| InsVerifyNum | integer | Primary key |
+| DateLastVerified | string | Date of last successful verification (yyyy-MM-dd); DateTime.MinVal if never verified |
+| UserNum | integer | FK to userod.UserNum — assigned verifying user (typically 0) |
+| VerifyType | string | "PatientEnrollment" or "InsuranceBenefit" |
+| FKey | integer | FK to patplan.PatPlanNum (if PatientEnrollment) or insplan.PlanNum (if InsuranceBenefit) |
+| DefNum | integer | FK to definition.DefNum where Category=38 — verification status |
+| Note | string | Status note for this verification |
+| DateLastAssigned | string | DateTime when a user was last assigned/unassigned (yyyy-MM-dd); DateTime.MinVal if never assigned |
+| SecDateTEdit | string | Last modified timestamp (yyyy-MM-dd HH:mm:ss) |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /insverifies
+
+**Version:** 23.2.23
+**Description:** Retrieves multiple insurance verification records with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| VerifyType | string | No* | — | "PatientEnrollment" or "InsuranceBenefit"; required if FKey is specified |
+| FKey | integer | No | — | FK to patplan.PatPlanNum or insplan.PlanNum depending on VerifyType (added 24.4.17) |
+| SecDateTEdit | string | No | — | Returns records modified after this timestamp (yyyy-MM-dd HH:mm:ss) |
+
+**Response:** Array of objects with same fields as single GET
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+
+---
+
+### PUT /insverifies
+
+**Version:** 21.1
+**Description:** Updates an insurance verification record. Historical entries are always retained in the insverifyhist table. There is no path parameter — the record is identified by `VerifyType` + `FKey` in the body.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| VerifyType | string | Yes | "PatientEnrollment" or "InsuranceBenefit" |
+| FKey | integer | Yes | FK to patplan.PatPlanNum (PatientEnrollment) or insplan.PlanNum (InsuranceBenefit) |
+| DateLastVerified | string | No* | Date to set as last verified (yyyy-MM-dd); optional after version 24.1.17 |
+| DefNum | integer | No | FK to definition.DefNum where Category=38 — verification status |
+| Note | string | No | Status note (added 24.1.17) |
+
+**Response:** Single updated InsVerify object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+
+---
+
+## Field Reference
+
+### VerifyType (enum: VerifyTypes)
+
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | No type — FKey should be 0 |
+| InsuranceBenefit | 1 | Benefits verification — FKey links to insplan.PlanNum |
+| PatientEnrollment | 2 | Enrollment/eligibility verification — FKey links to patplan.PatPlanNum |
+
+---
+
+## Implementation Notes
+
+- PUT uses `VerifyType` + `FKey` in the body to identify the record (not a path parameter with InsVerifyNum).
+- Every PUT creates a historical copy in the `insverifyhist` table; the current record is updated in-place.
+- `DateLastVerified` is DateTime.MinVal (displayed as "0001-01-01") when a plan is newly created and never verified.
+- `DateLastAssigned` is DateTime.MinVal when no user has ever been assigned.
+- `DefNum` must reference a definition where `definition.Category` = 38 (InsVerifyStatus).
+- `UserNum` is typically 0; it is only populated when the optional user-assignment feature is in use.
+- `FKey` is required when specifying `VerifyType` in GET query parameters.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /insplans | Insurance plans referenced by FKey when VerifyType=InsuranceBenefit |
+| /inssubs | Subscriber records linked to plans being verified |

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

@@ -0,0 +1,174 @@
+# API: LabCases
+
+**Source:** https://www.opendental.com/site/apilabcases.html
+**Extracted:** 2026-04-22
+**Base Path:** `/labcases`
+
+---
+
+## Overview
+The LabCases API manages dental lab case records linking patients, laboratories, and appointments. It tracks the lifecycle of lab work from creation through receipt and quality check.
+
+---
+
+## Endpoints
+
+### GET /labcases/{LabCaseNum}
+
+**Version:** 24.2.28
+**Description:** Retrieves a single lab case record by its unique identifier.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LabCaseNum | integer | Yes | Unique lab case identifier |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| LabCaseNum | integer | Unique identifier |
+| PatNum | integer | FK to patient |
+| LaboratoryNum | integer | FK to laboratory |
+| AptNum | integer | FK to scheduled appointment |
+| PlannedAptNum | integer | FK to planned appointment |
+| DateTimeDue | datetime | Due date for lab slip |
+| DateTimeCreated | datetime | Creation timestamp |
+| DateTimeSent | datetime | Sent to lab timestamp |
+| DateTimeRecd | datetime | Received from lab timestamp |
+| DateTimeChecked | datetime | Quality check timestamp |
+| ProvNum | integer | FK to provider |
+| Instructions | string | Lab work instructions |
+| LabFee | decimal | Informational fee only; does not affect calculations |
+| DateTStamp | datetime | Database timestamp (system-generated) |
+| InvoiceNum | string | Optional tracking number |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /labcases
+
+**Version:** 24.2.28
+**Description:** Retrieves multiple lab case records with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | No | — | Filter by patient |
+| LaboratoryNum | integer | No | — | Filter by laboratory |
+| AptNum | integer | No | — | Filter by scheduled appointment |
+| PlannedAptNum | integer | No | — | Filter by planned appointment |
+| ProvNum | integer | No | — | Filter by provider |
+
+**Response:** array of objects (same fields as GET single)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /labcases
+
+**Version:** 24.4.19
+**Description:** Creates a new lab case record.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient |
+| LaboratoryNum | integer | Yes | FK to laboratory |
+| ProvNum | integer | Yes | FK to provider |
+| AptNum | integer | No | FK to appointment; must have AptStatus=Scheduled |
+| PlannedAptNum | integer | No | FK to planned appointment; must have AptStatus=Planned |
+| DateTimeDue | datetime | No | Due date/time (format: "yyyy-MM-dd HH:mm:ss") |
+| DateTimeCreated | datetime | No | Creation timestamp (format: "yyyy-MM-dd HH:mm:ss") |
+| DateTimeSent | datetime | No | Sent to lab timestamp (format: "yyyy-MM-dd HH:mm:ss") |
+| DateTimeRecd | datetime | No | Received from lab timestamp (format: "yyyy-MM-dd HH:mm:ss") |
+| DateTimeChecked | datetime | No | Quality check timestamp (format: "yyyy-MM-dd HH:mm:ss") |
+| Instructions | string | No | Lab work instructions |
+| LabFee | decimal | No | Informational/tracking fee only |
+| InvoiceNum | string | No | Optional tracking number |
+
+**Response:** object — created lab case with all fields including generated `LabCaseNum`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /labcases/{LabCaseNum}
+
+**Version:** 24.4.19
+**Description:** Updates an existing lab case record. `PatNum` and `LaboratoryNum` are immutable after creation.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LabCaseNum | integer | Yes | Lab case identifier |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| AptNum | integer | No | FK to scheduled appointment |
+| PlannedAptNum | integer | No | FK to planned appointment |
+| DateTimeDue | datetime | No | Due date/time (format: "yyyy-MM-dd HH:mm:ss") |
+| DateTimeCreated | datetime | No | Creation timestamp |
+| DateTimeSent | datetime | No | Sent to lab timestamp |
+| DateTimeRecd | datetime | No | Received from lab timestamp |
+| DateTimeChecked | datetime | No | Quality check timestamp |
+| ProvNum | integer | No | FK to provider |
+| Instructions | string | No | Lab work instructions |
+| LabFee | decimal | No | Informational fee only |
+| InvoiceNum | string | No | Tracking number |
+
+**Response:** object — updated lab case with all fields
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /labcases/{LabCaseNum}
+
+**Version:** 24.4.19
+**Description:** Removes a lab case record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LabCaseNum | integer | Yes | Lab case identifier |
+
+**Response:** 200 OK (no body)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+- `PatNum` and `LaboratoryNum` cannot be changed after creation via PUT.
+- `AptNum` must reference an appointment with AptStatus=Scheduled.
+- `PlannedAptNum` must reference an appointment with AptStatus=Planned.
+- `LabFee` and `InvoiceNum` are informational only and do not affect billing calculations.
+- `DateTStamp` is system-generated and returned in responses; do not set it in POST/PUT.
+- All datetime fields use format: `yyyy-MM-dd HH:mm:ss`.

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

@@ -0,0 +1,147 @@
+# API: Laboratories
+
+**Source:** https://www.opendental.com/site/apilaboratories.html
+**DB Schema Ref:** laboratory
+**Extracted:** 2026-04-22
+**Base Path:** `/laboratories`
+
+---
+
+## Overview
+
+Laboratories represents dental lab partners associated with lab cases. Each laboratory record stores contact information, address details, and a reference to a custom lab slip sheet definition. Labs can be marked hidden (inactive) without being deleted.
+
+---
+
+## Endpoints
+
+### GET /laboratories/{LaboratoryNum}
+
+**Version:** 24.2.33
+**Description:** Retrieves a single laboratory record by primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LaboratoryNum | integer | Yes | Primary key of the laboratory |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| LaboratoryNum | integer | Primary key |
+| Description | varchar(255) | Laboratory name/description |
+| Phone | varchar(255) | Contact phone number; freeform including punctuation |
+| Notes | text | Additional notes; no practical length limit |
+| Slip | bigint | FK to sheetdef.SheetDefNum; 0 = use default internal lab slip |
+| Address | varchar(255) | Street address |
+| City | varchar(255) | City |
+| State | varchar(255) | State (US) or province (Canada) |
+| Zip | varchar(255) | Postal code |
+| Email | varchar(255) | Email address |
+| WirelessPhone | varchar(255) | Additional contact phone number |
+| IsHidden | boolean (tinyint) | True if laboratory is inactive/hidden |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /laboratories
+
+**Version:** 24.2.33
+**Description:** Retrieves all laboratory records as an array.
+
+**Response:** array of objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+### POST /laboratories
+
+**Version:** 24.4.22
+**Description:** Creates a new laboratory record.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Description | string | Yes | Laboratory name |
+| Phone | string | No | Contact phone number |
+| Notes | string | No | Additional notes |
+| Slip | integer | No | FK to sheetdef.SheetDefNum; default 0 (uses default internal lab slip) |
+| Address | string | No | Street address |
+| City | string | No | City |
+| State | string | No | State/province code |
+| Zip | string | No | Postal code; US formats: 12345, 12345-1234, 123456789; Canada: A0A 0A0 |
+| Email | string | No | Email address |
+| WirelessPhone | string | No | Additional phone number |
+| IsHidden | string | No | "true" to mark inactive; default "false" |
+
+**Response:** object — complete laboratory record with assigned LaboratoryNum
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /laboratories/{LaboratoryNum}
+
+**Version:** 24.4.23
+**Description:** Updates an existing laboratory record. All body fields are optional.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LaboratoryNum | integer | Yes | Primary key of the laboratory to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Description | string | No | Laboratory name |
+| Phone | string | No | Contact phone number |
+| Notes | string | No | Overwrites existing notes entirely |
+| Slip | integer | No | FK to sheetdef.SheetDefNum |
+| Address | string | No | Street address |
+| City | string | No | City |
+| State | string | No | State/province code |
+| Zip | string | No | Postal code |
+| Email | string | No | Email address |
+| WirelessPhone | string | No | Additional phone number |
+| IsHidden | string | No | "true" to mark inactive |
+
+**Response:** object — updated laboratory record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+
+- `Slip` = 0 means the default internal lab slip is used rather than a custom sheet definition.
+- `Notes` on PUT overwrites the entire existing value; perform a GET first if appending is desired.
+- `IsHidden` is stored as tinyint(4) in the DB; pass as string "true"/"false" in the API.
+- Zip format validation enforces US (12345, 12345-1234, 123456789) and Canada (A0A 0A0) patterns on POST.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| LabTurnarounds | Turnaround time entries attached to a laboratory |
+| SheetDef | Custom lab slip sheet definitions (Slip FK target) |