@rinse-dental/open-dental 3.4.2 → 4.0.2

package/docs/Open Dental 2026-04-22/context/Open Dental _ Benefits Guide.md

@@ -0,0 +1,294 @@
+This is a guide for the [Benefits API](https://www.opendental.com/site/apibenefits.html) resource. The following payloads can be used to create, modify, or read benefits from the POST, PUT, and GET endpoints respectively. See the [Benefit Database Schema](https://www.opendental.com/OpenDentalDocumentation25-4.xml#benefit) for more information on each field.
+
+Note that this guide doesn't provide examples for all benefits, such as those that would appear in the "Other Benefits" grid. However, a majority of these examples can be applied to other benefits. For example, a CoInsurance benefit for a codegroup would appear in the "Other Benefits" grid, while a CoInsurance benefit for a covcat associated with the Diagnostic EBenefitCategory (see the Categories section) would appear in the "Diagnostic (includes x-ray) \- %" textbox in the UI. This guide references the [Edit Benefits \- Simplified View](https://opendental.com/help254/benefitinfo.html) window in Open Dental.
+
+All examples below are plan-wide benefits. To create a patient override, use PatPlanNum instead of PlanNum.
+
+**Annual Max**  
+Individual level:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+{
+	"PlanNum": 81,
+	"BenefitType": "Limitations",
+	"CoverageLevel": "Individual",
+	"TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
+	"MonetaryAmt": 5.0
+}
+```
+
+Family level:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+{
+	"PlanNum": 81,
+	"BenefitType": "Limitations",
+	"CoverageLevel": "Family",
+	"TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
+	"MonetaryAmt": 5.0
+}
+```
+
+**General Deductible**  
+Individual level:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Deductible",
+	"CoverageLevel": "Individual",
+	"TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
+	"MonetaryAmt": 5.0
+}
+```
+
+Family level:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Deductible",
+	"CoverageLevel": "Family",
+	"TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
+	"MonetaryAmt": 5.0
+}
+```
+
+**Frequency Limitations**  
+Uses CodeGroups. See [CodeGroup Database Schema](https://www.opendental.com/OpenDentalDocumentation25-4.xml#codegroup) and [CodeGroups API Documentation](https://www.opendental.com/site/apicodegroups.html) for more information.
+
+Every \# Years:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Limitations",
+	"CoverageLevel": "None",
+	"CodeGroupNum": 2,
+	"TimePeriod": "None",
+	"Quantity": 4,
+	"QuantityQualifier": "Years",
+	"TreatArea": "None"
+}
+```
+
+\# Per Benefit Year:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Limitations",
+	"CoverageLevel": "None",
+	"CodeGroupNum": 2,
+	"TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
+	"Quantity": 4,
+	"QuantityQualifier": "NumberOfServices",
+	"TreatArea": "None"
+}
+```
+
+Every \# Months:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Limitations",
+	"CoverageLevel": "None",
+	"CodeGroupNum": 2,
+	"TimePeriod": "None",
+	"Quantity": 4,
+	"QuantityQualifier": "Months",
+	"TreatArea": "None"
+}
+```
+
+\# in Last 12 Months:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Limitations",
+	"CoverageLevel": "None",
+	"CodeGroupNum": 2,
+	"TimePeriod": "NumberInLast12Months",
+	"Quantity": 4,
+	"QuantityQualifier": "NumberOfServices",
+	"TreatArea": "None"
+}
+```
+
+**Age Limits**  
+Uses CodeGroups. See [CodeGroup Database Schema](https://www.opendental.com/OpenDentalDocumentation25-4.xml#codegroup) and [CodeGroups API Documentation](https://www.opendental.com/site/apicodegroups.html) for more information.
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Limitations",
+	"CoverageLevel": "None",
+	"CodeGroupNum": 2,
+	"TimePeriod": "None",
+	"Quantity": 16,
+	"QuantityQualifier": "AgeLimit",
+	"TreatArea": "None"
+}
+```
+
+**Ortho**  
+Ortho benefits use a CovCatNum where the EBenefitCategory is Orthodontics (9). See [CovCat Database Schema](https://www.opendental.com/OpenDentalDocumentation25-4.xml#covcat) and [CovCats API Documentation](https://www.opendental.com/site/apicovcats.html) for more information.
+
+Lifetime Max:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Limitations",
+	"CoverageLevel": "None",
+	"CovCatNum": 12,                //covcat.EBenefitCat=9.
+	"TimePeriod": "Lifetime",
+	"MonetaryAmt": 15000,
+	"TreatArea": "None"
+}
+```
+
+Through Age:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Limitations",
+	"CoverageLevel": "None",
+	"CovCatNum": 12,                //covcat.EBenefitCat=9.
+	"TimePeriod": "None",
+	"Quantity": 23,
+	"QuantityQualifier": "AgeLimit",
+	"TreatArea": "None"
+}
+```
+
+Percentage:
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "CoInsurance",
+	"CoverageLevel": "None",
+	"CovCatNum": 12,                //covcat.EBenefitCat=9.
+	"TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
+	"Percent": 80,
+	"TreatArea": "None"
+}
+```
+
+**Categories**  
+The following examples use a CovCatNum associated with a specific EBenefitCategory. The payloads will look similar for all of the coverage categories, requiring only the CovCatNum to change. See [CovCat Database Schema](https://www.opendental.com/OpenDentalDocumentation25-4.xml#covcat) and [CovCats API Documentation](https://www.opendental.com/site/apicovcats.html) for more information. Each category in the 'Edit Benefits' window is associated with a specific covcat.EBenefitCategory. The following shows the mapping of the categories in the UI to their associated EBenefitCategory:
+
+* "Diagnostic (includes x-ray)" → EBenefitCategory.Diagnostic (2)  
+* "X-Ray (if different)" → EBenefitCategory.DiagnosticXRay (13)  
+* "Routine Preventive" → EBenefitCategory.RoutinePreventive (12)  
+* "Restorative" → EBenefitCategory.Restorative (4)  
+* "Endo" → EBenefitCategory.Endodontics (5)  
+* "Perio" → EBenefitCategory.Periodontics (3)  
+* "Oral Surgery" → EBenefitCategory.OralSurgery (11)  
+* "Crowns" → EBenefitCategory.Crowns (7)  
+* "Prosthodontics" → EBenefitCategory.Prosthodontics (10)  
+* "Maxillofacial Prosth" → EBenefitCategory.MaxillofacialProsth (6)  
+* "Accident" → EBenefitCategory.Accident (8)
+
+CoInsurance: *(This example uses the Diagnostic EBenefitCategory)*
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "CoInsurance",
+	"CoverageLevel": "None",
+	"CovCatNum": 2,                 //covcat.EBenefitCat=2.
+	"Percent": 89
+}
+```
+
+Individual Deductible: *(This example uses the Diagnostic EBenefitCategory)*  
+Only the Diagnostic, DiagnosticXRay, and RoutinePreventive EBenefitCategories have specific textboxes in the UI for individual deductibles (not including general deductibles).
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Deductible",
+	"CoverageLevel": "Individual",
+	"CovCatNum": 2,                 //covcat.EBenefitCat=2.
+	"MonetaryAmt": 50.0
+}
+```
+
+Family Deductible: *(This example uses the Diagnostic EBenefitCategory)*  
+Only the Diagnostic, DiagnosticXRay, and RoutinePreventive EBenefitCategories have specific textboxes in the UI for family deductibles (not including general deductibles).
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "Deductible",
+	"CoverageLevel": "Family",
+	"CovCatNum": 2,                 //covcat.EBenefitCat=2.
+	"MonetaryAmt": 75.0
+}
+```
+
+WaitingPeriod: *(This example uses the Restorative EBenefitCategory)*  
+Only the Restorative, Endodontics, Periodontics, OralSurgery, Crowns, and Prosthodontics EBenefitCategories have specific textboxes in the UI for waiting periods.
+
+**Code: [Select all](https://www.opendentalsoft.com:8085/forum/viewtopic.php?t=8645#)**
+
+```
+
+{
+	"PlanNum": 81,
+	"BenefitType": "WaitingPeriod",
+	"CoverageLevel": "None",
+	"CovCatNum": 4,                 //covcat.EBenefitCat=4.
+	"Quantity": 10,
+	"QuantityQualifier": "Months"
+}
+```
+