API Benefits
Anyone using the API should also become very familiar with our schema documentation which contains important details about individual database table columns.
See Benefit Database Schema.
Benefits GET
Version Added: 22.3.27
Gets all Benefits for a given Insurance Plan or Patient Plan. Empty Percent and MonetaryAmt values are indicated by -1 .
PlanNum: (Optional after version 23.2.62) FK to InsPlan.PlanNum.
PatPlanNum: (Optional after version 23.2.62) FK to PatPlan.PatPlanNum.
Example Requests:
GET /benefits?PlanNum=12
GET /benefits?PatPlanNum=30
Example Response:
[
{
"BenefitNum": 236,
"PlanNum": 12,
"PatPlanNum": 0,
"CovCatNum": 3,
"BenefitType": "CoInsurance",
"Percent": 30,
"MonetaryAmt": -1.0,
"TimePeriod": "None",
"QuantityQualifier": "Visits",
"Quantity": 2,
"CodeNum": 0,
"procCode": "",
"CoverageLevel": "None",
"SecDateTEntry": "2021-06-21 10:03:08",
"SecDateTEdit": "2021-06-21 10:03:08",
"CodeGroupNum": 0
},
{
"BenefitNum": 243,
"PlanNum": 12,
"PatPlanNum": 0,
"CovCatNum": 0,
"BenefitType": "WaitingPeriod",
"Percent": -1,
"MonetaryAmt": -1.0,
"TimePeriod": "ServiceYear",
"QuantityQualifier": "Months",
"Quantity": 3,
"CodeNum": 150,
"procCode": "D0486",
"CoverageLevel": "Family",
"SecDateTEntry": "2021-06-21 10:03:08",
"SecDateTEdit": "2021-06-21 10:03:08",
"CodeGroupNum": 0
},
{
"BenefitNum": 245,
"PlanNum": 12,
"PatPlanNum": 0,
"CovCatNum": 12,
"BenefitType": "Limitations",
"Percent": -1,
"MonetaryAmt": 1000.0,
"TimePeriod": "Lifetime",
"QuantityQualifier": "None",
"Quantity": 0,
"CodeNum": 0,
"procCode": "",
"CoverageLevel": "Individual",
"SecDateTEntry": "2021-06-21 10:03:08",
"SecDateTEdit": "2021-06-21 10:03:08",
"CodeGroupNum": 0
},
etc...
]
200 OK
400 BadRequest (with explanation)
404 NotFound (with explanation)
Benefits POST (create)
Version Added: 22.3.17
Creates a new benefit for a given Insurance Plan or Patient Plan. For more information, see Edit Benefits - Row View.
PlanNum: This or PatPlanNum is required. FK to InsPlan.PlanNum.
PatPlanNum: This or PlanNum is required. FK to PatPlan.PlanNum.
BenefitType: Required. Either "ActiveCoverage", "CoInsurance", "Deductible", "CoPayment", "Exclusions", "Limitations", or "WaitingPeriod".
CoverageLevel: Required. Either "None", "Individual", or "Family".
CovCatNum: Optional. FK to covcat.CovCatNum.
Percent: Optional. Only allowed if BenefitType is "CoInsurance". Must be a value between 0 and 100. Default -1 (Indicating empty).
MonetaryAmt: Optional. Only used if BenefitType is "CoPayment", "Limitations", or "Deductible". Default -1.0 (Indicating empty).
TimePeriod: Optional. Either "None", "ServiceYear", "CalendarYear", "Lifetime", "Years", or "NumberInLast12Months". Default "CalendarYear".
QuantityQualifier: Optional. Either "None", "NumberOfServices", "AgeLimit", "Visits", "Years", or "Months". Default "None". Must be "Months" or "Years" if BenefitType is "WaitingPeriod".
Quantity: Optional. Must be a value between 0 and 100. Default 0. Must be a value greater than 0 if QuantityQualifier is "AgeLimit".
CodeNum: Optional. FK to procedurecode.CodeNum. Only allowed if CovCatNum is 0. Will be used over procCode if both are specified. Default 0.
procCode: Optional. FK to procedurecode.ProcCode. Only allowed if CovCatNum is 0. Default empty string.
CodeGroupNum: Optional. (Added in version 23.2.62) FK to codegroup.CodeGroupNum. The group of procedure codes that apply to this Frequency Limitation benefit.
Example Requests:
POST /benefits
{
"PlanNum": 12,
"CoverageLevel": "None",
"BenefitType": "CoInsurance",
"Percent": 30,
"QuantityQualifier": "Visits",
"Quantity": 2,
"CovCatNum": 3,
"TimePeriod": "None"
}
or
{
"PatPlanNum": 29,
"CoverageLevel": "Individual",
"BenefitType": "Deductible",
"MonetaryAmt": 500,
"CodeNum": 158,
"QuantityQualifier": "AgeLimit",
"Quantity": "15",
"TimePeriod": "Years"
}
or
{
"PlanNum": 19,
"CoverageLevel": "Family",
"BenefitType": "WaitingPeriod",
"QuantityQualifier": "Months",
"Quantity": "6",
"procCode": "D1110",
"TimePeriod": "ServiceYear"
}
or
{
"PlanNum":25,
"BenefitType":"Limitations",
"CoverageLevel":"None",
"Percent":-1,
"MonetaryAmt":-1,
"TimePeriod": "None",
"QuantityQualifier":"AgeLimit",
"Quantity":12,
"CodeGroupNum":1
}
Example Responses:
{
"BenefitNum": 236,
"PlanNum": 12,
"PatPlanNum": 0,
"CovCatNum": 3,
"BenefitType": CoInsurance,
"Percent": 30,
"MonetaryAmt": -1.0,
"TimePeriod": None,
"QuantityQualifier": "Visits",
"Quantity": 2,
"CodeNum": 0,
"procCode": "",
"CoverageLevel": "None",
"SecDateTEntry": "2021-06-21 10:03:08",
"SecDateTEdit": "2021-06-21 10:03:08",
"CodeGroupNum": 0
}
or
{
"BenefitNum": 245,
"PlanNum": 0,
"PatPlanNum": 29,
"CovCatNum": 0,
"BenefitType": "Deductible",
"Percent": -1,
"MonetaryAmt": 500.0,
"TimePeriod": "Years",
"QuantityQualifier": "AgeLimit",
"Quantity": 15,
"CodeNum": 158,
"procCode": "D1120",
"CoverageLevel": "Individual",
"SecDateTEntry": "2021-06-21 10:03:08",
"SecDateTEdit": "2021-06-21 10:03:08",
"CodeGroupNum": 0
}
or
{
"BenefitNum": 246,
"PlanNum": 19,
"PatPlanNum": 0,
"CovCatNum": 0,
"BenefitType": "WaitingPeriod",
"Percent": -1,
"MonetaryAmt": -1.0,
"TimePeriod": "ServiceYear",
"QuantityQualifier": "Months",
"Quantity": 6,
"CodeNum": 157,
"procCode": "D1110",
"CoverageLevel": "Family",
"SecDateTEntry": "2021-06-21 10:03:08",
"SecDateTEdit": "2021-06-21 10:03:08",
"CodeGroupNum": 0
}
or
{
"BenefitNum": 323,
"PlanNum": 25,
"PatPlanNum": 0,
"CovCatNum": 0,
"BenefitType": "Limitations",
"Percent": -1,
"MonetaryAmt": -1.0,
"TimePeriod": "None",
"QuantityQualifier": "AgeLimit",
"Quantity": 12,
"CodeNum": 0,
"procCode": "",
"CoverageLevel": "None",
"SecDateTEntry": "2024-02-13 14:45:19",
"SecDateTEdit": "2024-02-13 14:45:19",
"CodeGroupNum": 1
}
201 Created
400 BadRequest (with explanation)
404 NotFound (with explanation)
Benefits PUT (update)
Version Added: 22.4.7
Updates an existing benefit by BenefitNum. For more information, see Edit Benefits - Row View.
BenefitNum: Required in URL.
CovCatNum: Optional. FK to covcat.CovCatNum.
BenefitType: Optional. Either "ActiveCoverage", "CoInsurance", "Deductible", "CoPayment", "Exclusions", "Limitations", or "WaitingPeriod".
Percent: Optional. Only allowed if BenefitType is "CoInsurance". Must be a value between 0 and 100. Use -1 to indicate empty.
MonetaryAmt: Optional. Only used if BenefitType is "CoPayment", "Limitations", or "Deductible". Use -1 to indicate empty.
TimePeriod: Optional. Either "None", "ServiceYear", "CalendarYear", "Lifetime", "Years", or "NumberInLast12Months".
QuantityQualifier: Optional. Either "None", "NumberOfServices", "AgeLimit", "Visits", "Years", or "Months". Must be "Months" or "Years" if BenefitType is "WaitingPeriod".
Quantity: Optional. Must be a value between 0 and 100. Must be a value greater than 0 if QuantityQualifier is "AgeLimit".
CodeNum: Optional. FK to procedurecode.CodeNum. Only allowed if CovCatNum is 0. Will be used over procCode if both are specified.
procCode: Optional. FK to procedurecode.ProcCode. Only allowed if CovCatNum is 0.
CoverageLevel: Optional. Either "None", "Individual", or "Family".
Example Requests:
PUT /benefits/75
PUT /benefits/323
{
"Percent": 70,
"QuantityQualifier": "Visits",
"Quantity": 2
}
or
{
"CovCatNum": 0,
"BenefitType": "ActiveCoverage",
"Percent": -1,
"MonetaryAmt": 499.99,
"TimePeriod": "ServiceYear",
"QuantityQualifier": "AgeLimit",
"Quantity": 13,
"CodeNum": 156,
"procCode": "D1110",
"CoverageLevel": "Individual"
}
or
{
"Quantity":18
}
Example Response:
{
"BenefitNum": 75,
"PlanNum": 10,
"PatPlanNum": 0,
"CovCatNum": 0,
"BenefitType": "ActiveCoverage",
"Percent": -1,
"MonetaryAmt": 499.99,
"TimePeriod": "ServiceYear",
"QuantityQualifier": "AgeLimit",
"Quantity": 13,
"CodeNum": 156,
"procCode": "D0999",
"CoverageLevel": "Individual",
"SecDateTEntry": "2021-05-25 13:27:52",
"SecDateTEdit": "2021-05-25 13:27:52",
"CodeGroupNum": 0
}
or
{
"BenefitNum": 323,
"PlanNum": 25,
"PatPlanNum": 0,
"CovCatNum": 0,
"BenefitType": "Limitations",
"Percent": -1,
"MonetaryAmt": -1.0,
"TimePeriod": "None",
"QuantityQualifier": "AgeLimit",
"Quantity": 18,
"CodeNum": 0,
"procCode": "",
"CoverageLevel": "None",
"SecDateTEntry": "2024-02-13 14:45:19",
"SecDateTEdit": "2024-02-13 14:45:19",
"CodeGroupNum": 1
}
200 OK
400 BadRequest (with explanation)
404 NotFound (with explanation)
Benefits DELETE
Version Added: 22.4.7
Deletes an existing benefit by BenefitNum.
BenefitNum: Required in URL.
Example Request:
DELETE /benefits/75
Example Response:
200 OK
400 BadRequest (with explanation)
404 NotFound (with explanation)