@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,319 @@
+# API: Documents
+
+**Source:** https://www.opendental.com/site/apidocuments.html
+**Extracted:** 2026-04-22
+**Base Path:** `/documents`
+
+---
+
+## Overview
+
+Documents manages patient document records in Open Dental's document imaging system. It supports multiple upload mechanisms (raw Base64, SFTP, URL), thumbnail generation, and direct SFTP download. Documents are stored in one of three backends: LocalAtoZ, InDatabase, or Cloud.
+
+---
+
+## Endpoints
+
+### GET /documents/{DocNum}
+
+**Version:** 24.2.32
+**Description:** Retrieves a single document record by its identifier.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| DocNum | integer | Yes | Document identifier |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| DocNum | integer | Primary key |
+| Description | string | Document description |
+| DateCreated | datetime | Creation timestamp |
+| DocCategory | integer | Definition number for the document category |
+| docCategory | string | Category name |
+| PatNum | integer | Patient identifier |
+| FileName | string | File name on disk |
+| ImgType | string | Image type: Photo, Document, Radiograph, File, or Attachment |
+| ToothNumbers | string | Comma/hyphen-separated tooth numbers (e.g., "1-5,8") |
+| DateTStamp | datetime | Last modification timestamp |
+| ProvNum | integer | Provider identifier |
+| PrintHeading | boolean | Whether to print a heading on the document |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /documents
+
+**Version:** 21.2
+**Description:** Retrieves all document records for a patient, ordered by DateCreated.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | Yes | — | Patient identifier |
+
+**Response:** array of document objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /documents/Upload
+
+**Version:** 21.1
+**Description:** Uploads a document as a Base64-encoded file and creates a document record.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | Patient identifier |
+| rawBase64 | string | Yes | Base64-encoded file content |
+| extension | string | Yes | File extension (e.g., `.jpg`, `.pdf`) |
+| Description | string | No | Document description |
+| DateCreated | datetime | No | Format: "yyyy-MM-dd HH:mm:ss" |
+| DocCategory | integer | No | Definition number for the category |
+| ImgType | string | No | Default: Document |
+| ToothNumbers | string | No | Comma/hyphen-separated tooth numbers (v23.1.35+) |
+| ProvNum | integer | No | Provider identifier (v24.2.32+) |
+| PrintHeading | boolean | No | Whether to print a heading (v24.2.32+) |
+
+**Response:** 201 Created — document object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /documents/UploadSftp
+
+**Version:** 21.2
+**Description:** Uploads a document from an SFTP server and creates a document record.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | Patient identifier |
+| SftpAddress | string | Yes | Full path using forward slashes |
+| SftpUsername | string | Yes | SFTP username |
+| SftpPassword | string | Yes | SFTP password |
+| SftpPort | integer | No | SFTP port; default 22 (v25.4.45+) |
+| Description | string | No | Document description (v24.2.32+) |
+| DateCreated | datetime | No | Creation timestamp (v21.4+) |
+| DocCategory | integer | No | Definition number for the category |
+| ImgType | string | No | Image type |
+| ToothNumbers | string | No | Comma/hyphen-separated tooth numbers (v23.1.35+) |
+| ProvNum | integer | No | Provider identifier (v24.2.32+) |
+| PrintHeading | boolean | No | Whether to print a heading (v24.2.32+) |
+
+**Response:** 201 Created — document object with `filePath`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /documents/SetByUrl
+
+**Version:** 21.1
+**Description:** Creates a document record that references a file by URL.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | Patient identifier |
+| url | string | Yes | URL of the file to link |
+| Description | string | No | Document description |
+| DateCreated | datetime | No | Creation timestamp (v24.2.32+) |
+| DocCategory | integer | No | Definition number for the category |
+| ImgType | string | No | Image type |
+| ToothNumbers | string | No | Comma/hyphen-separated tooth numbers (v23.1.35+) |
+| ProvNum | integer | No | Provider identifier (v24.2.32+) |
+| PrintHeading | boolean | No | Whether to print a heading (v24.2.32+) |
+
+**Response:** 201 Created — document object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /documents/DownloadSftp
+
+**Version:** 21.2
+**Description:** Downloads a document or mount item to an SFTP server.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| DocNum | integer | Conditional | Document identifier; required if MountNum not provided |
+| MountNum | integer | Conditional | Mount identifier; required if DocNum not provided |
+| SftpAddress | string | Yes | SFTP destination path |
+| SftpUsername | string | Yes | SFTP username |
+| SftpPassword | string | Yes | SFTP password |
+| SftpPort | integer | No | SFTP port; default 22 (v25.4.45+) |
+
+**Response:** 201 Created — Location header with full filepath
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /documents/Thumbnails
+
+**Version:** 21.2
+**Description:** Uploads thumbnail images for all documents of a patient to an SFTP server.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | Patient identifier |
+| SftpAddress | string | Yes | SFTP destination path |
+| SftpUsername | string | Yes | SFTP username |
+| SftpPassword | string | Yes | SFTP password |
+| SftpPort | integer | No | SFTP port; default 22 (v25.4.45+) |
+
+**Response:** array of objects with `DocNum` and `FileName`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /documents/DownloadMount
+
+**Version:** 21.2
+**Description:** Downloads all images from a mount to an SFTP server.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| MountNum | integer | Yes | Mount identifier |
+| SftpAddress | string | Yes | SFTP destination path |
+| SftpUsername | string | Yes | SFTP username |
+| SftpPassword | string | Yes | SFTP password |
+| SftpPort | integer | No | SFTP port; default 22 (v25.4.45+) |
+
+**Response:** array of objects with `DocNum` and `FileName`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /documents/{DocNum}
+
+**Version:** 24.2.32
+**Description:** Updates metadata on an existing document record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| DocNum | integer | Yes | Document identifier |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Description | string | No | Updated description |
+| DateCreated | datetime | No | Updated creation timestamp |
+| DocCategory | integer | No | Updated category definition number |
+| ImgType | string | No | Updated image type |
+| ToothNumbers | string | No | Updated tooth numbers |
+| ProvNum | integer | No | Updated provider identifier |
+| PrintHeading | boolean | No | Updated print heading flag |
+
+**Response:** object — updated document record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /documents/{DocNum}
+
+**Version:** 24.2.32
+**Description:** Deletes a document record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| DocNum | integer | Yes | Document identifier |
+
+**Response:** 200 OK
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### ImgType (enum)
+| Value | Description |
+|-------|-------------|
+| Document | Standard document |
+| Radiograph | Dental radiograph/X-ray |
+| Photo | Patient photo |
+| File | Generic file |
+| Attachment | Email or form attachment |
+
+---
+
+## Implementation Notes
+
+- Three storage backends are supported: LocalAtoZ, InDatabase, Cloud.
+- When storage is InDatabase, the `filePath` field returns empty.
+- Mounts do not have `filePath`, `ToothNumbers`, `PrintHeading`, or `DateTStamp` fields.
+- `ToothNumbers` format: comma and/or hyphen-separated ranges (e.g., "1-5,8").
+- `DateCreated` format for POST/PUT body: "yyyy-MM-dd HH:mm:ss".
+- Base64 uploads store a reference prefix "\_rawBase64\_:" in the document Note field.
+- URL-based documents store a reference prefix "\_download\_:" in the document Note field.
+- Manual file insertions use prefix "\_##\_" where ## is the category DefNum.
+- SFTP user must have appropriate read/write permissions for the target path.
+- Either `DocNum` or `MountNum` must be provided for DownloadSftp, but not necessarily both.
+- `SftpPort` defaults to 22 when not specified (available from v25.4.45).

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

@@ -0,0 +1,87 @@
+# API: EhrPatients
+
+**Source:** https://www.opendental.com/site/apiehrpatients.html
+**Extracted:** 2026-04-22
+**Base Path:** `/ehrpatients`
+
+---
+
+## Overview
+The EhrPatients API manages extended EHR (Electronic Health Record) demographic fields for patients, including mother's maiden name, vaccination sharing consent, Medicaid information, sexual orientation, gender identity, and discharge date. Each patient has exactly one EhrPatient record keyed by PatNum.
+
+---
+
+## Endpoints
+
+### GET /ehrpatients/{PatNum}
+
+**Version:** 24.1.15
+**Description:** Retrieves the EHR patient record for a given patient.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | Patient identifier (FK to patient) |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| PatNum | integer | Patient identifier |
+| MotherMaidenFname | string | Mother's maiden first name |
+| MotherMaidenLname | string | Mother's maiden last name |
+| VacShareOk | string | Vaccination sharing permission: "Yes" or "No" |
+| MedicaidState | string | State abbreviation for Medicaid ID |
+| SexualOrientation | string | SNOMED code representing sexual orientation |
+| GenderIdentity | string | SNOMED code representing gender identity |
+| SexualOrientationNote | string | Additional notes on sexual orientation |
+| GenderIdentityNote | string | Additional notes on gender identity |
+| DischargeDate | string | Patient discharge date (format: "yyyy-MM-dd") |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /ehrpatients/{PatNum}
+
+**Version:** 24.1.15
+**Description:** Updates the EHR patient record for a given patient.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | Patient identifier |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| DischargeDate | string | No | Patient discharge date (format: "yyyy-MM-dd") |
+| MedicaidState | string | No | State abbreviation for Medicaid ID (added v24.4.13) |
+
+**Response:** object — updated EhrPatient record with all fields
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+- EhrPatient records are keyed by `PatNum`; there is one record per patient.
+- `SexualOrientation` and `GenderIdentity` store SNOMED codes, not plain-text values.
+- `MedicaidState` is a two-character state abbreviation.
+- `MedicaidState` became writable via PUT in version 24.4.13.
+- Only `DischargeDate` and `MedicaidState` are currently writable via PUT; other fields must be managed through the Open Dental UI.
+- No POST or DELETE operations are available; records are created automatically with the patient.
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| Patients | Core patient demographic record |

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

@@ -0,0 +1,145 @@
+# API: Employees
+
+**Source:** https://www.opendental.com/site/apiemployees.html
+**Extracted:** 2026-04-22
+**Base Path:** `/employees`
+
+---
+
+## Overview
+The Employees API manages employee records including contact information, payroll IDs, clock status, and reporting hierarchy. Supports full CRUD operations as of version 25.4.36.
+
+---
+
+## Endpoints
+
+### GET /employees/{EmployeeNum}
+
+**Version:** 23.3.22
+**Description:** Retrieves a single employee record by its identifier.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EmployeeNum | integer | Yes | Unique employee identifier |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| EmployeeNum | integer | Unique employee identifier |
+| LName | string | Last name |
+| FName | string | First name |
+| MiddleI | string | Middle initial or name |
+| IsHidden | string | "true" or "false" |
+| ClockStatus | string | Current employee clock status |
+| PayrollID | string | Payroll identification number |
+| WirelessPhone | string | Phone number with punctuation |
+| EmailWork | string | Work email address |
+| EmailPersonal | string | Personal email address |
+| IsFurloughed | string | "true" or "false" |
+| ReportsTo | integer | FK to employee.EmployeeNum (supervisor); 0 if no supervisor |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /employees
+
+**Version:** 23.3.22
+**Description:** Retrieves multiple employee records with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| ReportsTo | integer | No | — | Filter by supervisor (FK to employee.EmployeeNum) |
+
+**Response:** array of objects (same fields as GET single)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /employees
+
+**Version:** 25.4.36
+**Description:** Creates a new employee record. At least one of `LName` or `FName` must be provided.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LName | string | Conditional | Last name; required if FName is absent; default empty string |
+| FName | string | Conditional | First name; required if LName is absent; default empty string |
+| MiddleI | string | No | Middle initial or name; default empty string |
+| IsHidden | string | No | "true" or "false"; default "false" |
+| PayrollID | string | No | Payroll ID; default empty string |
+| WirelessPhone | string | No | Phone number with punctuation; default empty string |
+| EmailWork | string | No | Work email address; default empty string |
+| EmailPersonal | string | No | Personal email address; default empty string |
+| IsFurloughed | string | No | "true" or "false"; default "false" |
+| ReportsTo | integer | No | FK to employee.EmployeeNum; default 0 |
+
+**Response:** object — created employee with all fields
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /employees/{EmployeeNum}
+
+**Version:** 25.4.36
+**Description:** Updates an existing employee record. All body parameters are optional; only provided fields are updated.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EmployeeNum | integer | Yes | Employee identifier |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LName | string | No | Last name |
+| FName | string | No | First name |
+| MiddleI | string | No | Middle initial or name |
+| IsHidden | string | No | "true" or "false" |
+| PayrollID | string | No | Payroll identification number |
+| WirelessPhone | string | No | Phone number with punctuation |
+| EmailWork | string | No | Work email address |
+| EmailPersonal | string | No | Personal email address |
+| IsFurloughed | string | No | "true" or "false" |
+| ReportsTo | integer | No | FK to employee.EmployeeNum; can be set to 0 to remove supervisor |
+
+**Response:** object — updated employee with all fields
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+- At least one of `LName` or `FName` must be non-empty at all times; setting both to blank via PUT will result in 400 BadRequest.
+- `ReportsTo` = 0 means the employee has no supervisor.
+- `ClockStatus` is returned in GET responses but is not directly settable via POST/PUT (managed by ClockEvents).
+- GET and PUT were available from version 23.3.22; POST and PUT body support added in 25.4.36.
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| ClockEvents | Time clock records for employees |

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

@@ -0,0 +1,129 @@
+# API: Employers
+
+**Source:** https://www.opendental.com/site/apiemployers.html
+**Extracted:** 2026-04-22
+**Base Path:** `/employers`
+
+---
+
+## Overview
+
+Employers represents employer records in Open Dental, which are referenced by patient insurance plans. This resource supports full CRUD operations on employer records.
+
+---
+
+## Endpoints
+
+### GET /employers/{EmployerNum}
+
+**Version:** 23.3.22
+**Description:** Retrieves a single employer record by its identifier.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EmployerNum | integer | Yes | Employer identifier |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| EmployerNum | integer | Primary key |
+| EmpName | string | Employer's business name |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /employers
+
+**Version:** 23.3.22
+**Description:** Retrieves all employer records with optional pagination.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| Offset | integer | No | 0 | Pagination offset |
+
+**Response:** array of employer objects with `EmployerNum` and `EmpName`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+### POST /employers
+
+**Version:** 21.4
+**Description:** Creates a new employer record.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EmpName | string | Yes | The employer's business name |
+
+**Response:** 201 Created — employer object with generated `EmployerNum`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+
+---
+
+### PUT /employers/{EmployerNum}
+
+**Version:** 21.4
+**Description:** Updates an existing employer's name.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EmployerNum | integer | Yes | Employer identifier |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EmpName | string | Yes | Updated employer name |
+
+**Response:** object — updated employer record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /employers/{EmployerNum}
+
+**Version:** 23.3.22
+**Description:** Deletes an employer record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EmployerNum | integer | Yes | Employer identifier |
+
+**Response:** 200 OK
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+
+- Employers associated with a patient or an insurance plan cannot be deleted; attempting to do so returns a 400 BadRequest.