@rinse-dental/open-dental 3.4.2 → 4.0.2

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

@@ -0,0 +1,515 @@
+# API: Benefits
+
+**Source:** https://www.opendental.com/site/apibenefits.html  
+**DB Schema Ref:** OpenDental_DB_Documentation_v26-1.xml → table `benefit`  
+**Benefits Guide Ref:** Open Dental _ Benefits Guide.md  
+**Extracted:** 2026-04-22  
+**Base Path:** `/benefits`
+
+---
+
+## Overview
+
+A benefit is a single row representing one insurance benefit — typically a percentage, deductible, limitation, max, copay, or waiting period. Benefits are attached to either an insurance plan (`PlanNum`) or a specific patient plan (`PatPlanNum`), never both simultaneously.
+
+- **Plan-level** (`PlanNum`): Applies to all patients on the plan (most common).
+- **Patient-level** (`PatPlanNum`): Overrides a plan benefit for a single patient (e.g. a different co-insurance percentage).
+
+> DB table `benefit` replaces the old `covpat` table. X12 field mappings are noted per field.
+
+---
+
+## Endpoints
+
+### GET /benefits/{BenefitNum}
+
+**Version:** 25.3.7  
+**Description:** Retrieve a single benefit record by its primary key.
+
+**Path Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| BenefitNum | integer | yes | Primary key of the benefit record |
+
+**Response Fields (object):** *(see [Field Reference](#field-reference) for full definitions)*
+
+| Field | Type | Description |
+|-------|------|-------------|
+| BenefitNum | integer | Primary key |
+| PlanNum | integer | FK → insplan. Use for plan-level benefits; 0 if PatPlanNum is set |
+| PatPlanNum | integer | FK → patplan. Use for patient-level overrides; 0 if PlanNum is set |
+| CovCatNum | integer | FK → covcat. Coverage category (X12 EB03). 0 if none / general |
+| BenefitType | string | Enum — see BenefitType values below |
+| Percent | integer | Insurance coverage %. -1 = empty. Only meaningful for CoInsurance |
+| MonetaryAmt | decimal | Dollar amount. -1.0 = empty. Used for Deductible, CoPayment, Limitations |
+| TimePeriod | string | Enum — see TimePeriod values below (X12 EB06) |
+| QuantityQualifier | string | Enum — see QuantityQualifier values below (X12 EB09) |
+| Quantity | integer | Numeric quantity (0–255) qualifying QuantityQualifier (X12 EB10) |
+| CodeNum | integer | FK → procedurecode. Specific procedure code; 0 if none. Use instead of CovCatNum for procedure-specific benefits |
+| procCode | string | String procedure code (e.g. "D0274"). Empty if none |
+| CoverageLevel | string | Enum — see CoverageLevel values below (X12 EB02) |
+| SecDateTEntry | datetime | Read-only. Timestamp when record was created |
+| SecDateTEdit | datetime | Read-only. Auto-updated by MySQL on every change |
+| CodeGroupNum | integer | FK → codegroup. Procedure code group for frequency/age-limit benefits |
+| TreatArea | string | Enum — see TreatArea values below. Only applicable to frequency limitations |
+
+**Status Codes:**
+
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | Not Found |
+
+---
+
+### GET /benefits
+
+**Version:** 22.3.27  
+**Description:** Retrieve all benefits for a given insurance plan or patient plan.
+
+**Query Parameters:**
+
+| Name | Type | Required | Notes |
+|------|------|----------|-------|
+| PlanNum | integer | conditional | FK → insplan. Required unless PatPlanNum is provided. Optional as of v23.2.62 |
+| PatPlanNum | integer | conditional | FK → patplan. Required unless PlanNum is provided. Optional as of v23.2.62 |
+
+**Response:** Array of benefit objects — same field structure as single GET above.
+
+**Status Codes:**
+
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+### POST /benefits
+
+**Version:** 22.3.17  
+**Description:** Create a new benefit record.
+
+**Required Fields:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| PlanNum OR PatPlanNum | integer | At least one must be provided and non-zero |
+| BenefitType | string | Type of benefit (see enum below) |
+| CoverageLevel | string | Coverage scope (see enum below) |
+
+**Optional Fields:**
+
+| Name | Type | Version | Description |
+|------|------|---------|-------------|
+| CovCatNum | integer | — | Coverage category. Omit (or set 0) when using CodeNum/CodeGroupNum |
+| Percent | integer | — | 0–100. Only for CoInsurance. Omit otherwise |
+| MonetaryAmt | decimal | — | Dollar amount. For Deductible, CoPayment, Limitations |
+| TimePeriod | string | — | Time period qualifier |
+| QuantityQualifier | string | — | Quantity qualifier type |
+| Quantity | integer | — | 0–255. Must be >0 when QuantityQualifier is AgeLimit |
+| CodeNum | integer | — | Specific procedure code. Set CovCatNum to 0 when used |
+| procCode | string | — | Procedure code string (alternative to CodeNum) |
+| CodeGroupNum | integer | 23.2.62 | Procedure code group for frequency/age-limit limitations |
+| TreatArea | string | 25.3.7 | Treatment area for frequency limitations only |
+
+**Status Codes:**
+
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+### PUT /benefits/{BenefitNum}
+
+**Version:** 22.4.7  
+**Description:** Update an existing benefit.
+
+**Path Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| BenefitNum | integer | yes | Primary key of the benefit to update |
+
+**Updatable Fields:** All optional POST fields apply. All fields are optional on PUT.
+
+**Restrictions:**
+- `CodeGroupNum` cannot be changed on existing Frequency Limitation or Age Limit benefits that already have a `CodeGroupNum` set.
+
+**Status Codes:**
+
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+### DELETE /benefits/{BenefitNum}
+
+**Version:** 22.4.7  
+**Description:** Delete a benefit record.
+
+**Path Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| BenefitNum | integer | yes | Primary key of the benefit to delete |
+
+**Status Codes:**
+
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | Bad Request |
+| 404 | Not Found |
+
+---
+
+## Field Reference
+
+### BenefitType (enum: InsBenefitType) — X12 EB01
+
+| API Value | DB Int | Description |
+|-----------|--------|-------------|
+| ActiveCoverage | 0 | Informational only. Indicates patient has coverage but without specifics. Rarely used |
+| CoInsurance | 1 | Percentage insurance will pay. Note: X12 feeds often report the patient's share (inverse). Use `Percent` field |
+| Deductible | 2 | Deductible amount. May have two entries (e.g. waived on preventive). Use `MonetaryAmt` |
+| CoPayment | 3 | Informational only. Fixed dollar copay. Use `MonetaryAmt` |
+| Exclusions | 4 | Services not covered at all |
+| Limitations | 5 | Covers annual max, frequency limits, fee reductions, etc. Use `MonetaryAmt` or `Quantity`/`QuantityQualifier` |
+| WaitingPeriod | 6 | Period after effective date where benefit is not applicable. Use `Quantity`/`QuantityQualifier` |
+
+---
+
+### TimePeriod (enum: BenefitTimePeriod) — X12 EB06
+
+| API Value | DB Int | Description |
+|-----------|--------|-------------|
+| None | 0 | No time period needed. Typical for percentages and copays |
+| ServiceYear | 1 | Benefit year with non-January renewal month. Requires knowledge of effective date |
+| CalendarYear | 2 | Renewal month is January. Use when `insplan.MonthRenew = 0` |
+| Lifetime | 3 | Lifetime limit. Commonly used for ortho max |
+| Years | 4 | Used with `QuantityQualifier=Years` and `Quantity` for frequency (e.g. every 5 years) |
+| NumberInLast12Months | 5 | Rolling 12-month window, regardless of benefit year start |
+
+> **Rule:** Use `ServiceYear` when `insplan.MonthRenew != 0`; use `CalendarYear` when `insplan.MonthRenew = 0`.
+
+---
+
+### QuantityQualifier (enum: BenefitQuantity) — X12 EB09
+
+| API Value | DB Int | Description |
+|-----------|--------|-------------|
+| None | 0 | No quantity needed. Most benefits |
+| NumberOfServices | 1 | Count of services (e.g. 2 exams per year) |
+| AgeLimit | 2 | Maximum patient age (e.g. fluoride covered through age 18). `Quantity` must be > 0 |
+| Visits | 3 | Number of visits (e.g. copay per 1 visit) |
+| Years | 4 | Frequency in years (e.g. pano every 5 years) |
+| Months | 5 | Frequency in months (e.g. BWs every 6 months) |
+
+---
+
+### CoverageLevel (enum: BenefitCoverageLevel) — X12 EB02
+
+| API Value | DB Int | Description |
+|-----------|--------|-------------|
+| None | 0 | Situational — no level specified. Typical for percentages and copays |
+| Individual | 1 | Individual deductible or max (default for deductibles/maximums) |
+| Family | 2 | Family deductible or max |
+
+---
+
+### TreatArea (enum: TreatmentArea)
+
+Only used for frequency limitation benefits (`BenefitType=Limitations`). Ignored for all other benefit types.
+
+| API Value | DB Int | Description |
+|-----------|--------|-------------|
+| None | 0 | Default / not applicable |
+| Surf | 1 | Surface |
+| Tooth | 2 | Specific tooth |
+| Mouth | 3 | Entire mouth (claims: "00") |
+| Quad | 4 | Quadrant |
+| Sextant | 5 | Sextant |
+| Arch | 6 | Arch |
+| ToothRange | 7 | Range of teeth |
+
+---
+
+### Sentinel Values
+
+| Field | Sentinel | Meaning |
+|-------|----------|---------|
+| Percent | -1 | Empty / not applicable |
+| MonetaryAmt | -1.0 | Empty / not applicable |
+
+---
+
+### EBenefitCategory → CovCatNum Mapping
+
+Used to set `CovCatNum` when creating category-level benefits. Retrieve actual `CovCatNum` values via the CovCats API — the mapping below shows the `covcat.EBenefitCategory` enum value to match against.
+
+| UI Label | EBenefitCategory | Enum Int |
+|----------|-----------------|----------|
+| Diagnostic (includes x-ray) | Diagnostic | 2 |
+| X-Ray (if different) | DiagnosticXRay | 13 |
+| Routine Preventive | RoutinePreventive | 12 |
+| Restorative | Restorative | 4 |
+| Endo | Endodontics | 5 |
+| Perio | Periodontics | 3 |
+| Oral Surgery | OralSurgery | 11 |
+| Crowns | Crowns | 7 |
+| Prosthodontics | Prosthodontics | 10 |
+| Maxillofacial Prosth | MaxillofacialProsth | 6 |
+| Accident | Accident | 8 |
+| Orthodontics | Orthodontics | 9 |
+
+> Only Diagnostic (2), DiagnosticXRay (13), and RoutinePreventive (12) support per-category individual/family deductibles in the UI.  
+> Only Restorative (4), Endodontics (5), Periodontics (3), OralSurgery (11), Crowns (7), and Prosthodontics (10) support per-category waiting periods in the UI.
+
+---
+
+## Usage Examples (from Benefits Guide)
+
+### Annual Max — Individual
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Limitations",
+  "CoverageLevel": "Individual",
+  "TimePeriod": "ServiceYear",
+  "MonetaryAmt": 1000.0
+}
+```
+> Use `"TimePeriod": "CalendarYear"` when `insplan.MonthRenew = 0`.
+
+### Annual Max — Family
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Limitations",
+  "CoverageLevel": "Family",
+  "TimePeriod": "ServiceYear",
+  "MonetaryAmt": 2000.0
+}
+```
+
+### General Deductible — Individual
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Deductible",
+  "CoverageLevel": "Individual",
+  "TimePeriod": "ServiceYear",
+  "MonetaryAmt": 50.0
+}
+```
+
+### General Deductible — Family
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Deductible",
+  "CoverageLevel": "Family",
+  "TimePeriod": "ServiceYear",
+  "MonetaryAmt": 150.0
+}
+```
+
+### Frequency Limitation — Every N Years (CodeGroup)
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Limitations",
+  "CoverageLevel": "None",
+  "CodeGroupNum": 2,
+  "TimePeriod": "None",
+  "Quantity": 5,
+  "QuantityQualifier": "Years",
+  "TreatArea": "None"
+}
+```
+
+### Frequency Limitation — N Per Benefit Year (CodeGroup)
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Limitations",
+  "CoverageLevel": "None",
+  "CodeGroupNum": 2,
+  "TimePeriod": "ServiceYear",
+  "Quantity": 2,
+  "QuantityQualifier": "NumberOfServices",
+  "TreatArea": "None"
+}
+```
+
+### Frequency Limitation — Every N Months (CodeGroup)
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Limitations",
+  "CoverageLevel": "None",
+  "CodeGroupNum": 2,
+  "TimePeriod": "None",
+  "Quantity": 6,
+  "QuantityQualifier": "Months",
+  "TreatArea": "None"
+}
+```
+
+### Frequency Limitation — N in Last 12 Months (CodeGroup)
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Limitations",
+  "CoverageLevel": "None",
+  "CodeGroupNum": 2,
+  "TimePeriod": "NumberInLast12Months",
+  "Quantity": 2,
+  "QuantityQualifier": "NumberOfServices",
+  "TreatArea": "None"
+}
+```
+
+### Age Limit (CodeGroup)
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Limitations",
+  "CoverageLevel": "None",
+  "CodeGroupNum": 2,
+  "TimePeriod": "None",
+  "Quantity": 18,
+  "QuantityQualifier": "AgeLimit",
+  "TreatArea": "None"
+}
+```
+
+### Ortho — Lifetime Max
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Limitations",
+  "CoverageLevel": "None",
+  "CovCatNum": 12,
+  "TimePeriod": "Lifetime",
+  "MonetaryAmt": 1500.0,
+  "TreatArea": "None"
+}
+```
+> `CovCatNum` must resolve to a covcat where `EBenefitCategory = 9` (Orthodontics).
+
+### Ortho — Through Age
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Limitations",
+  "CoverageLevel": "None",
+  "CovCatNum": 12,
+  "TimePeriod": "None",
+  "Quantity": 23,
+  "QuantityQualifier": "AgeLimit",
+  "TreatArea": "None"
+}
+```
+
+### Ortho — CoInsurance Percentage
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "CoInsurance",
+  "CoverageLevel": "None",
+  "CovCatNum": 12,
+  "TimePeriod": "ServiceYear",
+  "Percent": 80,
+  "TreatArea": "None"
+}
+```
+
+### Category CoInsurance (e.g. Diagnostic)
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "CoInsurance",
+  "CoverageLevel": "None",
+  "CovCatNum": 2,
+  "Percent": 89
+}
+```
+
+### Category Individual Deductible (e.g. Diagnostic)
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Deductible",
+  "CoverageLevel": "Individual",
+  "CovCatNum": 2,
+  "MonetaryAmt": 50.0
+}
+```
+
+### Category Family Deductible (e.g. Diagnostic)
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "Deductible",
+  "CoverageLevel": "Family",
+  "CovCatNum": 2,
+  "MonetaryAmt": 75.0
+}
+```
+
+### Waiting Period (e.g. Restorative)
+```json
+{
+  "PlanNum": 81,
+  "BenefitType": "WaitingPeriod",
+  "CoverageLevel": "None",
+  "CovCatNum": 4,
+  "Quantity": 10,
+  "QuantityQualifier": "Months"
+}
+```
+
+### Patient-Level Override (CoInsurance override for one patient)
+```json
+{
+  "PatPlanNum": 44,
+  "BenefitType": "CoInsurance",
+  "CoverageLevel": "None",
+  "CovCatNum": 2,
+  "Percent": 100
+}
+```
+
+---
+
+## Implementation Notes
+
+- A benefit must have a value in **either** `PlanNum` **or** `PatPlanNum` — never both, and never neither.
+- `CodeNum`/`procCode` and `CovCatNum` are mutually exclusive — when using a specific procedure code, set `CovCatNum` to 0.
+- `CodeGroupNum` is used for frequency limitations and age limits. It cannot be changed on existing records of these types once set.
+- `TreatArea` is only enforced for frequency limitation benefits; it is ignored for all other benefit types.
+- The `Percent` field reflects the **insurance share** (what insurance pays). Note that X12 electronic benefit data typically reports the **patient's share** (inverse) — you may need to subtract from 100 when ingesting X12 data.
+- Benefits unsupported by the API include: posterior composites, COB duplication, amounts used, in/out-of-network, authorization required, missing tooth exclusion, and date-based waiting periods.
+- `SecDateTEntry` and `SecDateTEdit` are read-only; do not send them on POST/PUT.
+
+---
+
+## Related Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `GET /insplans` | Retrieve `PlanNum` values and `MonthRenew` to determine CalendarYear vs ServiceYear |
+| `GET /patplans` | Retrieve `PatPlanNum` for patient-level overrides |
+| `GET /covcats` | Retrieve `CovCatNum` values by `EBenefitCategory` |
+| `GET /codegroups` | Retrieve `CodeGroupNum` for frequency/age-limit benefits |
+| `GET /procedurecodes` | Retrieve `CodeNum` for procedure-specific benefits |

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

@@ -0,0 +1,150 @@
+# API: Carriers
+
+**Source:** https://www.opendental.com/site/apicarriers.html
+**Extracted:** 2026-04-22
+**Base Path:** `/carriers`
+
+---
+
+## Overview
+Carriers represent insurance carriers (payers) used in patient insurance plans. Each carrier stores contact information, an electronic payer ID for claim submission, and flags controlling electronic claim behavior.
+
+---
+
+## Endpoints
+
+### GET /carriers
+
+**Version:** 22.4.16
+**Description:** Retrieves a list of all insurance carriers.
+
+**Response:** Array of carrier objects
+| Field | Type | Description |
+|-------|------|-------------|
+| CarrierNum | integer | Primary key |
+| CarrierName | string | Carrier display name |
+| Address | string | Street address line 1 |
+| Address2 | string | Street address line 2 |
+| City | string | City |
+| State | string | Two-character state code (USA) or province (Canada) |
+| Zip | string | ZIP/postal code |
+| Phone | string | Phone number |
+| ElectID | string | Electronic payer ID for claim submission |
+| NoSendElect | string (enum) | Electronic claim sending behavior; see Field Reference |
+| IsHidden | string | "true" or "false" |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+
+---
+
+### GET /carriers/{CarrierNum}
+
+**Version:** 24.4.5
+**Description:** Retrieves a single insurance carrier by primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| CarrierNum | integer | Yes | Primary key of the carrier |
+
+**Response:** Single carrier object (same fields as GET list)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### POST /carriers
+
+**Version:** 21.4
+**Description:** Creates a new insurance carrier.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| CarrierName | string | Yes | Carrier display name |
+| Address | string | No | Street address line 1 |
+| Address2 | string | No | Street address line 2 |
+| City | string | No | City |
+| State | string | No | Two capital characters for USA; province for Canada |
+| Zip | string | No | Format: 12345, 12345-1234, or 123456789 |
+| Phone | string | No | Phone number |
+| ElectID | string | No | Electronic payer ID |
+| NoSendElect | string (enum) | No | Electronic claim behavior; see Field Reference |
+| IsHidden | string | No | "true" or "false" |
+
+**Response:** Created carrier object (same fields as GET list)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+
+---
+
+### PUT /carriers/{CarrierNum}
+
+**Version:** 21.4
+**Description:** Updates an existing insurance carrier. All body fields are optional.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| CarrierNum | integer | Yes | Primary key of the carrier to update |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| CarrierName | string | No | Carrier display name |
+| Address | string | No | Street address line 1 |
+| Address2 | string | No | Street address line 2 |
+| City | string | No | City |
+| State | string | No | Two capital characters for USA; province for Canada |
+| Zip | string | No | Format: 12345, 12345-1234, or 123456789 |
+| Phone | string | No | Phone number |
+| ElectID | string | No | Electronic payer ID |
+| NoSendElect | string (enum) | No | Electronic claim behavior; see Field Reference |
+| IsHidden | string | No | "true" or "false" |
+
+**Response:** Updated carrier object
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### NoSendElect (enum)
+| Value | Description |
+|-------|-------------|
+| SendElect | Send claims electronically |
+| NoSendElect | Do not send claims electronically |
+| NoSendSecondaryElect | Do not send secondary claims electronically |
+
+---
+
+## Implementation Notes
+- `State` must be exactly two uppercase characters for US addresses.
+- `Zip` accepts formats: 12345, 12345-1234, or 123456789.
+- `IsHidden` is a string ("true"/"false"), not a boolean.
+- `ElectID` is the electronic payer ID used for EDI/clearinghouse claim submission.
+- The GET list endpoint (v22.4.16) was added later than POST/PUT (v21.4); single-record GET was added even later (v24.4.5).
+
+---
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| InsPlan | References CarrierNum for patient insurance plans |