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!

[willhink]

Hey Ryan,

Another question I had, is it possible to update the "Benefits Last Verified" field via the API? The idea being that I create a new InsPlan and Benefits, then I populate that field with the current date.

Screenshot 2026-05-01 at 2.58.06 PM.png (21.74 KiB) Viewed 139046 times

Thanks!

[RyanH]

Hey Ryan,

Another question I had, is it possible to update the "Benefits Last Verified" field via the API? The idea being that I create a new InsPlan and Benefits, then I populate that field with the current date.

Screenshot 2026-05-01 at 2.58.06 PM.png

Thanks!

Hello willhink,

To populate that box, you can call /insverifies PUT with VerifyType="InsuranceBenefit", FKey=insplan.PlanNum you're updating, and the desired date in the DateLastVerified field. See InsVerifies PUT for more information.

Thanks!

[willhink]

Hello again RyanH,

Thanks for the help with regards to DateLastVerified.

I see how I am currently able to add the Annual Max and General Deductible as benefits via the API.

Is it possible to also add the Ins Used and Deductible Remaining via the API?

Thanks!

[RyanH]

Hello again RyanH,

Thanks for the help with regards to DateLastVerified.

I see how I am currently able to add the Annual Max and General Deductible as benefits via the API.

Is it possible to also add the Ins Used and Deductible Remaining via the API?

Thanks!

Hello willhink,

The Ins Used and Deductible Remaining fields are calculated at runtime and are not actually stored in the DB, so it is not possible to access these fields via the API.

Thanks!

[willhink]

Hi RyanH,

Another question I had: If a plan has age dependent benefits, how should that be handled in OpenDental? For example, if a plan has age dependent frequency limits. Should we create separate plans (one for pediatric and one for adult) or is there a way to model this on the same plan in OpenDental?

Thank you!
- Will

[RyanH]

Hi RyanH,

Another question I had: If a plan has age dependent benefits, how should that be handled in OpenDental? For example, if a plan has age dependent frequency limits. Should we create separate plans (one for pediatric and one for adult) or is there a way to model this on the same plan in OpenDental?

Thank you!
- Will

Hello willhink,

If a plan's benefit varies based on the patient's age, but the benefit is not an age limitation, you can specify PatPlanNum in the /benefits POST endpoint to create a patient override benefit.

For example, suppose a plan allows adults two cleanings per year and pediatric patients three cleanings per year. You could create a frequency limitation of two cleanings per year on the base plan by supplying PlanNum. Then, for each pediatric patient enrolled in the plan, you could create a patient override frequency limitation of three cleanings per year by supplying that patient's PatPlanNum.

Thanks!

[willhink]

Ahh super helpful, thanks!

[willhink]

Hi RyanH,

Another question. If a plan has 'No Maximum', how should this modeled in OpenDental? Would I skip creating the annual max limitation? Or maybe I populate its MonetaryAmt with 0 or 9999?

Thanks!
- Will

[RyanH]

Hi RyanH,

Another question. If a plan has 'No Maximum', how should this modeled in OpenDental? Would I skip creating the annual max limitation? Or maybe I populate its MonetaryAmt with 0 or 9999?

Thanks!
- Will

Hello willhink,

If a plan has no annual maximum, you would be correct in not creating an annual max limitation (for both the individual and family level).

Thanks!

[willhink]

Thanks RyanH,

I know previously we had spoken about how to properly create an insurance plan and attach it to a patient in OpenDental. I was hoping you could provide some more details about the effect of doing that in the OpenDental system (procedure history, max/deductible used, claims, reporting, etc).

Some background on what I have been working on:
A patient in OpenDental is attached to a plan that the office had created. The existing plan could be incomplete, incorrect, or even perfectly fine. However, we would want to create a new optimized plan that we would fully manage/update in an automated fashion via the OpenDental API instead of office input. Once the new plan has been created, we could then also move other patients to that shared plan via the API.

I am just trying to understand any downstream repercussions of switching patients to a new plan (even if it is just Aetna "Bad" to Aetna "Optimized")?
I know this is not your recommended flow, but I see that the InsSubs API has a PUT endpoint where we could directly swap the PlanNum. Could that be safely utilized for our purpose?

Appreciate all the help!
- Will

[justine]

Thanks RyanH,

I know previously we had spoken about how to properly create an insurance plan and attach it to a patient in OpenDental. I was hoping you could provide some more details about the effect of doing that in the OpenDental system (procedure history, max/deductible used, claims, reporting, etc).

Some background on what I have been working on:
A patient in OpenDental is attached to a plan that the office had created. The existing plan could be incomplete, incorrect, or even perfectly fine. However, we would want to create a new optimized plan that we would fully manage/update in an automated fashion via the OpenDental API instead of office input. Once the new plan has been created, we could then also move other patients to that shared plan via the API.

I am just trying to understand any downstream repercussions of switching patients to a new plan (even if it is just Aetna "Bad" to Aetna "Optimized")?
I know this is not your recommended flow, but I see that the InsSubs API has a PUT endpoint where we could directly swap the PlanNum. Could that be safely utilized for our purpose?

Appreciate all the help!
- Will

Hello willhink,

An insurance plan in Open Dental may be used by multiple subscribers. Because of this, updating an existing InsPlan affects other subscribers who use that plan.

If the existing plan information is incomplete or incorrect for everyone using that plan, the existing plan should generally be updated rather than creating a duplicate plan. Creating duplicate plans can make the insurance data difficult for the office to maintain. For example, if an annual maximum or benefit changes, that information would then need to be maintained across multiple plans instead of one.

If the patient has actually changed to a new insurance plan, the existing coverage should be dropped and the new coverage added. Changing PlanNum on an existing InsSub changes the plan association for the subscriber and for any other patients whose PatPlan is attached to that InsSub. This can alter historical insurance information by making those patients appear to have been covered by the new plan instead of the old plan. Prior claims, claimprocs, and other records associated with the old plan need to remain associated with that plan in order to preserve insurance history.

For this reason, we strongly recommend against using InsSubs PUT to change PlanNum.

Determining whether incoming insurance information represents a correction to a shared plan, a subscriber-specific change, or genuinely new coverage depends on the data being received and needs to be handled by the integrating application.

Thanks!

[willhink]

Hi Justine,

Thanks for the information. In this scenario:
- Patient was on the wrong plan for their appointment and a claim was created
- Then we created a new plan and correctly attached the proper patient/subscriber to it.

Is it possible to point the claim to the correct plan (InsSub) after the fact? What is the recommended process in OpenDental to move claims and history?

Thanks,
Will

[RyanH]

Hi Justine,

Thanks for the information. In this scenario:
- Patient was on the wrong plan for their appointment and a claim was created
- Then we created a new plan and correctly attached the proper patient/subscriber to it.

Is it possible to point the claim to the correct plan (InsSub) after the fact? What is the recommended process in OpenDental to move claims and history?

Thanks,
Will

Hello willhink,

The InsSubNum attached to a claim should never be changed. This is not possible in the Open Dental UI or the OD API. The one and only case where it would make sense to 'correct' a claim to point to a new inssub is when that claim has not already been sent or received. In which case, you would not be updating the existing claim, you would delete the invalid claim and create a new one. Is this the case for your proposed workflow, or is the claim already sent/received in your described scenario?

As Justine mentioned above, changing the PlanNum on an existing inssub would result in previous historical information being changed, which would invalidate all previous history for received claims, claimpayments, claimprocs, etc, for not only the subscriber but all patients covered under the subscriber. Please re-review the first couple of posts in this thread where the correct workflow for dropping a plan and assigning a new plan to a patient was outlined. If the insplan for the subscriber needs to change, you would create a new inssub instead of updating an existing inssub.

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!

Thanks!