API Guide - Benefits

For requests or help with our API
Locked
RyanH
Posts: 74
Joined: Thu Dec 19, 2024 8:33 am

API Guide - Benefits

Post by RyanH »

This is a guide for the Benefits API 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 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 window in Open Dental.

Most examples below are plan-wide benefits. To create a patient override, use PatPlanNum instead of PlanNum.

Annual Max
Individual level:

Code: Select all

{
  "PlanNum": 81,
  "BenefitType": "Limitations",
  "CoverageLevel": "Individual",
  "TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
  "MonetaryAmt": 5.0
}
Family level:

Code: Select all

{
  "PlanNum": 81,
  "BenefitType": "Limitations",
  "CoverageLevel": "Family",
  "TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
  "MonetaryAmt": 5.0
}

General Deductible
Individual level:

Code: Select all

{
  "PlanNum": 81,
  "BenefitType": "Deductible",
  "CoverageLevel": "Individual",
  "TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
  "MonetaryAmt": 5.0
}
Family level:

Code: Select all

{
  "PlanNum": 81,
  "BenefitType": "Deductible",
  "CoverageLevel": "Family",
  "TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
  "MonetaryAmt": 5.0
}

Frequency Limitations
The "Frequency Limitation Benefits" grid only displays frequency limitations utilizing codegroups. See CodeGroup Database Schema and CodeGroups API Documentation for more information. Frequency limitations can also use procedurecodes, which would display in the "Other Benefits" grid. Additionally, a frequency limitation can specify a TreatArea to restrict the benefit to a specific treatment area.

Every # Years:

Code: Select all

{
  "PlanNum": 81,
  "BenefitType": "Limitations",
  "CoverageLevel": "None",
  "CodeGroupNum": 2,
  "TimePeriod": "None",
  "Quantity": 4,
  "QuantityQualifier": "Years",
  "TreatArea": "None"
}
# Per Benefit Year:

Code: Select all

{
  "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

{
  "PlanNum": 81,
  "BenefitType": "Limitations",
  "CoverageLevel": "None",
  "CodeGroupNum": 2,
  "TimePeriod": "None",
  "Quantity": 4,
  "QuantityQualifier": "Months",
  "TreatArea": "None"
}
# in Last 12 Months:

Code: Select all

{
  "PlanNum": 81,
  "BenefitType": "Limitations",
  "CoverageLevel": "None",
  "CodeGroupNum": 2,
  "TimePeriod": "NumberInLast12Months",
  "Quantity": 4,
  "QuantityQualifier": "NumberOfServices",
  "TreatArea": "None"
}
Age Limits
The "Age Limits" grid only displays plan-wide age limitations utilizing codegroups. See CodeGroup Database Schema and CodeGroups API Documentation for more information. Patient override age limitations utilizing codegroups, along with age limitations utilizing covcats or procedurecodes, will display in the "Other Benefits" grid, with the exception of an age limitation utilizing the Ortho covcat (see the Ortho - Through Age section).

Beginning in version 26.2.5, age limitations can specify a ToothRange to limit coverage to specific teeth. For example, sealant procedures for teeth 3, 14, 19, and 30 may be covered only through age 8. Age limitations also allow for different age-based spans of coverage. Using the previous example, an age limitation of 12 for teeth 2, 15, 18, and 31 for the same codegroup/procedurecode/covcat may also be specified at the same plan level (plan-wide or patient override). This allows coverage for specific teeth through age 8 and coverage for other specific teeth through age 12.

However, two age limitations may not be specified at the same plan level (plan-wide or patient override) for the same codegroup/procedurecode/covcat if either of the following is true:
  • A tooth is specified in both ToothRanges, causing an overlap in coverage and assigning more than one age limit to the same tooth.
    Ex: AgeLimit 8 on teeth 3,4,5 and AgeLimit 12 on teeth 5,6,7.
  • Both benefits specify the same age. In this scenario, the two benefits should be combined into one.
    Ex: AgeLimit 8 on teeth 3,14 and AgeLimit 8 on teeth 19,30.
CodeGroup AgeLimit: (Displays in the "Age Limits" grid)

Code: Select all

{
  "PlanNum": 81,
  "BenefitType": "Limitations",
  "CoverageLevel": "None",
  "CodeGroupNum": 2,
  "TimePeriod": "None",
  "Quantity": 12,
  "QuantityQualifier": "AgeLimit",
  "TreatArea": "None",
  "ToothRange": "2,15,18,31"
}
General AgeLimit: (Displays in the "Other Benefits" grid)

Code: Select all

{
  "PatPlanNum": 79,
  "BenefitType": "Limitations",
  "CoverageLevel": "None",
  "CodeNum": 40,
  "TimePeriod": "None",
  "Quantity": 8,
  "QuantityQualifier": "AgeLimit",
  "TreatArea": "None",
  "ToothRange": "3,14,19,30"
}
Ortho
The following Ortho benefits use a CovCatNum where the EBenefitCategory is Orthodontics (9). See CovCat Database Schema and CovCats API Documentation for more information. Ortho procedures may also be covered by benefits that utilize codegroups or procedurecodes, however those benefits would be displayed in the "Other Benefits" grid.

Lifetime Max:

Code: Select all

{
  "PlanNum": 81,
  "BenefitType": "Limitations",
  "CoverageLevel": "None",
  "CovCatNum": 12,                //covcat.EBenefitCat=9.
  "TimePeriod": "Lifetime",
  "MonetaryAmt": 15000,
  "TreatArea": "None"
}
Through Age:
ToothRange must be blank for this benefit to appear in the "Through Age" textbox. If an age limit specifying teeth is set up for the Ortho covcat, it will be displayed in the "Other Benefits" grid.

Code: Select all

{
  "PlanNum": 81,
  "BenefitType": "Limitations",
  "CoverageLevel": "None",
  "CovCatNum": 12,                //covcat.EBenefitCat=9.
  "TimePeriod": "None",
  "Quantity": 23,
  "QuantityQualifier": "AgeLimit",
  "TreatArea": "None",
  "ToothRange": ""
}
Percentage:

Code: Select all

{
  "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 and CovCats API Documentation 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

{
  "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

{
  "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

{
  "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

{
  "PlanNum": 81,
  "BenefitType": "WaitingPeriod",
  "CoverageLevel": "None",
  "CovCatNum": 4,                 //covcat.EBenefitCat=4.
  "Quantity": 10,
  "QuantityQualifier": "Months"
}
Top
Locked

Return to “API”