@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,239 @@
+# API: Recalls
+
+**Source:** https://www.opendental.com/site/apirecalls.html
+**DB Schema Ref:** recall, recalltype
+**Extracted:** 2026-04-22
+**Base Path:** `/recalls`
+
+---
+
+## Overview
+
+Recalls track when patients are due for preventive procedures (e.g., Prophy, Perio). Each patient may have at most one recall per RecallType. The API supports retrieving, creating, updating recalls, switching recall types, and updating reminder status.
+
+---
+
+## Endpoints
+
+### GET /recalls
+
+**Version:** 22.4.40
+**Description:** Retrieves a list of recall records, optionally filtered by patient.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | No | — | Filter by patient number |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| RecallNum | integer | Primary key |
+| PatNum | integer | FK to patient.PatNum |
+| DateDue | string (yyyy-MM-dd) | Date used for recall reporting; usually same as DateDueCalc unless user-modified |
+| DatePrevious | string (yyyy-MM-dd) | Previous date trigger procedures were completed; calculated automatically |
+| RecallInterval | string | Format: digit + 'y'/'m'/'w'/'d' (e.g., "6m") |
+| RecallStatus | integer | FK to definition.DefNum (Category=13); 0 = None |
+| recallStatus | string | Human-readable recall status description |
+| Note | string | Administrative note for staff |
+| IsDisabled | boolean | If true, recall is disabled |
+| DateTStamp | string (timestamp) | Last inserted/updated datetime |
+| RecallTypeNum | integer | FK to recalltype.RecallTypeNum |
+| DisableUntilBalance | decimal | Family balance threshold; 0 = no threshold |
+| DisableUntilDate | string (yyyy-MM-dd) | Recall disabled until this date |
+| DateScheduled | string (yyyy-MM-dd) | Populated only if a recall appointment is scheduled |
+| Priority | string | "Normal" or "ASAP" |
+| TimePatternOverride | string | Overrides RecallType time pattern; 'X' and '/' characters only |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+### GET /recalls/List
+
+**Version:** 22.1
+**Description:** Retrieves the recall list as displayed in the Appointment Module, with pagination support.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| DateStart | string (yyyy-MM-dd) | No | RecallDaysPast preference | Due date range start (inclusive) |
+| DateEnd | string (yyyy-MM-dd) | No | RecallDaysFuture preference | Due date range end (inclusive) |
+| ProvNum | integer | No | — | Filter by provider (considers PriProv and SecProv) |
+| ClinicNum | integer | No | — | Filter by clinic; use 0 for unassigned |
+| RecallType | string | No | — | Typically "Prophy" or "Perio" |
+| IncludeReminded | boolean | No | false | Include patients already reminded |
+| Offset | integer | No | 0 | Pagination offset |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| DueDate | string | Recall due date |
+| PatNum | integer | Patient identifier |
+| Patient | string | Format "Last, First" |
+| Age | string | Patient age |
+| Type | string | RecallType description |
+| Interval | string | Recall interval |
+| NumRemind | string | Number of reminders sent |
+| LastRemind | string | Date of last reminder |
+| Contact | string | Preferred recall contact method |
+| Status | string | Current recall status |
+| ClinicNum | integer | Clinic identifier |
+| Note | string | Administrative note |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request (with explanation) |
+| 404 | Not Found (with explanation) |
+
+---
+
+### POST /recalls
+
+**Version:** 24.2.31
+**Description:** Creates a recall for a patient. Maximum one recall per RecallType per patient.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum |
+| RecallTypeNum | integer | Yes | FK to recalltype.RecallTypeNum |
+| DateDue | string (yyyy-MM-dd) | No | Recall due date |
+| RecallInterval | string | No | Format: digit + 'y'/'m'/'w'/'d'; defaults to recalltype.DefaultInterval |
+| RecallStatus | integer | No | FK to definition.DefNum (Category=13); default 0 |
+| Note | string | No | Administrative note |
+| IsDisabled | boolean | No | Default false |
+| DisableUntilBalance | decimal | No | Default 0 |
+| DisableUntilDate | string (yyyy-MM-dd) | No | — |
+| Priority | string | No | "Normal" or "ASAP"; default "Normal" |
+| TimePatternOverride | string | No | 'X' and '/' characters only, 5-minute increments |
+
+**Response:** object (same fields as GET /recalls)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request (with explanation) |
+| 404 | Not Found (with explanation) |
+
+---
+
+### PUT /recalls/{RecallNum}
+
+**Version:** 24.2.31
+**Description:** Updates an existing recall. All body fields are optional.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| RecallNum | integer | Yes | Primary key of the recall to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| DateDue | string (yyyy-MM-dd) | No | Updated due date |
+| RecallInterval | string | No | Format: digit + 'y'/'m'/'w'/'d' |
+| RecallStatus | integer | No | Use 0 for "None" |
+| Note | string | No | Overwrites existing note |
+| IsDisabled | boolean | No | — |
+| DisableUntilBalance | decimal | No | — |
+| DisableUntilDate | string (yyyy-MM-dd) | No | — |
+| Priority | string | No | "Normal" or "ASAP" |
+| TimePatternOverride | string | No | 'X' and '/' characters only |
+
+**Response:** object (same fields as GET /recalls)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request (with explanation) |
+| 404 | Not Found (with explanation) |
+
+---
+
+### PUT /recalls/Status
+
+**Version:** 21.2
+**Description:** Updates the RecallStatus for a patient's recall and optionally creates a commlog entry. Updates the recall reminder status — not appointment status.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | Patient identifier |
+| recallType | string | Yes | Typically "Prophy" or "Perio" |
+| RecallStatus | integer | No | definition.DefNum where Category=13; use 0 for "None" |
+| commlogMode | string | No | "None", "Email", "Mail", "Phone", "InPerson", "Text", "EmailAndText", or "PhoneAndText" |
+| commlogNote | string | No | Replaces default commlog note |
+
+**Response:** 200 OK
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request (with explanation) |
+| 404 | Not Found (with explanation) |
+
+---
+
+### PUT /recalls/SwitchType
+
+**Version:** 22.4.41
+**Description:** Toggles a patient's recall type between Prophy and Perio, mirroring the UI button behavior.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | Patient identifier |
+
+**Response:** 200 OK
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request (with explanation) |
+| 404 | Not Found (with explanation) |
+
+---
+
+## Field Reference
+
+### Priority (enum: RecallPriority)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Normal | 0 | Default scheduling priority |
+| ASAP | 1 | Flags record for the ASAP list |
+
+---
+
+## Implementation Notes
+
+- A patient may have only one recall per RecallType.
+- RecallTypes shown in /recalls/List depend on the "RecallTypesShowingInList" preference (CSV of RecallTypeNum values).
+- `DateDue` is the field used for recall reports. It tracks `DateDueCalc` unless a user manually overrides it; gets cleared when the recall is reset or disabled.
+- `DatePrevious` is not editable via API — it is auto-calculated from completed trigger procedures on the patient's chart.
+- `RecallStatus` references definition.DefNum where Category=13; use 0 for "None".
+- `DisableUntilBalance` default is 0 (no balance threshold). If positive, the family balance must be below this value for the recall to appear in the list.
+- `TimePatternOverride` must use only 'X' and '/' characters in 5-minute increments.
+- PUT /recalls/Status creates a commlog with CommType.Recall. Use PUT /appointments Confirm for appointment confirmation status changes.
+- PUT /recalls/SwitchType: Prophy → Perio and Perio → Prophy.
+- The recall table is kept synchronized automatically by the system when procedures, patient status, or procedurecode.SetRecall changes; minor sync bugs may exist.
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| Appointments | Use PUT /appointments Confirm to update appointment confirmation status |
+| Definitions | RecallStatus values (Category=13) |
+| RecallTypes | RecallTypeNum references |

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

@@ -0,0 +1,65 @@
+# API: RecallTypes
+
+**Source:** https://www.opendental.com/site/apirecalltypes.html
+**DB Schema Ref:** recalltype
+**Extracted:** 2026-04-22
+**Base Path:** `/recalltypes`
+
+---
+
+## Overview
+
+RecallTypes define the templates that drive patient recall scheduling, including the default interval between recalls, appointment time pattern, associated procedures, and whether the type appends to special recall appointments. All patient recalls are based on a recall type.
+
+---
+
+## Endpoints
+
+### GET /recalltypes/{RecallTypeNum}
+
+**Version:** 24.1.44
+**Description:** Retrieves a single recall type record by primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| RecallTypeNum | integer | Yes | Primary key of the recall type |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| RecallTypeNum | bigint | Primary key |
+| Description | varchar(255) | Name/description of the recall type |
+| DefaultInterval | integer | Default interval between recalls; encoded as a combined integer (years + months + weeks + days); displayed in the app as e.g. "6m1d" |
+| TimePattern | varchar(255) | Appointment time pattern using / and X characters; each character represents one time-increment unit per global setting |
+| Procedures | varchar(255) | Comma-separated procedure codes to place on the recall appointment |
+| AppendToSpecial | boolean (tinyint) | True if this type should automatically append to the appointment when scheduling a special recall type; only relevant for manual/custom types |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /recalltypes
+
+**Version:** 24.1.44
+**Description:** Retrieves all recall types in the system as an array.
+
+**Response:** array of objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+## Implementation Notes
+
+- `DefaultInterval` is stored as a single integer that encodes years, months, weeks, and days. Decode using Open Dental's Interval struct logic; the API returns the combined integer value.
+- `TimePattern` appointment length is relative to the global "Time Increments" preference — each `/` or `X` represents one increment unit (e.g., 10, 15, or 20 minutes depending on setup).
+- `AppendToSpecial` is only considered for manual/custom recall types; it is ignored if the type is itself flagged as a special recall type.
+- `Procedures` stores ProcCodes (not CodeNums) as a comma-delimited string.

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

@@ -0,0 +1,179 @@
+# API: RefAttaches
+
+**Source:** https://www.opendental.com/site/apirefattaches.html
+**DB Schema Ref:** refattach
+**Extracted:** 2026-04-22
+**Base Path:** `/refattaches`
+
+---
+
+## Overview
+
+RefAttaches (referral attachments) link a patient to a referral source. Each record captures whether the referral is incoming (RefFrom), outgoing (RefTo), or custom (RefCustom), along with status, notes, and associated procedure information.
+
+---
+
+## Endpoints
+
+### GET /refattaches
+
+**Version:** 22.4.27
+**Description:** Retrieves a list of referral attachments with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | No | — | Filter by patient number |
+| ReferralNum | integer | No | — | Filter by referral number (v25.2.10+) |
+| DateTStamp | string (yyyy-MM-dd HH:mm:ss) | No | — | Return only records modified after this timestamp (v25.2.10+) |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| RefAttachNum | integer | Primary key |
+| ReferralNum | integer | FK to referral.ReferralNum |
+| referralName | string | Referral source name |
+| PatNum | integer | FK to patient.PatNum |
+| ItemOrder | integer | Display order (one-based) |
+| RefDate | string (yyyy-MM-dd) | Date of referral |
+| ReferralType | string | "RefFrom", "RefTo", or "RefCustom" |
+| RefToStatus | string | "None", "Declined", "Scheduled", "Consulted", "InTreatment", or "Complete" |
+| Note | string | Patient-specific referral notes |
+| IsTransitionOfCare | string | "true" or "false" |
+| ProcNum | integer | FK to procedurelog.ProcNum |
+| DateProcComplete | string (yyyy-MM-dd) | Procedure completion date |
+| ProvNum | integer | FK to provider.ProvNum (valid only for RefTo; -1 when RefType is not RefTo) |
+| DateTStamp | string (yyyy-MM-dd HH:mm:ss) | Last edited datetime |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+### POST /refattaches
+
+**Version:** 21.2
+**Description:** Attaches a patient to a referral source. Either ReferralNum or referralName must be provided.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum |
+| ReferralNum | integer | Conditional | FK to referral; required if referralName not provided |
+| referralName | string | Conditional | Required if ReferralNum not provided; creates new referral record if no exact match found |
+| RefDate | string (yyyy-MM-dd) | No | Defaults to current date |
+| ReferralType | string | No | "RefFrom" (default), "RefTo", or "RefCustom" |
+| RefToStatus | string | No | "None" (default), "Declined", "Scheduled", "Consulted", "InTreatment", "Complete" |
+| Note | string | No | Patient-specific notes |
+| IsTransitionOfCare | string | No | "true" or "false"; defaults to "false" (v23.3.26+) |
+| ProcNum | integer | No | FK to procedurelog.ProcNum; defaults to 0 (v23.3.26+) |
+| DateProcComplete | string (yyyy-MM-dd) | No | Defaults to "0001-01-01" (v23.3.26+) |
+| ProvNum | integer | No | FK to provider.ProvNum; valid only when ReferralType is "RefTo" (v23.3.26+) |
+
+**Response:** object (same fields as GET /refattaches)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+### PUT /refattaches/{RefAttachNum}
+
+**Version:** 23.3.26
+**Description:** Updates an existing referral attachment. All body fields are optional.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| RefAttachNum | integer | Yes | Primary key of the referral attachment |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ReferralNum | integer | No | FK to referral.ReferralNum |
+| RefDate | string (yyyy-MM-dd) | No | Date of referral |
+| ReferralType | string | No | "RefFrom", "RefTo", or "RefCustom" |
+| RefToStatus | string | No | "None", "Declined", "Scheduled", "Consulted", "InTreatment", "Complete" |
+| Note | string | No | Overwrites existing note |
+| IsTransitionOfCare | string | No | "true" or "false" |
+| ProcNum | integer | No | FK to procedurelog.ProcNum |
+| DateProcComplete | string (yyyy-MM-dd) | No | Procedure completion date |
+| ProvNum | integer | No | FK to provider.ProvNum; valid only when ReferralType is "RefTo" |
+
+**Response:** object (same fields as GET /refattaches)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+### DELETE /refattaches/{RefAttachNum}
+
+**Version:** 23.3.26
+**Description:** Removes a referral attachment record.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| RefAttachNum | integer | Yes | Primary key of the referral attachment |
+
+**Response:** 200 OK
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+## Field Reference
+
+### ReferralType (enum: ReferralType)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| RefTo | 0 | Outgoing referral — patient referred out |
+| RefFrom | 1 | Incoming referral — patient referred in |
+| RefCustom | 2 | Neither to nor from; rarely used; will not appear on reports |
+
+### RefToStatus (enum: ReferralToStatus)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | No status set |
+| Declined | 1 | Patient declined referral |
+| Scheduled | 2 | Appointment scheduled |
+| Consulted | 3 | Patient consulted |
+| InTreatment | 4 | Patient in treatment |
+| Complete | 5 | Referral complete |
+
+---
+
+## Implementation Notes
+
+- Either `ReferralNum` or `referralName` must be supplied on POST; if `referralName` is used and no exact match exists, a new referral record is created.
+- `ProvNum` is only valid when `ReferralType` is "RefTo"; it is stored as -1 in the DB when ReferralType is not RefTo.
+- `IsTransitionOfCare` is a boolean represented as a string ("true"/"false"); outgoing referrals (RefTo) default to true in the UI.
+- `RefCustom` type records do not appear on referral reports.
+- `DateProcComplete` defaults to "0001-01-01" (effectively null/unset).
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| Referrals | Manage referral source records referenced by ReferralNum |
+| Procedures | ProcNum links to procedurelog |
+| Providers | ProvNum links to provider |

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

@@ -0,0 +1,198 @@
+# API: Referrals
+
+**Source:** https://www.opendental.com/site/apireferrals.html
+**DB Schema Ref:** referral
+**Extracted:** 2026-04-22
+**Base Path:** `/referrals`
+
+---
+
+## Overview
+
+Referrals are the source records for referring providers, patients, or non-person sources (e.g., "website", "word of mouth"). All referral info is stored on the referral record itself for easy querying. Referral attachments (linking a referral to a patient) are managed through the RefAttaches API.
+
+---
+
+## Endpoints
+
+### GET /referrals/{ReferralNum}
+
+**Version:** 24.1.34
+**Description:** Retrieves a single referral record by its identifier.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ReferralNum | integer | Yes | Referral identifier |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| ReferralNum | integer | Primary key |
+| LName | string | Last name, or description for non-person sources (e.g., "word of mouth") |
+| FName | string | First name |
+| MName | string | Middle name or initial |
+| SSN | string | SSN or TIN (no punctuation; in Canada, holds referring provider CDA number) |
+| UsingTIN | string | "true" if SSN field contains TIN |
+| Specialty | integer | FK to definition.DefNum (Category=35) |
+| specialty | string | Specialty name |
+| ST | string | State (max 2 characters) |
+| Telephone | string | Primary phone number |
+| Address | string | Mailing address |
+| Address2 | string | Additional address info |
+| City | string | City |
+| Zip | string | ZIP code |
+| Note | string | General notes about the referral |
+| Phone2 | string | Additional phone number (no format restrictions) |
+| IsHidden | string | "true" if hidden (records cannot be deleted, only hidden) |
+| NotPerson | string | "true" for non-person sources (e.g., Yellow Pages) |
+| Title | string | Professional title (e.g., DMD, DDS) |
+| EMail | string | Email address |
+| PatNum | integer | FK to patient.PatNum; 0 if not a patient |
+| IsDoctor | string | "true" if another dentist or physician |
+| DateTStamp | string (timestamp) | Last edited datetime |
+| IsPreferred | string | "true" if marked as a preferred referral |
+| BusinessName | string | Business affiliation name |
+| DisplayNote | string | Shows in Family Module Patient Info grid (scheduling notes) |
+| isPatient | string | "true" if this referral is linked to a patient record |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | Not Found |
+
+---
+
+### GET /referrals
+
+**Version:** 21.4
+**Description:** Retrieves all referral sources with optional boolean and string filters.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| IsHidden | string | No | — | Filter by hidden status ("true"/"false") (v24.1.34+) |
+| NotPerson | string | No | — | Filter non-person referrals (v24.1.34+) |
+| IsDoctor | string | No | — | Filter doctor referrals (v24.1.34+) |
+| IsPreferred | string | No | — | Filter preferred referrals (v24.1.34+) |
+| isPatient | string | No | — | Filter patient referrals (v24.1.34+) |
+| BusinessName | string | No | — | Partial string match on business name (v24.4.19+) |
+
+**Response:** array of referral objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request |
+
+---
+
+### POST /referrals
+
+**Version:** 22.3
+**Description:** Creates a new referral. Referrals can be for patients (provide PatNum), providers (provide Specialty), or non-persons (provide neither).
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LName | string | Yes | Last name or description for non-person sources |
+| PatNum | integer | No | Sets isPatient=true, IsDoctor=false, NotPerson=false |
+| FName | string | No | First name |
+| MName | string | No | Middle name or initial |
+| SSN | string | No | No punctuation (v24.4.16+) |
+| UsingTIN | string | No | "true"/"false"; default "false" (v24.4.16+) |
+| Specialty | integer | No | definition.DefNum where Category=35; sets IsDoctor=true |
+| specialty | string | No | definition.ItemName where DefCat=ProviderSpecialty(35) |
+| ST | string | No | Max 2 characters (v24.4.16+) |
+| Telephone | string | No | Must be 10 digits (v24.4.16+) |
+| Address | string | No | (v24.4.16+) |
+| Address2 | string | No | (v24.4.16+) |
+| City | string | No | (v24.4.16+) |
+| Zip | string | No | (v24.4.16+) |
+| Note | string | No | General notes |
+| Phone2 | string | No | Additional phone, no restrictions (v24.4.16+) |
+| NotPerson | string | No | Default "false" unless neither PatNum nor Specialty supplied (v24.4.16+) |
+| Title | string | No | Professional title |
+| EMail | string | No | Email address (v24.4.16+) |
+| IsDoctor | string | No | Default "false" unless Specialty supplied (v24.4.16+) |
+| BusinessName | string | No | Business affiliation (v24.4.16+) |
+| DisplayNote | string | No | Scheduling notes shown in Family Module (v24.4.16+) |
+
+**Response:** object (same fields as GET /referrals/{ReferralNum})
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+### PUT /referrals/{ReferralNum}
+
+**Version:** 22.4.24
+**Description:** Updates an existing referral. All body fields are optional. Referrals linked to a patient can only have Note and DisplayNote modified.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ReferralNum | integer | Yes | Referral identifier |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| LName | string | No | Last name or description |
+| FName | string | No | First name |
+| MName | string | No | Middle name or initial |
+| SSN | string | No | No punctuation (v24.4.16+) |
+| UsingTIN | string | No | "true"/"false" (v24.4.16+) |
+| Specialty | integer | No | Use 0 to indicate None |
+| ST | string | No | Max 2 characters (v24.4.16+) |
+| Telephone | string | No | Must be 10 digits (v24.4.16+) |
+| Address | string | No | (v24.4.16+) |
+| Address2 | string | No | (v24.4.16+) |
+| City | string | No | (v24.4.16+) |
+| Zip | string | No | (v24.4.16+) |
+| Note | string | No | General notes |
+| Phone2 | string | No | Additional phone (v24.4.16+) |
+| NotPerson | string | No | (v24.4.16+) |
+| Title | string | No | Professional title |
+| EMail | string | No | Email address (v24.4.16+) |
+| IsDoctor | string | No | (v24.4.16+) |
+| BusinessName | string | No | (v24.4.16+) |
+| DisplayNote | string | No | Scheduling notes (v24.4.16+) |
+
+**Response:** object (same fields as GET /referrals/{ReferralNum})
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+## Implementation Notes
+
+- All boolean fields are represented as string values: "true" or "false".
+- `Telephone` must be exactly 10 digits (API restriction prior to v25.4; DB stores up to 30 chars).
+- `SSN` must contain no punctuation.
+- Referral records linked to a patient (`isPatient=true`) have restricted update capabilities — only `Note` and `DisplayNote` can be modified.
+- `IsDoctor=true` referrals cannot be patients.
+- When neither `PatNum` nor `Specialty` is supplied on POST, `NotPerson` defaults to "true".
+- Referrals cannot be deleted via the API; set `IsHidden=true` to hide inactive records.
+- `Specialty` uses `Specialty=0` to clear/unset on PUT.
+- `DisplayNote` is a global field that appears in the Family Module Patient Info grid as scheduling notes.
+- `PatNum=0` on the response indicates the referral is not linked to a patient.
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| RefAttaches | Link referral sources to specific patients |
+| Definitions | Specialty values (Category=35) |