@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,260 @@
+# API: ProcedureCodes
+
+**Source:** https://www.opendental.com/site/apiprocedurecodes.html
+**DB Schema Ref:** procedurecode
+**Extracted:** 2026-04-22
+**Base Path:** `/procedurecodes`
+
+---
+
+## Overview
+ProcedureCodes define the catalog of dental and medical procedures used by the office. Every procedure logged for a patient (procedurelog) is linked to a procedurecode entry. Codes can hold dental codes, medical codes, and custom codes.
+
+---
+
+## Endpoints
+
+### GET /procedurecodes/{CodeNum}
+
+**Version:** 23.3.25
+**Description:** Retrieves a single procedure code by its primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| CodeNum | integer | Yes | Primary key of the procedure code |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| CodeNum | integer | Primary key |
+| ProcCode | string | Dental/medical/custom code (e.g., "D0120"); varchar(15) |
+| Descript | string | Full procedure description; varchar(255) |
+| AbbrDesc | string | Abbreviated description; varchar(50) |
+| ProcTime | string | Time pattern using 'X' and '/' characters; varchar(24) |
+| ProcCat | integer | FK to definition.DefNum (category=11) |
+| procCat | string | Category name (e.g., "Exams & Xrays") |
+| TreatArea | string | Treatment area enum (see Field Reference) |
+| NoBillIns | boolean string | "true" if this procedure should not be billed to insurance |
+| IsProsth | boolean string | "true" if Crown, Bridge, Denture, or RPD (forces Initial/Replacement entry) |
+| DefaultNote | text | Note copied to ProcNote when procedure marked complete |
+| IsHygiene | boolean string | "true" if hygiene procedure |
+| AlternateCode1 | string | Medicaid alternate code; varchar(15) |
+| MedicalCode | string | FK to procedurecode.ProcCode (optional) |
+| IsTaxed | boolean string | "true" if sales tax applies |
+| PaintType | string | Tooth chart painting type enum (see Field Reference) |
+| LaymanTerm | string | Patient-friendly description for treatment plans; varchar(255) |
+| IsCanadianLab | boolean string | "true" if used only as a Canadian lab fee adjunct |
+| BaseUnits | integer | Base units (e.g., for anesthesia); non-negative |
+| SubstitutionCode | string | FK to procedurecode.ProcCode; case-sensitive; varchar(25) |
+| SubstOnlyIf | string | Substitution condition enum (see Field Reference) |
+| DateTStamp | string | Last modified timestamp (yyyy-MM-dd HH:mm:ss) |
+| DrugNDC | string | National Drug Code; must be 11 digits or blank |
+| RevenueCodeDefault | string | 3-digit institutional revenue code (for 837I) |
+| ProvNumDefault | integer | FK to provider.ProvNum; 0 for none |
+| CanadaTimeUnits | float | Scaling/periodontal insurance units for Canadian customers |
+| IsRadiology | boolean string | "true" if radiology procedure |
+| DefaultClaimNote | string | Note appended to claim.ClaimNote |
+| DefaultTPNote | string | Note appended to treatment planned procedure |
+| PaintText | string | Text drawn on tooth chart (requires PaintType="Text") |
+| AreaAlsoToothRange | boolean string | "true" enables ToothRange area (requires TreatArea="Quad" or "Arch") |
+| DiagnosticCodes | string | Comma-separated ICD-10 codes; max 4; no whitespace |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### GET /procedurecodes
+
+**Version:** 22.3.22
+**Description:** Retrieves a list of all procedure codes with optional timestamp filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| DateTStamp | string | No | — | "yyyy-MM-dd HH:mm:ss"; returns codes modified on or after this date (added v22.4.28) |
+
+**Response:** array of objects — same fields as single GET
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+
+---
+
+### POST /procedurecodes
+
+**Version:** 22.3
+**Description:** Creates a new procedure code.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| ProcCode | string | Yes | Dental/medical/custom code |
+| Descript | string | Yes | Full description |
+| AbbrDesc | string | Yes | Abbreviated description |
+| ProcCat | integer | Yes (or procCat) | FK to definition.DefNum where definition.Category=11 |
+| procCat | string | Yes (or ProcCat) | String version of definition.ItemName |
+| ProcTime | string | No | Time pattern; default "/X/" |
+| TreatArea | string | No | See enum; default "None" (added v22.4.34) |
+| NoBillIns | string | No | "true"/"false"; default "false" (added v23.2.10) |
+| IsProsth | string | No | "true"/"false"; default "false" (added v23.3.25) |
+| DefaultNote | string | No | Default procedure note |
+| IsHygiene | string | No | "true"/"false"; default "false" |
+| AlternateCode1 | string | No | Medicaid code (added v23.3.25) |
+| MedicalCode | string | No | FK to procedurecode.ProcCode |
+| IsTaxed | string | No | "true"/"false"; default "false" (added v23.3.25) |
+| PaintType | string | No | See enum; default "None" (added v23.3.25) |
+| LaymanTerm | string | No | Patient-friendly description |
+| IsCanadianLab | string | No | "true"/"false"; default "false" (added v23.3.25) |
+| BaseUnits | integer | No | Non-negative; default 0 (added v23.3.25) |
+| SubstitutionCode | string | No | FK to procedurecode.ProcCode (added v22.4.9) |
+| SubstOnlyIf | string | No | See enum; default "Always" (added v22.4.9) |
+| DrugNDC | string | No | 11 digits or blank (added v23.3.25) |
+| RevenueCodeDefault | string | No | 3-digit code (added v23.3.25) |
+| ProvNumDefault | integer | No | FK to provider.ProvNum; default 0 |
+| CanadaTimeUnits | float | No | Canadian insurance units |
+| IsRadiology | string | No | "true"/"false"; default "false" (added v23.3.25) |
+| DefaultClaimNote | string | No | Claim note (added v23.3.25) |
+| DefaultTPNote | string | No | Treatment plan note (added v23.3.25) |
+| PaintText | string | No | Text for tooth painting (added v23.3.24) |
+| AreaAlsoToothRange | string | No | "true"/"false"; default "false" (added v23.3.25) |
+| DiagnosticCodes | string | No | Comma-separated ICD-10 codes (added v23.3.25) |
+
+**Response:** object — complete procedure code with all fields
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest (with explanation) |
+| 404 | NotFound (with explanation) |
+
+---
+
+### PUT /procedurecodes/{CodeNum}
+
+**Version:** 23.3.25
+**Description:** Updates an existing procedure code. All body parameters are optional.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| CodeNum | integer | Yes | Primary key of the procedure code to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| Descript | string | No | Full description |
+| AbbrDesc | string | No | Abbreviated description |
+| ProcTime | string | No | Time pattern |
+| ProcCat | integer | No | FK to definition.DefNum (category=11) |
+| procCat | string | No | String category name |
+| TreatArea | string | No | Treatment area enum |
+| NoBillIns | string | No | "true"/"false" |
+| IsProsth | string | No | "true"/"false" |
+| DefaultNote | string | No | Default procedure note |
+| IsHygiene | string | No | "true"/"false" |
+| AlternateCode1 | string | No | Medicaid code |
+| MedicalCode | string | No | FK to procedurecode.ProcCode |
+| IsTaxed | string | No | "true"/"false" |
+| PaintType | string | No | Paint type enum |
+| LaymanTerm | string | No | Patient-friendly description |
+| IsCanadianLab | string | No | "true"/"false" |
+| BaseUnits | integer | No | Non-negative |
+| SubstitutionCode | string | No | FK to procedurecode.ProcCode |
+| SubstOnlyIf | string | No | Substitution condition enum |
+| DrugNDC | string | No | 11 digits or blank |
+| RevenueCodeDefault | string | No | 3-digit code |
+| ProvNumDefault | integer | No | FK to provider.ProvNum |
+| CanadaTimeUnits | float | No | Canadian insurance units |
+| IsRadiology | string | No | "true"/"false" |
+| DefaultClaimNote | string | No | Claim note |
+| DefaultTPNote | string | No | Treatment plan note |
+| PaintText | string | No | Text for tooth painting |
+| AreaAlsoToothRange | string | No | "true"/"false" |
+| DiagnosticCodes | string | No | Comma-separated ICD-10 codes |
+
+**Response:** object — updated procedure code with all fields
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest (with explanation) |
+| 404 | NotFound (with explanation) |
+
+---
+
+## Field Reference
+
+### TreatArea (enum: TreatmentArea)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | No treatment area; goes on claims as blank |
+| Surf | 1 | Surface |
+| Tooth | 2 | Tooth |
+| Mouth | 3 | Mouth; goes on claims as 00 |
+| Quad | 4 | Quadrant |
+| Sextant | 5 | Sextant |
+| Arch | 6 | Arch |
+| ToothRange | 7 | Tooth range |
+
+### PaintType (enum: ToothPaintingType)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | No tooth painting |
+| Extraction | 1 | Extraction marking |
+| Implant | 2 | Implant marking |
+| RCT | 3 | Root canal treatment |
+| PostBU | 4 | Post and buildup |
+| FillingDark | 5 | Dark filling |
+| FillingLight | 6 | Light filling |
+| CrownDark | 7 | Dark crown |
+| CrownLight | 8 | Light crown |
+| BridgeDark | 9 | Dark bridge |
+| BridgeLight | 10 | Light bridge |
+| DentureDark | 11 | Dark denture |
+| DentureLight | 12 | Light denture |
+| Sealant | 13 | Sealant |
+| Veneer | 14 | Veneer |
+| Text | 15 | Text label (previously called Watch) |
+| RetainedRoot | 16 | Retained root |
+| SpaceMaintainer | 17 | Space maintainer |
+
+### SubstOnlyIf (enum: SubstitutionCondition)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Always | 0 | Always substitute |
+| Molar | 1 | Substitute only if molar |
+| SecondMolar | 2 | Substitute only if second molar |
+| Never | 3 | Never substitute |
+| Posterior | 4 | Substitute if posterior |
+
+---
+
+## Implementation Notes
+- `ProcCat` and `procCat` are mutually exclusive; supply exactly one.
+- `MedicalCode` must reference an existing procedurecode.ProcCode before assignment.
+- `SubstitutionCode` is case-sensitive and must reference an existing procedurecode.ProcCode.
+- `PaintText` is only used when `PaintType = "Text"`.
+- `AreaAlsoToothRange` is only applicable when `TreatArea = "Quad"` or `"Arch"`.
+- `DiagnosticCodes` supports a maximum of 4 ICD-10 codes with no whitespace between them.
+- `BaseUnits` must be non-negative.
+- `DrugNDC` must be exactly 11 digits or blank.
+- `DateTStamp` filter on GET /procedurecodes was added in v22.4.28; use for synchronization.
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| /procedurelogs | Patient procedure instances linked to these codes |
+| /definitions | Lookup for ProcCat (DefCat=11) and ProvNumDefault |
+| /providers | Lookup for ProvNumDefault |