Creating New InsPlan

[willhink]

Hello,

If I wanted to create a new insurance plan and attach it to a patient who has an existing appointment, is there an easy/recommended way to do this via the API?

Or would I need to send requests for each step of the process: Delete patplan --> Create insplan --> Create patplan --> Create/Update inssub --> Create benefits --> Update appointments?

Appreciate any feedback!

- Will

[RyanH]

Hello,

If I wanted to create a new insurance plan and attach it to a patient who has an existing appointment, is there an easy/recommended way to do this via the API?

Or would I need to send requests for each step of the process: Delete patplan --> Create insplan --> Create patplan --> Create/Update inssub --> Create benefits --> Update appointments?

Appreciate any feedback!

- Will

Hello willhink,

Requests would need to be made for each step of the process. The order you've written is almost correct, though you'll want to create/update the inssub prior to creating the patplan. Assuming the insurance plan created is of ordinal 1 or 2 (primary or secondary), the patient's appointment will be correctly updated to reflect the insurance plan, so you won't need to call appointments PUT after calling patplans POST.

Thanks!

[willhink]

Hey Ryan,

Thanks for the reply! Good to know about the appointments API.

Another follow-up question in the same vain:

Is it possible to create multiple benefits at the same time? Or do I just need to call the Benefits API multiple times? Just curious if there is some sort of bulk functionality to reduce requests to the endpoint.

Thanks!

[RyanH]

Hey Ryan,

Thanks for the reply! Good to know about the appointments API.

Another follow-up question in the same vain:

Is it possible to create multiple benefits at the same time? Or do I just need to call the Benefits API multiple times? Just curious if there is some sort of bulk functionality to reduce requests to the endpoint.

Thanks!

Benefits must be created in individual requests, one benefit per payload. However, API requests can be sent simultaneously, so you don't need to wait for a response before sending the next request.

Thanks!

[willhink]

Great thanks!

[willhink]

Hey Ryan,

A couple follow-up question:
- How would I create a benefit that is the Individual Deductible for a patient? Would I just use the Benefit API and not set values for CovCatNum, CodeNum, procCode, and CodeGroupNum?

- Also would a Max Benefit for a patient be considered a Limitation?

Thanks!
- Will

[RyanH]

Hey Ryan,

A couple follow-up question:
- How would I create a benefit that is the Individual Deductible for a patient? Would I just use the Benefit API and not set values for CovCatNum, CodeNum, procCode, and CodeGroupNum?

- Also would a Max Benefit for a patient be considered a Limitation?

Thanks!
- Will

Hello willhink,

- How would I create a benefit that is the Individual Deductible for a patient? Would I just use the Benefit API and not set values for CovCatNum, CodeNum, procCode, and CodeGroupNum?

You are correct, to create a General Deductible for the individual or family level, you'd submit a payload without specifying CovCatNum, CodeNum/procCode, or CodeGroupNum. Here's an example payload: (to create one at the family level, supply "Family" for the CoverageLevel)

Code: Select all

//=== General Deductible (Individual) ================
{
	"PlanNum": 1,
	"BenefitType": "Deductible",
	"CoverageLevel": "Individual",
	"TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
	"MonetaryAmt": 50.0
}

- Also would a Max Benefit for a patient be considered a Limitation?

Yes, although it's going to look similar to the payload for creating a deductible. The difference being BenefitType will be "Limitations" instead of "Deductible". As with the previous payload, CoverageLevel can be changed to "Family" to create an Annual Max at the family level.

Code: Select all

//=== Annual Max (Individual) ========================
{
	"PlanNum": 1,
	"BenefitType": "Limitations",
	"CoverageLevel": "Individual",
	"TimePeriod": "ServiceYear",    //Or "CalendarYear" if insplan.MonthRenew=0.
	"MonetaryAmt": 1500.0
}

Hope this helps!

[willhink]

Incredibly helpful, thank you Ryan!

[willhink]

Hey Ryan

I am getting a little tripped up when trying to create Benefits for a plan.

I am sending this payload to the /benefits endpoint:
{
"PlanNum": 33,
"BenefitType": "Limitations",
"CoverageLevel": "None",
"TimePeriod": "CalendarYear",
"QuantityQualifier": "NumberOfServices",
"Quantity": 1,
"procCode": "D0120",
"CovCatNum": 0
}

However, I am being returned a 400 error stating 'procCode is invalid'.

My understanding is that I could use procCode instead of CovCatNum?

I also tried to GET all the procCodes using the /procedurecodes endpoint, however, I am receiving a 401 'Not Authorized error'. Is that API not available in the demo/sandbox environment?

Thanks!
- Will

[RyanH]

Hey Ryan

I am getting a little tripped up when trying to create Benefits for a plan.

I am sending this payload to the /benefits endpoint:
{
"PlanNum": 33,
"BenefitType": "Limitations",
"CoverageLevel": "None",
"TimePeriod": "CalendarYear",
"QuantityQualifier": "NumberOfServices",
"Quantity": 1,
"procCode": "D0120",
"CovCatNum": 0
}

However, I am being returned a 400 error stating 'procCode is invalid'.

My understanding is that I could use procCode instead of CovCatNum?

I also tried to GET all the procCodes using the /procedurecodes endpoint, however, I am receiving a 401 'Not Authorized error'. Is that API not available in the demo/sandbox environment?

Thanks!
- Will

Hey willhink,

procCode can be used instead of CovCatNum to create a benefit for a specific procedure instead of an entire coverage category. The error message indicates the procCode string was not found to belong to any procedurecode entries. I recommend using CodeNum when possible as this is a primary key look up in the procedurecode table rather than a string lookup, though you'd need to be able to run /procedurecodes GET in order to retrieve the CodeNum you're looking for.

Since you're using the demo, it's possible all procedurecode.ProcCode strings start with a "T", as this is how all procedurecodes come in the trial version.

As far as the procedurecodes 401 - 'Not Authorized', I recommend reaching out to us via email to resolve, as we'd need more technical information better suited over email. You can find the API support email in the Developer Portal.

Thanks!

[willhink]

Hey Ryan,

I have another follow-up question regarding benefits:

In the process I am building out, we would first create a new plan and all of its benefits. Then at some later point, my automated process could potentially update that plan and benefits. During the update I would delete all the benefits attached to the plan and then refresh (create) them. This would handle any minor differences to the benefits for the plan instead of doing a one-by-one comparison.

Would deleting benefits have any unforeseen consequences on other parts of the system? Like could a benefit ID be used in billing, for example, and then deleting it would cause issues?

Do you recommend any alternatives to updating the benefits? I know there is the PUT route, but I'm not sure how useful that would be for my use case.

Also, how would the system handle if I created two CoInsurance benefits for the same CodeNum but with different Percent values?

Appreciate any help!
- Will

[RyanH]

Hey Ryan,

I have another follow-up question regarding benefits:

In the process I am building out, we would first create a new plan and all of its benefits. Then at some later point, my automated process could potentially update that plan and benefits. During the update I would delete all the benefits attached to the plan and then refresh (create) them. This would handle any minor differences to the benefits for the plan instead of doing a one-by-one comparison.

Would deleting benefits have any unforeseen consequences on other parts of the system? Like could a benefit ID be used in billing, for example, and then deleting it would cause issues?

Do you recommend any alternatives to updating the benefits? I know there is the PUT route, but I'm not sure how useful that would be for my use case.

Also, how would the system handle if I created two CoInsurance benefits for the same CodeNum but with different Percent values?

Appreciate any help!
- Will

Hey willhink,

Would deleting benefits have any unforeseen consequences on other parts of the system? Like could a benefit ID be used in billing, for example, and then deleting it would cause issues?

Deleting all benefits for a plan shouldn't cause any breaking changes in the software, but it could leave behind some stale data such as estimates, which end up being recalculated in various parts of Open Dental as well as the API so that shouldn't be an issue. I would, however, be cautious of deleting all benefits for a given plan as office staff may have made changes to them. If your software manages insurance plans 100% and the office doesn't do any additional customization outside of your software, the route you described could be feasible.

Do you recommend any alternatives to updating the benefits? I know there is the PUT route, but I'm not sure how useful that would be for my use case.

Benefits PUT would be the recommended route to updating benefits. Updating only what needs to be updated and leaving the records in the database is a much cleaner implementation. I strongly recommend reviewing the API Guide - Benefits and spending some time testing the various payloads in a sandbox.

Also, how would the system handle if I created two CoInsurance benefits for the same CodeNum but with different Percent values?

Duplicated benefits are not known to work in regards to insurance calculations, except when one benefit is plan-wide and the other is a patient override. In version 25.3.7, the API implemented some extra validation to help prevent duplicated benefits for this reason. Do you happen to have a real use case for having two CoInsurance benefits with the same CodeNum on a plan?

Thanks!

[willhink]

Thanks for all the information!

I don't have a real use-case for having two CoInsurance benefits with the same CodeNum on a plan, I was more just curious in case we submitted bad data by mistake.

Also, why is there not an InsPlan DELETE api method? Could this be possible in the future?

Thanks!
- Will

[RyanH]

Thanks for all the information!

I don't have a real use-case for having two CoInsurance benefits with the same CodeNum on a plan, I was more just curious in case we submitted bad data by mistake.

Also, why is there not an InsPlan DELETE api method? Could this be possible in the future?

Thanks!
- Will

Hey willhink,

An insplans DELETE endpoint does not exist as it would involve lots of complex logic, and "dropping" the insplan is the recommended workflow. You can utilize the patplans DELETE and inssubs DELETE endpoints to "drop" an insplan.

Thanks!

[willhink]

Thanks for the insight Ryan!

Another question I had:
I see this page discusses implementing the idea of 'deductible applies/does not apply' for a category:
https://www.opendental.com/manual/deductibles.html

How would that be done via the API? Would I also just create a Deductible Benefit for a Category and set the MonetaryAmt to 0 if the deductible does not apply? Conversely, if the deductible does apply for a category, do I even need to add a benefit or is that default/assumed? I did not see mention of this specific deductible concept in the Benefits Guide you had sent.

Thanks!
- Will

[RyanH]

Thanks for the insight Ryan!

Another question I had:
I see this page discusses implementing the idea of 'deductible applies/does not apply' for a category:
https://www.opendental.com/manual/deductibles.html

How would that be done via the API? Would I also just create a Deductible Benefit for a Category and set the MonetaryAmt to 0 if the deductible does not apply? Conversely, if the deductible does apply for a category, do I even need to add a benefit or is that default/assumed? I did not see mention of this specific deductible concept in the Benefits Guide you had sent.

Thanks!
- Will

Hello willhink,

You are correct, if the General Deductible applies to a category, you would not create a deductible benefit for that category. If the General Deductible does not apply to a category, you would create an individual/family deductible for that category with MonetaryAmt=0. If the category has a deductible different from the General Deductible, you would create a deductible benefit for that category with the specified MonetaryAmt.

Thanks!

[willhink]

Super helpful thanks!

Also, is there currently a way in OpenDental to denote if plan/benefits are In Network vs Out of Network?

Thanks,
Will

[willhink]

Super helpful thanks!

Also, is there currently a way in OpenDental to denote if plan/benefits are In Network vs Out of Network?

Thanks,
Will

Let me know if I should post this network question on a different thread.

[RyanH]

Super helpful thanks!

Also, is there currently a way in OpenDental to denote if plan/benefits are In Network vs Out of Network?

Thanks,
Will

Let me know if I should post this network question on a different thread.

Hello willhink,

This thread is fine. In Open Dental, insplans with a PlanType of PPO Percentage (insplan.PlanType="p"), PPO Fixed Benefit (insplan.PlanType="p" and insplan.CopayFeeSched is set to a Fixed Benefit FeeSchedNum), Medicaid or Flat Co-pay (insplan.PlanType="f"), and Capitation (insplan.PlanType="c") are considered in-network.

Thanks!