@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,133 @@
+# API: Subscriptions
+
+**Source:** https://www.opendental.com/site/apisubscriptions.html
+**DB Schema Ref:** apisubscription
+**Extracted:** 2026-04-22
+**Base Path:** `/subscriptions`
+
+---
+
+## Overview
+
+Subscriptions allow API clients to register for notifications when specific database table changes or UI events occur. When a subscribed event fires, Open Dental sends an HTTP POST to the registered `EndPointUrl`. Subscriptions are scoped to the API customer key and can target either database polling events or UI events.
+
+---
+
+## Endpoints
+
+### POST /subscriptions
+
+**Version:** 22.1
+**Description:** Creates a new subscription for database or UI events.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EndPointUrl | string | Yes | URL endpoint to which events will be sent. May include a suffix like `/patientevent` or `?type=patientevent` to differentiate multiple subscriptions to the same base URL. |
+| Workstation | string | Conditional | Machine name that fires events. Omit or leave blank to broadcast from all workstations (be careful of duplicate events). Required unless using localhost. |
+| PollingSeconds | integer | Conditional | Polling frequency in seconds. Required for database (`WatchTable`) subscriptions. |
+| WatchTable | string | Conditional | Database table name to monitor. Required for database events. |
+| UiEventType | string | Conditional | Type of UI event to monitor. Required for UI events. |
+| DateTimeStart | datetime | No | When monitoring begins. Defaults to now. |
+| DateTimeStop | datetime | No | When subscription expires. Defaults to no expiration (MinVal 0001-01-01). |
+| Note | string | No | Free-text notes for this subscription. |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| SubscriptionNum | integer | Primary key of the subscription. |
+| EndPointUrl | string | Target endpoint URL. |
+| Workstation | string | Machine name. Blank means all workstations. |
+| CustomerKey | string | API key associated with this subscription. |
+| WatchTable | string | Monitored DB table name (database subscriptions). |
+| PollingSeconds | integer | Polling frequency in seconds. |
+| UiEventType | string | UI event type (UI subscriptions). |
+| DateTimeStart | datetime | Start timestamp. |
+| DateTimeStop | datetime | Expiration timestamp; MinVal if no expiration. |
+| Note | string | Notes field. |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created successfully. |
+| 400 | Bad Request — missing or invalid parameters. |
+| 404 | Not Found. |
+
+---
+
+### GET /subscriptions
+
+**Version:** 22.1
+**Description:** Retrieves all subscriptions associated with the authenticated API key.
+
+**Response:** array of subscription objects (same fields as POST response)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Success. |
+
+---
+
+### PUT /subscriptions/{SubscriptionNum}
+
+**Version:** 22.1
+**Description:** Updates an existing subscription.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| SubscriptionNum | integer | Yes | Primary key of the subscription to update. |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| EndPointUrl | string | No | Updated target endpoint URL. |
+| Workstation | string | No | Updated machine name. |
+| PollingSeconds | integer | No | Updated polling frequency. Only applies to WatchTable subscriptions. |
+| DateTimeStart | datetime | No | Updated start timestamp. |
+| DateTimeStop | datetime | No | Updated expiration timestamp. |
+| Note | string | No | Updated notes. |
+
+**Response:** updated subscription object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Updated successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+### DELETE /subscriptions/{SubscriptionNum}
+
+**Version:** 22.1
+**Description:** Removes an existing subscription.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| SubscriptionNum | integer | Yes | Primary key of the subscription to delete. |
+
+**Response:** 200 No Content
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Deleted successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+## Implementation Notes
+
+- Subscriptions are scoped to the API customer key — each API key manages its own subscriptions independently.
+- Database (WatchTable) subscriptions require both `PollingSeconds` and `WatchTable`.
+- UI subscriptions require `UiEventType`.
+- Omitting `Workstation` broadcasts events from all machines; this can cause duplicate events if multiple workstations are running and all fire on the same table change.
+- To run multiple subscriptions with the same base endpoint URL, append a suffix: e.g., `/patientevent` or `?type=patientevent`.
+- `OpenDental.exe` handles both UI and database events.
+- `OpenDentalAPIService.exe` handles database events only (not UI events).
+- `DateTimeStop` MinVal (0001-01-01) indicates no expiration.

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

@@ -0,0 +1,143 @@
+# API: SubstitutionLinks
+
+**Source:** https://www.opendental.com/site/apisubstitutionlinks.html
+**DB Schema Ref:** substitutionlink
+**Extracted:** 2026-04-22
+**Base Path:** `/substitutionlinks`
+
+---
+
+## Overview
+
+SubstitutionLinks define procedure code substitution rules for an insurance plan. Each link specifies which procedure code (CodeNum) an insurance plan wants to skip or substitute, the replacement code (SubstitutionCode), and the condition under which the substitution applies (SubstOnlyIf). This is primarily used for posterior composite substitution rules.
+
+---
+
+## Endpoints
+
+### GET /substitutionlinks
+
+**Version:** 22.4.25
+**Description:** Retrieves all substitution links for a specific insurance plan.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PlanNum | integer | Yes | — | FK to insplan.PlanNum. Filters results to this insurance plan. |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| SubstitutionLinkNum | integer | Primary key. |
+| PlanNum | integer | FK to insplan.PlanNum. |
+| CodeNum | integer | FK to procedurecode.CodeNum — the procedure being substituted. |
+| SubstitutionCode | string | FK to procedurecode.ProcCode (case-sensitive) — the replacement procedure code. |
+| SubstOnlyIf | string | Enum:SubstitutionCondition — condition under which substitution applies. |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Success. |
+| 400 | Bad Request — missing or invalid PlanNum. |
+| 404 | Not Found. |
+
+---
+
+### POST /substitutionlinks
+
+**Version:** 22.4.1
+**Description:** Creates a new substitution link for an insurance plan.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PlanNum | integer | Yes | FK to insplan.PlanNum. |
+| CodeNum | integer | Yes | FK to procedurecode.CodeNum. |
+| SubstitutionCode | string | Yes | FK to procedurecode.ProcCode (case-sensitive). |
+| SubstOnlyIf | string | Yes | Enum:SubstitutionCondition — condition for substitution. |
+
+**Response:** created substitution link object (same fields as GET response)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+### PUT /substitutionlinks/{SubstitutionLinkNum}
+
+**Version:** 22.4.25
+**Description:** Updates an existing substitution link.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| SubstitutionLinkNum | integer | Yes | Primary key of the substitution link to update. |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| SubstitutionCode | string | No | FK to procedurecode.ProcCode (case-sensitive). |
+| SubstOnlyIf | string | No | Enum:SubstitutionCondition — updated condition. |
+
+**Response:** updated substitution link object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Updated successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+### DELETE /substitutionlinks/{SubstitutionLinkNum}
+
+**Version:** 22.4.25
+**Description:** Removes a substitution link.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| SubstitutionLinkNum | integer | Yes | Primary key of the substitution link to delete. |
+
+**Response:** 200 No Content
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Deleted successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+## Field Reference
+
+### SubstOnlyIf (enum: SubstitutionCondition)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Always | 0 | Always substitute this procedure code. |
+| Molar | 1 | Substitute only when the tooth is a molar. |
+| SecondMolar | 2 | Substitute only when the tooth is a second molar. |
+| Never | 3 | Never substitute (effectively disables substitution for this code). |
+| Posterior | 4 | Substitute when the tooth is any posterior tooth. |
+
+---
+
+## Implementation Notes
+
+- `SubstitutionCode` is case-sensitive and must exactly match `procedurecode.ProcCode`.
+- The `substitutionlink` table represents procedure codes that the insurance plan wants to skip during substitution evaluation.
+- `CodeNum` (FK to procedurecode.CodeNum) and `SubstitutionCode` (FK to procedurecode.ProcCode) reference the same `procedurecode` table but via different key types (numeric vs. string code).
+- GET requires `PlanNum` query parameter — there is no endpoint to retrieve all substitution links across all plans.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /insplans | Retrieve PlanNum values for insurance plans |
+| /procedurecodes | Retrieve CodeNum and ProcCode values |

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

@@ -0,0 +1,89 @@
+# API: TaskLists
+
+**Source:** https://www.opendental.com/site/apitasklists.html
+**DB Schema Ref:** tasklist
+**Extracted:** 2026-04-22
+**Base Path:** `/tasklists`
+
+---
+
+## Overview
+
+TaskLists are folder-like containers for tasks in Open Dental's intra-office task system. They can be nested (parent/child hierarchy), associated with specific object types (patient, appointment), and set as repeating. TaskLists may be Active or Archived.
+
+---
+
+## Endpoints
+
+### GET /tasklists
+
+**Version:** 22.3.15
+**Description:** Retrieves a list of task lists, optionally filtered by status. Supports pagination via Offset.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| TaskListStatus | string | No | Active | Filters by status. Accepts `Active` or `Archived`. |
+| Offset | integer | No | 0 | Pagination offset — number of records to skip. |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| TaskListNum | integer | Primary key. |
+| Descript | varchar(255) | Task list description/name. |
+| Parent | integer | FK to tasklist.TaskListNum. 0 if this is a root-level task list on the main trunk. |
+| DateTL | date | Optional date. Set to 0001-01-01 when no date assigned. If set, list also appears in the date section. |
+| IsRepeating | boolean | True if this list appears in the repeating section. All children must also be IsRepeating=true. |
+| DateType | string | Enum:TaskDateType — recurrence type. Only meaningful when IsRepeating is true. |
+| FromNum | integer | FK to tasklist.TaskListNum. If derived from a repeating list, holds the source TaskListNum. |
+| ObjectType | string | Enum:TaskObjectType — related object type for this list. |
+| DateTimeEntry | datetime | Date and time the task list was created. Used for sort order. |
+| TaskListStatus | string | Enum:TaskListStatusEnum — Active or Archived. |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Success. |
+| 400 | Bad Request — invalid `TaskListStatus` value. |
+
+---
+
+## Field Reference
+
+### TaskListStatus (enum: TaskListStatusEnum)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Active | 0 | Active task list — visible in Task Window tabs by default. |
+| Archived | 1 | Archived task list — hidden from User, Main, and Reminder tabs by default. |
+
+### DateType (enum: TaskDateType)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | No recurrence. When IsRepeating=true and DateType=None, repeating is effectively disabled. |
+| Day | 1 | Daily recurrence. |
+| Week | 2 | Weekly recurrence. |
+| Month | 3 | Monthly recurrence. |
+
+### ObjectType (enum: TaskObjectType)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | No associated object type. |
+| Patient | 1 | Task list is associated with patients. |
+| Appointment | 2 | Task list is associated with appointments. |
+
+---
+
+## Implementation Notes
+
+- `Parent` = 0 indicates a root-level task list on the main trunk of a section.
+- `DateTL` sentinel value `0001-01-01` means no date is assigned.
+- When `IsRepeating` is true, all child task lists must also have `IsRepeating=true`.
+- `FromNum` tracks derivation from repeating lists; automatically managed lists may be deleted if no tasks are marked complete.
+- Use `Offset` for pagination when the result set is large.
+- Only `Active` and `Archived` are valid values for `TaskListStatus`; invalid values return 400.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /tasks | Individual tasks within task lists |

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

@@ -0,0 +1,130 @@
+# API: TaskNotes
+
+**Source:** https://www.opendental.com/site/apitasknotes.html
+**DB Schema Ref:** tasknote
+**Extracted:** 2026-04-22
+**Base Path:** `/tasknotes`
+
+---
+
+## Overview
+
+TaskNotes are individual notes attached to tasks. Multiple notes may be added to a single task. Each note is associated with the user who created it. A user may only edit their own task notes within a task. The `DateTimeNote` is system-generated on creation but can be overridden via PUT.
+
+---
+
+## Endpoints
+
+### GET /tasknotes/{TaskNoteNum}
+
+**Version:** 24.4.22
+**Description:** Retrieves a single task note record by primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TaskNoteNum | integer | Yes | Primary key of the task note |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| TaskNoteNum | bigint | Primary key |
+| TaskNum | bigint | FK to task.TaskNum |
+| UserNum | bigint | FK to userod.UserNum; the user who created this note |
+| DateTimeNote | datetime | Date and time the note was created or last modified; editable |
+| Note | text | Text content of the note |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /tasknotes
+
+**Version:** 24.4.22
+**Description:** Retrieves multiple task note records with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| TaskNum | integer | No | — | FK to task.TaskNum; filters to notes for a specific task |
+| UserNum | integer | No | — | FK to userod.UserNum; filters to notes by a specific user |
+
+**Response:** array of objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### POST /tasknotes
+
+**Version:** 24.4.22
+**Description:** Creates a new task note.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TaskNum | integer | Yes | FK to task.TaskNum |
+| UserNum | integer | Yes | FK to userod.UserNum |
+| Note | string | Yes | Note content; cannot be blank |
+
+**Response:** object — created task note with system-generated `TaskNoteNum` and `DateTimeNote`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /tasknotes/{TaskNoteNum}
+
+**Version:** 24.4.22
+**Description:** Updates an existing task note. All body fields are optional.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TaskNoteNum | integer | Yes | Primary key of the task note to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| DateTimeNote | string (datetime) | No | Format "yyyy-MM-dd HH:mm:ss" |
+| Note | string | No | Updated note content; cannot be blank if provided |
+
+**Response:** object — updated task note record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+
+- `Note` cannot be blank on either POST or PUT; sending an empty string returns 400.
+- `DateTimeNote` is automatically set to the current server time on creation; it can be overridden via PUT.
+- In Open Dental's UI, users may only edit their own task notes; enforce the same restriction in SDK workflows.
+- `DateTimeNote` format: "yyyy-MM-dd HH:mm:ss".
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| Tasks | Parent task record (TaskNum FK target) |
+| Users | User who authored the note (UserNum FK target) |

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

@@ -0,0 +1,192 @@
+# API: Tasks
+
+**Source:** https://www.opendental.com/site/apitasks.html
+**DB Schema Ref:** task
+**Extracted:** 2026-04-22
+**Base Path:** `/tasks`
+
+---
+
+## Overview
+
+Tasks are individual to-do items used for intra-office communication, reminders, and workflow management. They exist within TaskLists and can optionally be linked to a Patient or Appointment. Tasks have a status lifecycle (New → Viewed → Done) and support priority, category, and reminder features.
+
+---
+
+## Endpoints
+
+### GET /tasks/{TaskNum}
+
+**Version:** 24.4.13
+**Description:** Retrieves a single task by its primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TaskNum | integer | Yes | Primary key of the task. |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| TaskNum | integer | Primary key. |
+| TaskListNum | integer | FK to tasklist.TaskListNum. 0 if on the trunk; -1 is a transient sentinel (never saved to DB). |
+| DateTask | date | Only used when the task is assigned to a dated category. |
+| KeyNum | integer | FK to patient.PatNum or appointment.AptNum. Only used when ObjectType is not None. |
+| Descript | text | Task description. May be very long. |
+| TaskStatus | string | Enum:TaskStatusEnum — New, Viewed, or Done. |
+| IsRepeating | boolean (string) | True if the task appears in the repeating section. |
+| DateType | string | Enum:TaskDateType — recurrence type. |
+| FromNum | integer | FK to task.TaskNum. If derived from a repeating task, holds the source TaskNum. |
+| ObjectType | string | Enum:TaskObjectType — None, Patient, or Appointment. |
+| DateTimeEntry | datetime (string) | Date and time task was added. For reminder tasks, the date/time the reminder takes effect. |
+| UserNum | integer | FK to userod.UserNum — the user who created the task. |
+| DateTimeFinished | datetime (string) | Date and time the task was marked Done. |
+| PriorityDefNum | integer | FK to definition.DefNum where Category=33 — task priority. |
+| ReminderGroupId | string | Group identifier for repeating reminders. Empty/null if not a reminder task. |
+| ReminderType | string | Bit field for reminder type. |
+| ReminderFrequency | integer | Reminder frequency value. |
+| DateTimeOriginal | datetime (string) | Original insert datetime. Used for sort order. Defaults filter uses previous 14 days. |
+| SecDateTEdit | datetime (string) | Automatically updated by MySQL on any row change. |
+| DescriptOverride | varchar(255) | If present, displays only this text in task list grids instead of full description. Max 256 characters. |
+| IsReadOnly | boolean (string) | If true, task cannot be edited by most users. Currently used at HQ only. |
+| Category | integer | FK to definition.DefNum where Category=54. Only used when pref `TaskCategoryShow` is enabled. Added v25.4.14. |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Success. |
+| 404 | Not Found. |
+
+---
+
+### GET /tasks
+
+**Version:** 22.3.16
+**Description:** Retrieves multiple tasks with optional filters. Defaults to tasks created in the previous 14 days when `DateTimeOriginal` is not specified.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| TaskListNum | integer | No | — | Filter by task list. |
+| KeyNum | integer | No | — | FK to patient.PatNum or appointment.AptNum. |
+| ObjectType | string | No | — | Filter by object type: `None`, `Patient`, or `Appointment`. |
+| TaskStatus | string | No | — | Filter by status: `New`, `Viewed`, or `Done`. |
+| DateTimeOriginal | datetime | No | Previous 14 days | Returns tasks created after this datetime. Format: `yyyy-MM-dd HH:mm:ss`. |
+
+**Response:** array of task objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Success. |
+| 400 | Bad Request — invalid parameters. |
+| 404 | Not Found. |
+
+---
+
+### POST /tasks
+
+**Version:** 22.3.17
+**Description:** Creates a new task.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TaskListNum | integer | Yes | FK to tasklist.TaskListNum. |
+| Descript | string | Yes | Task description. |
+| UserNum | integer | Yes | FK to userod.UserNum — creating user. |
+| KeyNum | integer | No | FK to patient.PatNum or appointment.AptNum. Required when ObjectType is not None. |
+| ObjectType | string | No | Enum:TaskObjectType — defaults to `None`. |
+| DateTimeEntry | datetime | No | Format `yyyy-MM-dd HH:mm:ss`. Defaults to current time. |
+| PriorityDefNum | integer | No | FK to definition.DefNum where Category=33. |
+| DescriptOverride | string | No | Max 256 characters. Overrides display text in task list grids. |
+| Category | integer | No | FK to definition.DefNum where Category=54. Added v25.4.14. Requires `TaskCategoryShow` preference enabled. |
+
+**Response:** created task object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+### PUT /tasks/{TaskNum}
+
+**Version:** 22.4.15
+**Description:** Updates an existing task.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TaskNum | integer | Yes | Primary key of the task to update. |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Descript | string | No | Overwrites existing description. Also resets status from `Done` to `Viewed`. |
+| TaskStatus | string | No | Enum:TaskStatusEnum — `New`, `Viewed`, or `Done`. Added v24.2.10. |
+| KeyNum | integer | No | FK to patient.PatNum or appointment.AptNum. |
+| ObjectType | string | No | Enum:TaskObjectType — `None`, `Patient`, or `Appointment`. |
+| DateTimeEntry | datetime | No | Format `yyyy-MM-dd HH:mm:ss`. |
+| PriorityDefNum | integer | No | FK to definition.DefNum where Category=33. |
+| DescriptOverride | string | No | Max 256 characters. |
+| Category | integer | No | FK to definition.DefNum where Category=54. Added v25.4.14. |
+
+**Response:** updated task object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Updated successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+## Field Reference
+
+### TaskStatus (enum: TaskStatusEnum)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| New | 0 | Task has not been viewed. |
+| Viewed | 1 | Task has been viewed but not completed. |
+| Done | 2 | Task is complete. |
+
+### ObjectType (enum: TaskObjectType)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | No linked object. |
+| Patient | 1 | Linked to a patient (KeyNum = patient.PatNum). |
+| Appointment | 2 | Linked to an appointment (KeyNum = appointment.AptNum). |
+
+### DateType (enum: TaskDateType)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | No recurrence. When IsRepeating=true and DateType=None, repeating is effectively disabled. |
+| Day | 1 | Daily recurrence. |
+| Week | 2 | Weekly recurrence. |
+| Month | 3 | Monthly recurrence. |
+
+---
+
+## Implementation Notes
+
+- `TaskListNum` = -1 is a transient sentinel meaning "not yet assigned to a list" — this value is never persisted to the database.
+- Updating `Descript` via PUT automatically resets a `Done` task status back to `Viewed`.
+- `ObjectType` must be paired with a valid `KeyNum` when set to `Patient` or `Appointment`.
+- `DescriptOverride` maximum length is 256 characters; when set, only this text displays in task list grids.
+- `Category` field requires the `TaskCategoryShow` preference to be enabled in Open Dental settings (added v25.4.14).
+- `PriorityDefNum` references definition rows with Category=33; `Category` references definition rows with Category=54.
+- Default GET (without `DateTimeOriginal`) returns tasks from the previous 14 days only.
+- `DateTimeOriginal` format: `yyyy-MM-dd HH:mm:ss`.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /tasklists | Retrieve TaskListNum values for filtering |
+| /userods | Retrieve UserNum for task creation |
+| /definitions | Retrieve PriorityDefNum (Category=33) and Category DefNum (Category=54) values |