@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,132 @@
+# API: EobAttaches
+
+**Source:** https://www.opendental.com/site/apieobattaches.html
+**Extracted:** 2026-04-22
+**Base Path:** `/eobattaches`
+
+---
+
+## Overview
+The EobAttaches API manages Explanation of Benefits (EOB) attachment files linked to claim payments. It supports retrieving EOB files, downloading them to an SFTP server, uploading EOB files from SFTP into the system, and deleting attachments.
+
+---
+
+## Endpoints
+
+### GET /eobattaches
+
+**Version:** 23.3.8
+**Description:** Retrieves a list of EOB attachments for a specified claim payment.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| ClaimPaymentNum | integer | Yes | — | FK to claimpayment; identifies the claim payment whose attachments are retrieved |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| EobAttachNum | integer | Unique identifier |
+| ClaimPaymentNum | integer | FK to claim payment |
+| DateTCreated | datetime | Creation timestamp |
+| FileName | string | Name of the attachment file |
+| RawBase64 | string | Base64-encoded file content |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /eobattaches/DownloadSftp
+
+**Version:** 23.3.12
+**Description:** Exports an EOB attachment to a specified SFTP location.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EobAttachNum | integer | Yes | FK to the EOB attachment to export |
+| SftpAddress | string | Yes | Full file path on the SFTP server using forward slashes |
+| SftpUsername | string | Yes | SFTP authentication username |
+| SftpPassword | string | Yes | SFTP authentication password |
+| SftpPort | integer | No | SFTP port; default 22 (added v25.4.45) |
+
+**Response:** string — full filepath of the saved file on the SFTP server
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /eobattaches/UploadSftp
+
+**Version:** 24.3.7
+**Description:** Imports an EOB file from an SFTP server into the system's storage, creating a new EobAttach record.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ClaimPaymentNum | integer | Yes | FK to claim payment to associate the uploaded file with |
+| SftpAddress | string | Yes | Full file path on the SFTP server using forward slashes |
+| SftpUsername | string | Yes | SFTP authentication username |
+| SftpPassword | string | Yes | SFTP authentication password |
+| SftpPort | integer | No | SFTP port; default 22 (added v25.4.45) |
+
+**Response:** object — newly created EobAttach record
+| Field | Type | Description |
+|-------|------|-------------|
+| EobAttachNum | integer | Unique identifier of the new record |
+| ClaimPaymentNum | integer | FK to claim payment |
+| DateTCreated | datetime | Creation timestamp |
+| FileName | string | Name of the imported file |
+| RawBase64 | string | Base64-encoded file content |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /eobattaches/{EobAttachNum}
+
+**Version:** 25.2.25
+**Description:** Removes an EOB attachment record and its associated file.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EobAttachNum | integer | Yes | EOB attachment to delete |
+
+**Response:** 200 OK (no body)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+- `ClaimPaymentNum` is required for GET; requests without it return 400 BadRequest.
+- `SftpAddress` must use forward slashes for path separators regardless of platform.
+- `SftpPort` parameter was added to both SFTP endpoints in version 25.4.45; prior versions use port 22 exclusively.
+- DELETE removes both the database record and the associated file from storage.
+- `RawBase64` in GET responses contains the full Base64-encoded file content; large EOB files may produce large response payloads.
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| ClaimPayments | Claim payment records that EOB attachments are linked to |

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

@@ -0,0 +1,44 @@
+# API: Etrans
+
+**Source:** https://www.opendental.com/site/apietrans.html
+**Extracted:** 2026-04-22
+**Base Path:** `/etrans`
+
+---
+
+## Overview
+
+Etrans manages electronic transaction records in Open Dental. This resource currently supports creating ERA 835 electronic remittance advice transactions for insurance payment processing.
+
+---
+
+## Endpoints
+
+### POST /etrans
+
+**Version:** 21.2
+**Description:** Creates one Etrans record of the type ERA 835.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| DateTimeTrans | string | Yes | Transaction timestamp |
+| HqClearinghouseNum | integer | Yes | Clearinghouse identifier |
+| MessageText | string | Yes | ERA 835 EDI message content (must begin with "ISA" segment) |
+| UserNum | integer | Yes | User identifier |
+
+**Response:** 201 Created — no response object or Location header returned
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+
+---
+
+## Implementation Notes
+
+- This endpoint specifically handles ERA 835 transaction types only.
+- The `MessageText` field must contain the full EDI X12 message beginning with the ISA segment.
+- No response body or Location header is returned on successful creation.
+- GET single is not supported for this resource.

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

@@ -0,0 +1,56 @@
+# API: EtransMessageTexts
+
+**Source:** https://www.opendental.com/site/apietransmessagetexts.html
+**DB Schema Ref:** etransmessagetext
+**Extracted:** 2026-04-22
+**Base Path:** `/etransmessagetexts`
+
+---
+
+## Overview
+
+EtransMessageTexts stores the full X12 EDI message text associated with electronic transactions (etrans). Each row holds a complete message, which can be shared across multiple etrans records since the messages can be very large. Use this resource to retrieve the raw EDI message text for a given transaction.
+
+---
+
+## Endpoints
+
+### GET /etransmessagetexts/{EtransMessageTextNum}
+
+**Version:** 23.2.11
+**Description:** Retrieves a single EtransMessageText record containing the full EDI message.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EtransMessageTextNum | integer | Yes | Message text identifier |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| EtransMessageTextNum | integer | Primary key (bigint) |
+| MessageText | string | Full X12 EDI message text, including carriage returns (mediumtext) |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest — with explanation |
+| 404 | NotFound — with explanation |
+
+---
+
+## Implementation Notes
+
+- The `MessageText` field stores the entire X12 EDI message including carriage returns; it is of type mediumtext and can be very large.
+- A single EtransMessageText record may be referenced by multiple etrans records (shared storage pattern).
+- Refer to the Etrans Edit documentation for context on how message texts relate to electronic transactions.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /etranss | Electronic transactions that reference EtransMessageTextNum |
+| /etrans | Create ERA 835 transactions |

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

@@ -0,0 +1,79 @@
+# API: Etranss
+
+**Source:** https://www.opendental.com/site/apietranss.html
+**Extracted:** 2026-04-22
+**Base Path:** `/etranss`
+
+---
+
+## Overview
+
+Etranss retrieves electronic transaction records for a patient. These records represent X12 EDI transactions such as ERA 835 remittance advice, associated with insurance claims and carriers. This is a read-only resource.
+
+---
+
+## Endpoints
+
+### GET /etranss
+
+**Version:** 23.2.7
+**Description:** Retrieves all electronic transaction records for a patient, with optional filtering by carrier or claim.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | Yes | — | Patient identifier |
+| CarrierNum | integer | No | — | FK to Carrier.CarrierNum — filter by carrier |
+| ClaimNum | integer | No | — | FK to Claim.ClaimNum — filter by claim |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| EtransNum | integer | Primary key — electronic transaction identifier |
+| DateTimeTrans | datetime | Transaction timestamp |
+| ClearingHouseNum | integer | Clearinghouse reference |
+| Etype | string | Transaction type (e.g., "ERA_835") |
+| ClaimNum | integer | FK to Claim — associated claim reference |
+| OfficeSequenceNumber | integer | Office sequence identifier |
+| CarrierTransCounter | integer | Carrier counter value |
+| CarrierTransCounter2 | integer | Secondary carrier counter |
+| CarrierNum | integer | FK to Carrier — primary carrier identifier |
+| CarrierNum2 | integer | Secondary carrier identifier |
+| PatNum | integer | Patient identifier |
+| BatchNumber | integer | Batch processing number |
+| AckCode | string | Acknowledgment code |
+| TransSetNum | integer | Transaction set number |
+| Note | string | Additional notes |
+| EtransMessageTextNum | integer | FK to EtransMessageText — full EDI message reference |
+| AckEtransNum | integer | FK to Etrans — acknowledgment transaction reference |
+| PlanNum | integer | Insurance plan identifier |
+| InsSubNum | integer | Insurance subscriber number |
+| TransSetId835 | integer | Transaction set 835 identifier |
+| CarrierNameRaw | string | Raw carrier name from the EDI message |
+| PatientNameRaw | string | Raw patient name from the EDI message |
+| UserNum | integer | User identifier |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest — with explanation |
+| 404 | NotFound — with explanation |
+
+---
+
+## Implementation Notes
+
+- `PatNum` is required; `CarrierNum` and `ClaimNum` are optional additional filters.
+- `EtransMessageTextNum` is a foreign key to the EtransMessageTexts resource for retrieving the full X12 EDI message body.
+- `CarrierNum` in query parameters is a FK to `Carrier.CarrierNum`.
+- `ClaimNum` in query parameters is a FK to `Claim.ClaimNum`.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /etransmessagetexts | Retrieve full EDI message text by EtransMessageTextNum |
+| /etrans | Create ERA 835 transactions |

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

@@ -0,0 +1,96 @@
+# API: Events
+
+**Source:** https://www.opendental.com/site/apievents.html
+**Extracted:** 2026-04-22
+**Base Path:** `/events` *(webhook/subscription-based; see Subscriptions API)*
+
+---
+
+## Overview
+
+API Events are webhooks — reverse REST calls sent by Open Dental to a caller-specified endpoint. Two categories exist: Database Events (polling-based, fire per configured interval) and UI Events (fire instantly on user action). Events are configured via the Subscriptions resource.
+
+---
+
+## Event Architecture
+
+### Setup Workflow
+1. Subscribe to events via `POST /subscriptions`.
+2. Monitor the specified `EndPointUrl` for incoming event payloads.
+3. Database Events fire per `PollingSeconds` interval; UI Events fire instantly.
+4. Manage existing subscriptions with GET, PUT, DELETE operations on `/subscriptions`.
+
+### Common Event Headers
+All events include the following HTTP headers:
+
+| Header | Description | Version Added |
+|--------|-------------|---------------|
+| Authorization | Customer API Key | — |
+| Workstation | Machine name of the sending workstation | 22.4.28 |
+| Event-Type | Event type identifier string | 22.4.35 |
+
+---
+
+## Database Events
+
+**Characteristics:**
+- Generated by Open Dental and the API Service via database polling.
+- Maximum capacity of 1000 elements per event payload; larger changesets batch automatically into multiple deliveries.
+- `DateTimeStart` updates upon successful delivery to the endpoint.
+- Changes are retained for up to 72 hours if the endpoint is unreachable.
+- Inactive workstations do not poll.
+
+**Supported Watch Table Types:**
+
+| Watch Type | Description | Version Added |
+|------------|-------------|---------------|
+| Appointment | Appointment record changes | — |
+| AppointmentDeleted | Appointment deletions | 22.4.35 |
+| LabCase | Lab case changes | 25.4.14 |
+| LabCaseDeleted | Lab case deletions | 26.1.6 |
+| MedicationPat | Patient medication changes | 25.4.14 |
+| MedicationPatDeleted | Patient medication deletions | 26.1.9 |
+| Operatory | Operatory record changes | 24.2.11 |
+| Patient | Patient record changes | — |
+| Provider | Provider record changes | 24.2.11 |
+| PatField | Patient field changes | 22.4.8 |
+| PatFieldDeleted | Patient field deletions | 26.1.12 |
+| Schedule | Schedule record changes | 24.2.11 |
+| ScheduleDeleted | Schedule deletions | 26.1.1 |
+| ToothInitial | Tooth initial condition changes | 24.4.30 |
+
+**Response Format:** JSON array of modified records for the watched table.
+
+---
+
+## UI Events
+
+**Characteristics:**
+- Fire immediately upon user action in the Open Dental UI.
+- Typically target localhost endpoints.
+
+**Supported UI Event Types:**
+
+| Event Type | Trigger |
+|------------|---------|
+| PatientSelected | Fires when a patient is selected in the UI |
+
+**Response Format:** JSON object with relevant entity fields and timestamp/status.
+
+---
+
+## Implementation Notes
+
+- Events are configured and managed through the Subscriptions API, not through direct `/events` endpoints.
+- Database Event payloads are capped at 1000 elements; batching occurs automatically for larger changesets.
+- Endpoint reliability: Open Dental retains undelivered events for up to 72 hours and retries delivery.
+- The `Workstation` header (added in v22.4.28) identifies which machine sent the event, useful in multi-workstation environments.
+- The `Event-Type` header (added in v22.4.35) identifies the event type for routing logic in the receiving endpoint.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /subscriptions | Create and manage webhook subscriptions that drive event delivery |

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

@@ -0,0 +1,108 @@
+# API: FamilyModules
+
+**Source:** https://www.opendental.com/site/apifamilymodules.html
+**Extracted:** 2026-04-22
+**Base Path:** `/familymodules`
+
+---
+
+## Overview
+
+FamilyModules provides insurance information for a patient as displayed in Open Dental's Family Module. It returns 0–2 rows per patient (one per active insurance plan — primary and/or secondary). Discount plan subscriptions are handled separately via the DiscountPlanSubs resource.
+
+---
+
+## Endpoints
+
+### GET /familymodules/{PatNum}/Insurance
+
+**Version:** 21.4
+**Description:** Retrieves insurance information for a patient as shown in the Family Module.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | Patient number |
+
+**Response:** array of objects (typically 0–2 rows)
+| Field | Type | Description |
+|-------|------|-------------|
+| PatNum | integer | Patient number |
+| InsSubNum | integer | Primary key to insurance subscriber (inssub) |
+| Subscriber | integer | PatNum of the subscriber |
+| subscriber | string | Subscriber's first and last name |
+| SubscriberID | string | Insurance company-assigned subscriber number (may be Medicaid ID) |
+| SubscNote | string | Additional notes affecting coverage |
+| PatPlanNum | integer | Primary key to patient plan (patplan) |
+| Ordinal | integer | Numerical insurance order (1, 2, 3, etc.) |
+| ordinal | string | Insurance order description: "Primary", "Secondary", "Medical", or "Other" |
+| IsPending | boolean | True if insurance information is incomplete or unverified |
+| Relationship | string | Subscriber relationship (see enum below) |
+| PatID | string | Optional patient ID that overrides SubscriberID on electronic claims |
+| CarrierNum | integer | Primary key to carrier |
+| CarrierName | string | Full carrier name |
+| PlanNum | integer | Primary key to insurance plan (insplan) |
+| GroupName | string | Plan group name (typically employer-related) |
+| GroupNum | string | Carrier-issued group number |
+| PlanNote | string | Subscriber and family-specific plan notes |
+| FeeSched | integer | FK to fee schedule |
+| feeSchedule | string | Fee schedule description |
+| PlanType | string | Plan type code (see enum below) |
+| planType | string | Plan type description |
+| CopayFeeSched | integer | FK to copay fee schedule |
+| EmployerNum | integer | FK to employer |
+| employer | string | Employer name |
+| IsMedical | boolean | True if this is a medical (not dental) insurance plan |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest — with explanation |
+| 404 | NotFound — with explanation |
+
+---
+
+## Field Reference
+
+### Relationship (enum)
+| Value | Description |
+|-------|-------------|
+| Self | Patient is the subscriber |
+| Spouse | Spouse of the subscriber |
+| Child | Child of the subscriber |
+| Employee | Employee of the subscriber |
+| HandicapDep | Handicapped dependent |
+| SignifOther | Significant other |
+| InjuredPlaintiff | Injured plaintiff |
+| LifePartner | Life partner |
+| Dependant | Other dependent |
+
+### PlanType (enum)
+| Value (PlanType code) | planType Description |
+|----------------------|----------------------|
+| "" (empty string) | Category Percentage |
+| p | PPO Percentage |
+| f | PPO Fixed Benefit / Flat Co-pay |
+| c | Capitation |
+| *(Medicaid)* | Medicaid |
+
+---
+
+## Implementation Notes
+
+- Returns 0–2 rows per patient (one per insurance plan ordered by Ordinal).
+- Discount plan subscriptions are not returned here; use `GET /discountplansubs?PatNum={PatNum}` instead.
+- `PatID` overrides `SubscriberID` on electronic claims when populated.
+- `IsPending` signals that insurance data is incomplete or awaiting verification.
+- `ordinal` (lowercase) is the human-readable description of `Ordinal` (integer).
+- `planType` (lowercase) is the human-readable description of `PlanType` (code).
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /discountplansubs | Retrieve discount plan subscriptions for a patient |
+| /employers | Look up employer details by EmployerNum |

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

@@ -0,0 +1,146 @@
+# API: Fees
+
+**Source:** https://www.opendental.com/site/apifees.html
+**Extracted:** 2026-04-22
+**Base Path:** `/fees`
+
+---
+
+## Overview
+The Fees API manages fee records associated with fee schedules and procedure codes. Fees can be global or scoped to specific clinics and/or providers. Supports full CRUD operations.
+
+---
+
+## Endpoints
+
+### GET /fees/{FeeNum}
+
+**Version:** 23.3.11
+**Description:** Retrieves a single fee record by its unique identifier.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| FeeNum | integer | Yes | Unique fee identifier |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| FeeNum | integer | Fee identifier |
+| Amount | decimal | Charged amount |
+| FeeSched | integer | Fee schedule reference (FK to feesched) |
+| CodeNum | integer | Procedure code reference (FK to procedurecode) |
+| ClinicNum | integer | Clinic reference; 0 for global |
+| ProvNum | integer | Provider reference; 0 for global |
+| SecUserNumEntry | integer | Entry user reference |
+| SecDateEntry | date | Entry date |
+| SecDateTEdit | datetime | Last edit timestamp |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /fees
+
+**Version:** 23.3.11
+**Description:** Retrieves a list of fees with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| FeeSched | integer | No | — | Filter by fee schedule |
+| CodeNum | integer | No | — | Filter by procedure code |
+| ClinicNum | integer | No | — | Filter by clinic |
+| ProvNum | integer | No | — | Filter by provider |
+
+**Response:** array of objects (same fields as GET single)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### POST /fees
+
+**Version:** 23.3.11
+**Description:** Creates a new fee record.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Amount | decimal | Yes | Charged amount |
+| FeeSched | integer | Yes | Fee schedule reference |
+| CodeNum | integer | Yes | Procedure code reference |
+| ClinicNum | integer | No | Clinic reference; defaults to 0 (global) |
+| ProvNum | integer | No | Provider reference; defaults to 0 (global) |
+
+**Response:** object — created fee with all fields
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /fees/{FeeNum}
+
+**Version:** 23.3.11
+**Description:** Updates a fee's amount.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| FeeNum | integer | Yes | Fee identifier |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Amount | decimal | Yes | New fee amount |
+
+**Response:** object — updated fee with all fields
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /fees/{FeeNum}
+
+**Version:** 23.3.11
+**Description:** Deletes a fee record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| FeeNum | integer | Yes | Fee identifier |
+
+**Response:** 200 OK (no body)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+- Fees with `ClinicNum` = 0 and `ProvNum` = 0 are global fees.
+- Fees associated with a FeeSchedGroup cannot be created, updated, or deleted via this API.
+- Non-global fees may include clinic and/or provider overrides.
+- Only `Amount` can be modified via PUT; to change FeeSched, CodeNum, ClinicNum, or ProvNum, delete and recreate the fee.