API Guide - Benefits

[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.

All 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
Uses CodeGroups. See CodeGroup Database Schema and CodeGroups API Documentation for more information.

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
Uses CodeGroups. See CodeGroup Database Schema and CodeGroups API Documentation for more information.

Code: Select all

{
	"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 and CovCats API Documentation for more information.

Lifetime Max:

Code: Select all

{
	"PlanNum": 81,
	"BenefitType": "Limitations",
	"CoverageLevel": "None",
	"CovCatNum": 12,                //covcat.EBenefitCat=9.
	"TimePeriod": "Lifetime",
	"MonetaryAmt": 15000,
	"TreatArea": "None"
}

Through Age:

Code: Select all

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

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