@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,119 @@
+# API: ToothInitials
+
+**Source:** https://www.opendental.com/site/apitoothinitials.html
+**DB Schema Ref:** toothinitial
+**Extracted:** 2026-04-22
+**Base Path:** `/toothinitials`
+
+---
+
+## Overview
+
+ToothInitials track tooth status records for patients, including missing, hidden, and primary tooth designations, as well as orthodontic movements and tooth chart drawings. The API exposes the three core clinical status types (Missing, Hidden, Primary); the underlying table also stores movement and drawing data types.
+
+---
+
+## Endpoints
+
+### GET /toothinitials
+
+**Version:** 24.2.3
+**Description:** Retrieves all tooth initial records, optionally filtered by patient.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | No | — | FK to patient.PatNum; filters results to a single patient |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| ToothInitialNum | bigint | Primary key |
+| PatNum | bigint | FK to patient.PatNum |
+| ToothNum | varchar(2) | Tooth identifier: 1–32 (permanent) or A–T (primary/deciduous) |
+| InitialType | string | Type classification (see Field Reference) |
+| Movement | float | Shift in mm, or rotation/tipping in degrees (for movement types) |
+| DrawingSegment | text | Point data for a drawing segment in format "x,y;x,y;..." within 410×307 coordinate space |
+| ColorDraw | integer | RGB color value as integer |
+| SecDateTEntry | datetime | Creation timestamp; system-generated, not user-editable |
+| SecDateTEdit | datetime (timestamp) | Last edit timestamp; auto-updated by MySQL |
+| DrawText | varchar(255) | Text associated with a drawing; format "x.x,y.y;TextContent" |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /toothinitials
+
+**Version:** 24.2.3
+**Description:** Creates a new tooth initial record for a patient.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum |
+| ToothNum | string | Yes | Single tooth number: 1–32 or A–T |
+| InitialType | string | Yes | "Missing", "Hidden", or "Primary" |
+
+**Response:** object — created record with all fields populated
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### DELETE /toothinitials/{ToothInitialNum}
+
+**Version:** 24.2.3
+**Description:** Removes an existing tooth initial record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ToothInitialNum | integer | Yes | Primary key of the record to delete |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### InitialType (enum: ToothInitialType)
+
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Missing | 0 | Tooth is missing |
+| Hidden | 1 | Tooth and its number are hidden on the chart |
+| Primary | 2 | Only valid for teeth 1–32; marks tooth as primary; shows primary tooth alongside permanent, displays letter alongside number; applies Shift0 -12 and other movements automatically |
+| ShiftM | 3 | Mesial shift in mm |
+| ShiftO | 4 | Occlusal/incisal shift in mm |
+| ShiftB | 5 | Buccal (labial) shift in mm |
+| Rotate | 6 | Clockwise rotation in degrees as viewed from occlusal/incisal |
+| TipM | 7 | Mesial tipping in degrees |
+| TipB | 8 | Buccal tipping in degrees |
+| Drawing | 9 | One segment of a freehand drawing |
+| Text | 10 | Location and string combined for chart text annotation |
+
+---
+
+## Implementation Notes
+
+- The API POST only supports `InitialType` values "Missing", "Hidden", and "Primary" (DB ints 0–2). Movement and drawing types (3–10) are not creatable via the API.
+- `ToothNum` accepts 1–32 for permanent teeth and A–T for primary/deciduous teeth. Supernumeraries are not supported.
+- `Primary` type (2) is only meaningful for teeth numbered 1–32; it triggers automatic display and movement adjustments in the tooth chart.
+- `DrawingSegment` coordinate space is always 410×307 regardless of how the tooth chart is scaled on screen; segments separated by semicolons; pen-lift starts a new row.
+- `SecDateTEntry` and `SecDateTEdit` are system-managed and not user-editable.

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

@@ -0,0 +1,111 @@
+# API: TreatPlanAttaches
+
+**Source:** https://www.opendental.com/site/apitreatplanattaches.html
+**DB Schema Ref:** treatplanattach
+**Extracted:** 2026-04-22
+**Base Path:** `/treatplanattaches`
+
+---
+
+## Overview
+
+TreatPlanAttaches link procedures from `procedurelog` to Active or Inactive treatment plans. Each attachment can carry a priority. When a procedure is completed or deleted, Open Dental automatically removes its treatplanattach rows. For Saved treatment plans, use the `ProcTPs` resource instead (which stores static copies of procedures).
+
+---
+
+## Endpoints
+
+### GET /treatplanattaches
+
+**Version:** 22.4.16
+**Description:** Retrieves all procedure attachments for a specified treatment plan.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| TreatPlanNum | integer | Yes | — | FK to treatplan.TreatPlanNum. Returns all attachments for this plan. |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| TreatPlanAttachNum | integer | Primary key. |
+| TreatPlanNum | integer | FK to treatplan.TreatPlanNum. |
+| ProcNum | integer | FK to procedurelog.ProcNum. |
+| Priority | integer | FK to definition.DefNum where Category=20 — numeric priority identifier. |
+| priority | string | Human-readable priority label: `"1"`, `"Recmend"`, `"Wait"`, or empty string. |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Success. |
+| 400 | Bad Request — missing or invalid TreatPlanNum. |
+| 404 | Not Found. |
+
+---
+
+### POST /treatplanattaches
+
+**Version:** 23.2.17
+**Description:** Creates a new association between a treatment plan and a procedure.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TreatPlanNum | integer | Yes | FK to treatplan.TreatPlanNum. Must be an Active or Inactive plan. |
+| ProcNum | integer | Yes | FK to procedurelog.ProcNum. |
+| Priority | integer | No | FK to definition.DefNum where Category=20. Defaults to 0 (no priority). |
+
+**Response:** created treatplanattach object (same fields as GET response)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+### PUT /treatplanattaches/{TreatPlanAttachNum}
+
+**Version:** 23.2.17
+**Description:** Updates the priority on an existing treatment plan attachment.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TreatPlanAttachNum | integer | Yes | Primary key of the attachment to update. |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Priority | integer | No | FK to definition.DefNum where Category=20. |
+
+**Response:** updated treatplanattach object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Updated successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+## Implementation Notes
+
+- This resource only applies to **Active** and **Inactive** treatment plans. For **Saved** treatment plans, use the `ProcTPs` resource.
+- When a procedure is completed or deleted, Open Dental automatically removes associated `treatplanattach` rows when the Treatment Plan or Chart module is opened.
+- `Priority` = 0 means no priority is assigned (sentinel value).
+- The `priority` (lowercase) field in the response is a human-readable label derived from the definition; the `Priority` (uppercase) field is the raw definition FK.
+- Known human-readable priority values: `"1"`, `"Recmend"`, `"Wait"`, or empty string.
+- `Priority` definition rows use Category=20; retrieve valid `DefNum` values from the definitions endpoint.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /treatplans | Retrieve TreatPlanNum values |
+| /procedurelogs | Retrieve ProcNum values |
+| /definitions | Retrieve Priority DefNum values (Category=20) |
+| /proctps | Procedure attachments for Saved treatment plans |

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

@@ -0,0 +1,201 @@
+# API: TreatPlans
+
+**Source:** https://www.opendental.com/site/apitreatplans.html
+**DB Schema Ref:** treatplan
+**Extracted:** 2026-04-22
+**Base Path:** `/treatplans`
+
+---
+
+## Overview
+
+Treatment Plans track proposed or accepted patient treatments. There are three statuses: Active (one per patient, linked to procedures via treatplanattaches), Inactive (additional plans linked to procedures via treatplanattaches), and Saved (static snapshot plans linked to ProcTP copies that do not change when procedures are completed). The API supports creating, retrieving, updating, and deleting treatment plans, as well as applying digital signatures.
+
+---
+
+## Endpoints
+
+### GET /treatplans
+
+**Version:** 22.4.16
+**Description:** Retrieves treatment plans matching the specified search criteria. Returns all statuses by default.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | No | — | Filter by patient. |
+| SecDateTEdit | string | No | — | Format `yyyy-MM-dd HH:mm:ss`. Returns only plans modified after this datetime. |
+| TPStatus | string | No | all | Filter by status: `Saved`, `Active`, or `Inactive`. |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| TreatPlanNum | integer | Primary key. |
+| PatNum | integer | FK to patient.PatNum. |
+| DateTP | string | Treatment plan date. Format: `yyyy-MM-dd`. |
+| Heading | string | Heading displayed at the top of the treatment plan (e.g., "Proposed Treatment Plan"). |
+| Note | string | Note displayed at the bottom of the treatment plan. |
+| SigIsTopaz | boolean | True if the patient signature is in Topaz format rather than OD format. |
+| ResponsParty | integer | FK to patient.PatNum. Responsible party for approving treatment. 0 if none. |
+| DocNum | integer | FK to document.DocNum. PDF document generated at signing time. 0 if none. |
+| TPStatus | string | Enum:TreatPlanStatus — `Saved`, `Active`, or `Inactive`. |
+| SecUserNumEntry | integer | FK to userod.UserNum — user who created the plan. |
+| SecDateEntry | string | Date the plan was created. Format: `yyyy-MM-dd`. |
+| SecDateTEdit | string | Timestamp of last modification. Format: `yyyy-MM-dd HH:mm:ss`. Auto-updated by MySQL. |
+| UserNumPresenter | integer | FK to userod.UserNum — user presenting the plan. |
+| TPType | string | Enum:TreatPlanType — `Insurance` or `Discount`. |
+| DateTSigned | string | Date and time the patient signed. Format: `yyyy-MM-dd HH:mm:ss`. |
+| DateTPracticeSigned | string | Date and time the practice signed. Format: `yyyy-MM-dd HH:mm:ss`. |
+| SignatureText | string | Typed name of the person who signed for the patient. |
+| SignaturePracticeText | string | Typed name of the person who signed for the practice. |
+| isSigned | boolean | True if the patient signature is present. |
+| isSignedPractice | boolean | True if the practice signature is present. |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Success. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+### POST /treatplans
+
+**Version:** 23.2.13
+**Description:** Creates a new Inactive treatment plan for a patient.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum. |
+| Heading | string | No | Defaults to `"Inactive Treatment Plan"`. |
+| Note | string | No | Defaults to the `TreatmentPlanNote` office preference value. |
+| TPType | string | No | Enum:TreatPlanType — `Insurance` or `Discount`. Defaults based on whether the patient has a discount plan subscription. |
+
+**Response:** created treatplan object with `TPStatus` = `"Inactive"`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+### POST /treatplans/Saved
+
+**Version:** 23.2.22
+**Description:** Creates an unsigned Saved treatment plan from an existing Active or Inactive plan. The saved plan stores static ProcTP copies.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TreatPlanNum | integer | Yes | FK to an existing Active or Inactive treatplan.TreatPlanNum to snapshot. |
+| Heading | string | No | Defaults to the source plan's heading. |
+| UserNumPresenter | integer | No | FK to userod.UserNum. Defaults to 0. |
+
+**Response:** created treatplan object with `TPStatus` = `"Saved"`
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+### PUT /treatplans/{TreatPlanNum}
+
+**Version:** 24.1.10
+**Description:** Updates treatment plan details or applies/clears digital signatures.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TreatPlanNum | integer | Yes | Primary key of the treatment plan to update. |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| DateTP | string | No | Format `yyyy-MM-dd`. Only allowed when `TPStatus` is `Saved`. |
+| Heading | string | No | Updated heading. |
+| Note | string | No | Updated note. Overwrites existing note entirely. |
+| ResponsParty | integer | No | FK to patient.PatNum. |
+| TPType | string | No | Enum:TreatPlanType — `Insurance` or `Discount`. |
+| SignatureText | string | No | Typed patient signature name. Only allowed if Treatment Plan Sheet has a matching SheetFieldDef signature box. |
+| SignaturePracticeText | string | No | Typed practice signature name. Only allowed if Treatment Plan Sheet has a matching SheetFieldDef. |
+| isSigned | boolean | No | `true` digitally signs for the patient; `false` clears the patient signature. Every Treatment Plan Sheet must have at least one Signature Box, so `isSigned` is always available. |
+| isSignedPractice | boolean | No | `true` digitally signs for the practice; `false` clears the practice signature. Only allowed if the TP Sheet has a `SigBoxPractice` field type. |
+
+**Response:** updated treatplan object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Updated successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+### DELETE /treatplans/{TreatPlanNum}
+
+**Version:** 24.4.26
+**Description:** Deletes a treatment plan. For Saved plans, also deletes all associated ProcTP rows.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| TreatPlanNum | integer | Yes | Primary key of the treatment plan to delete. |
+
+**Response:** 200 No Content
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Deleted successfully. |
+| 400 | Bad Request. |
+| 404 | Not Found. |
+
+---
+
+## Field Reference
+
+### TPStatus (enum: TreatPlanStatus)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Saved | 0 | Saved/archived plan. Linked to ProcTP copies; procedures do not change after saving. |
+| Active | 1 | Current active plan. Only one Active plan per patient. Linked to procedures via TreatPlanAttach. |
+| Inactive | 2 | Inactive plan. Linked to procedures via TreatPlanAttach. |
+
+### TPType (enum: TreatPlanType)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Insurance | 0 | Treatment plan uses regular insurance for cost calculations. |
+| Discount | 1 | Treatment plan uses a discount plan for cost calculations. |
+
+---
+
+## Implementation Notes
+
+- Only one **Active** treatment plan may exist per patient.
+- **Active** and **Inactive** plans reference live procedures via `treatplanattaches`; procedures removed when completed.
+- **Saved** plans use `ProcTP` copies (static snapshots); `DELETE` on a Saved plan also removes its ProcTP rows.
+- `DateTP` can only be updated on Saved plans via PUT.
+- Digital signature text format: `"Digitally Signed by [API DeveloperName] Date Signed: [MM/dd/yyyy HH:mm:ss tt]"`.
+- When `TreatPlanSaveSignedToPdf` office preference is enabled, signing generates a PDF to the practice/clinic path and sets `DocNum`.
+- `Note` field in PUT overwrites the entire existing note — there is no append behavior.
+- `ResponsParty` = 0 means no responsible party is set.
+- `DocNum` = 0 means no PDF document has been generated.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /treatplanattaches | Link procedures to Active/Inactive treatment plans |
+| /proctps | Procedure copies linked to Saved treatment plans |
+| /patients | Retrieve PatNum values |
+| /userods | Retrieve UserNumPresenter values |

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

@@ -0,0 +1,57 @@
+# API: UserGroupAttaches
+
+**Source:** https://www.opendental.com/site/apiusergroupattaches.html
+**DB Schema Ref:** usergroupattach
+**Extracted:** 2026-04-22
+**Base Path:** `/usergroupattaches`
+
+---
+
+## Overview
+
+UserGroupAttaches represent the many-to-many link between users and user groups. A user may belong to multiple groups, and security permissions are determined by the set of groups a user is attached to. This endpoint provides read-only access to those attachments.
+
+---
+
+## Endpoints
+
+### GET /usergroupattaches
+
+**Version:** 23.3.7
+**Description:** Retrieves a list of user group attachment records with optional filtering by user or group.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| UserNum | integer | No | — | FK to userod.UserNum; filters to attachments for a specific user |
+| UserGroupNum | integer | No | — | FK to usergroup.UserGroupNum; filters to attachments for a specific group |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| UserGroupAttachNum | bigint | Primary key |
+| UserNum | bigint | FK to userod.UserNum |
+| UserGroupNum | bigint | FK to usergroup.UserGroupNum |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+
+- The `usergroup.UserGroupNum` column in the `userod` table is deprecated; the usergroupattach table is the authoritative source for user-to-group assignments.
+- A user can be linked to multiple UserGroups; query by `UserNum` to get all groups for a user.
+- Query with no parameters returns all usergroupattach records in the system.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| UserGroups | User group definitions (UserGroupNum FK target) |

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

@@ -0,0 +1,56 @@
+# API: UserGroups
+
+**Source:** https://www.opendental.com/site/apiusergroups.html
+**DB Schema Ref:** usergroup
+**Extracted:** 2026-04-22
+**Base Path:** `/usergroups`
+
+---
+
+## Overview
+
+UserGroups define named security groups to which users are attached. Security permissions in Open Dental are determined by a user's group memberships. Groups may optionally be designated as CEMT (Central Enterprise Management Tool) groups, linked to a group in the central manager database.
+
+---
+
+## Endpoints
+
+### GET /usergroups
+
+**Version:** 23.2.21
+**Description:** Retrieves a list of user groups. By default only returns non-CEMT groups; set `includeCEMT=true` to include CEMT-linked groups.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| includeCEMT | string | No | "false" | Set to "true" to return both CEMT and non-CEMT user groups |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| UserGroupNum | bigint | Primary key |
+| Description | varchar(255) | Name/description of the user group |
+| UserGroupNumCEMT | bigint | FK to usergroup.UserGroupNum in the Central Manager DB; 0 if not a CEMT group |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+
+---
+
+## Implementation Notes
+
+- `UserGroupNumCEMT` is 0 for groups that are not linked to CEMT; non-zero values reference the corresponding group in the Central Manager database.
+- `UserGroupNumCEMT` is only editable via CEMT and may change when CEMT syncs.
+- `includeCEMT` defaults to "false"; omitting the parameter returns only local (non-CEMT) groups.
+- The deprecated `UserGroupNum` column in the `userod` table should not be used; user-to-group assignments are managed through the UserGroupAttaches resource.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| UserGroupAttaches | Links users to user groups |

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

@@ -0,0 +1,128 @@
+# API: Userods
+
+**Source:** https://www.opendental.com/site/apiuserods.html
+**DB Schema Ref:** userod
+**Extracted:** 2026-04-22
+**Base Path:** `/userods`
+
+---
+
+## Overview
+
+Userods represent Open Dental user accounts, which are separate entities from Providers and Employees (though they can be linked to either). Users are permanently identified by their `UserNum`, which never changes, ensuring an audit trail. The API supports listing, creating, and updating users.
+
+---
+
+## Endpoints
+
+### GET /userods
+
+**Version:** 21.3
+**Description:** Retrieves a list of users. By default returns only visible (non-hidden) non-CEMT users.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| includeHidden | string | No | false | `"true"` returns hidden users alongside visible ones. Added v22.4.24. |
+| includeCEMT | string | No | false | `"true"` returns CEMT-designated users. Added v25.1.10. |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| UserNum | integer | Primary key. Never changes — permanent audit trail identifier. |
+| UserName | varchar(255) | Unique username. |
+| userGroupNums | array | Array of UserGroupNum integers for all groups this user belongs to. |
+| EmployeeNum | integer | FK to employee.EmployeeNum. 0 if user is not an employee. |
+| employeeName | string | Employee first and last name. Blank if not linked to an employee. |
+| ProviderNum | integer | FK to provider.ProvNum. 0 if user is not a provider. |
+| providerName | string | Full provider name with suffix. Blank if not linked to a provider. |
+| ClinicNum | integer | FK to clinic.ClinicNum. Default clinic for this user. 0 if no default or HQ when clinics are enabled. |
+| emailAddress | string | User's email address. |
+| IsHidden | string | `"true"` or `"false"` — whether user is hidden from the login list. |
+| UserNumCEMT | integer | FK to userod.UserNum in the Central Manager database. Only editable via CEMT. |
+| IsPasswordResetRequired | string | `"true"` or `"false"` — whether user must reset password on next login. |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Success. |
+| 400 | Bad Request — with explanation. |
+
+---
+
+### POST /userods
+
+**Version:** 22.1
+**Description:** Creates a new user account.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| UserName | string | Yes | Must be unique. Cannot end with whitespace. |
+| UserGroupNum | integer | Yes | Obtain via UserGroups GET endpoint. |
+| Password | string | Yes | Minimum 8 characters with at least one number, one uppercase letter, and one lowercase letter. Special characters required if office `PasswordStrength` preference is enabled. |
+| IsPasswordResetRequired | string | No | `"true"` or `"false"`. Defaults to `"false"`. |
+
+**Response:** created userod object (same fields as GET response, plus Password echo)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created successfully. |
+| 400 | Bad Request — with explanation (e.g., duplicate username, invalid password). |
+| 404 | Not Found — with explanation. |
+
+---
+
+### PUT /userods/{UserNum}
+
+**Version:** 22.4.20
+**Description:** Updates an existing user account.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| UserNum | integer | Yes | Primary key of the user to update. |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| userGroupNums | array | No | Array of UserGroupNum integers, e.g., `[1, 2, 3]`. Replaces all existing group memberships. Added v25.1.10. |
+| EmployeeNum | integer | No | FK to employee.EmployeeNum — associates this user with an employee. |
+| ProviderNum | integer | No | FK to provider.ProvNum — associates this user with a provider. |
+| ClinicNum | integer | No | FK to clinic.ClinicNum — sets the default clinic for this user. |
+| IsHidden | string | No | `"true"` or `"false"` — hides or shows user in the login list. |
+| IsPasswordResetRequired | string | No | `"true"` or `"false"`. Added v25.1.10. |
+
+**Response:** updated userod object (same fields as GET response)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | Updated successfully. |
+| 400 | Bad Request — with explanation. |
+| 404 | Not Found — with explanation. |
+
+---
+
+## Implementation Notes
+
+- `UserNum` is permanent and never changes; it is used throughout the database as the audit trail reference.
+- Users, Providers, and Employees are separate entities. A user may optionally be linked to a Provider (`ProviderNum`) or Employee (`EmployeeNum`), or neither.
+- Multiple users can be linked to the same provider (via `ProvNum`).
+- `EmployeeNum` = 0 means not linked to an employee; `ProviderNum` = 0 means not linked to a provider.
+- `ClinicNum` = 0 means no default clinic, or defaults to HQ when clinics are enabled.
+- `IsHidden`, `IsPasswordResetRequired` values are returned as string `"true"` / `"false"`, not booleans.
+- Password is stored as a hash (`HashType$Salt$Hash` format), never as plaintext. Legacy passwords may be MD5.
+- `userGroupNums` in PUT replaces all existing group memberships — it is not additive.
+- `UserNumCEMT` is managed by the Central Enterprise Management Tool (CEMT) and cannot be changed via this API.
+- `includeHidden` and `includeCEMT` are string parameters (`"true"` / `"false"`), not booleans.
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| /usergroups | Retrieve UserGroupNum values for POST and PUT |
+| /employees | Retrieve EmployeeNum values |
+| /providers | Retrieve ProviderNum values |
+| /clinics | Retrieve ClinicNum values |