Request to support ClaimStatus Parameter in Post Claims

[avdhutkotkar]

Hello Team,

We would like to request an enhancement to the Open Dental Claims API regarding claim creation with a specified ClaimStatus.

**Current Open Dental UI Behavior:**
When a patient has Primary, Secondary, and Tertiary insurance plans:

* Selecting a procedure and clicking **New Claim** automatically creates a **Secondary claim** with ClaimStatus = **'H' (Hold)**.
* This behavior is handled internally by the Open Dental UI.

The POST `/claims` API does not allow specifying the `ClaimStatus` during claim creation. As a result, when creating a Secondary claim via API:

1. We must first create the claim using POST `/claims`.
2. Then make a second API call to update the claim and set `ClaimStatus = 'H'`.

This requires two API calls to achieve what the UI accomplishes in a single step and is a problem for our application because it reports to us a status indicating the claim is ready to send which we receive sometimes immediately, creating a race condition and then miscommunicate to our users that the claim is ready to be sent.

**Requested Enhancement:**
Option 1 :
Please add support to the POST `/claims` endpoint to allow passing `ClaimStatus` as part of the request payload. This way the claim is created with the correct status at the outset and no miscommunication occurs.
For example:

* Ability to create a claim directly with required status `ClaimStatus = 'H'`. In case, the status is not allowed for the particular type of claim then 400 error.

Option 2 :
We want to mimic the 'New Claim' button behavior of what Open Dental Does.
In our scenario we are deleting all the claims linked to the Procedure and want to recreate them in the same way Open Dental does:

* When user clicks 'New Claim' -> Create Primary Claim with 'W' status, Create Secondary claim with 'H' status and Create Tertiary claim with 'U' status.

Possible way ,
Currently ClaimType is a Required Parameter for claim creation but, if we make it optional and ClaimType parameter is not used then kick in 'New Claim' behavior

POST /claims

{
"PatNum": 1337,
"procNums": [12857, 12859, 12952]
}

This will create multiple claims based the current enrolment of the patient having the appropriate ClaimType and ClaimStatus just like how it happens through UI.

**Benefits:**
* Reduces API calls from two to one.
* Improves performance and simplifies client-side logic.
* We are currently trying to replicate internal Open Dental business logic, but it is a moving target as we continue to find edge cases we were unaware of


We believe this addition would significantly improve API usability for integrations that manage claims programmatically.
Option 2 is preferable as it is aligned with Open Dental UI and drastically reduce API calls when we want to create Primary,Secondary,Tertiary claims for procedures.
Thank you for considering this request. Please let us know if further clarification or examples are needed.

[RyanH]

Hello Team,

We would like to request an enhancement to the Open Dental Claims API regarding claim creation with a specified ClaimStatus.

**Current Open Dental UI Behavior:**
When a patient has Primary, Secondary, and Tertiary insurance plans:

* Selecting a procedure and clicking **New Claim** automatically creates a **Secondary claim** with ClaimStatus = **'H' (Hold)**.
* This behavior is handled internally by the Open Dental UI.

The POST `/claims` API does not allow specifying the `ClaimStatus` during claim creation. As a result, when creating a Secondary claim via API:

1. We must first create the claim using POST `/claims`.
2. Then make a second API call to update the claim and set `ClaimStatus = 'H'`.

This requires two API calls to achieve what the UI accomplishes in a single step and is a problem for our application because it reports to us a status indicating the claim is ready to send which we receive sometimes immediately, creating a race condition and then miscommunicate to our users that the claim is ready to be sent.

**Requested Enhancement:**
Option 1 :
Please add support to the POST `/claims` endpoint to allow passing `ClaimStatus` as part of the request payload. This way the claim is created with the correct status at the outset and no miscommunication occurs.
For example:

* Ability to create a claim directly with required status `ClaimStatus = 'H'`. In case, the status is not allowed for the particular type of claim then 400 error.

Option 2 :
We want to mimic the 'New Claim' button behavior of what Open Dental Does.
In our scenario we are deleting all the claims linked to the Procedure and want to recreate them in the same way Open Dental does:

* When user clicks 'New Claim' -> Create Primary Claim with 'W' status, Create Secondary claim with 'H' status and Create Tertiary claim with 'U' status.

Possible way ,
Currently ClaimType is a Required Parameter for claim creation but, if we make it optional and ClaimType parameter is not used then kick in 'New Claim' behavior

POST /claims

{
"PatNum": 1337,
"procNums": [12857, 12859, 12952]
}

This will create multiple claims based the current enrolment of the patient having the appropriate ClaimType and ClaimStatus just like how it happens through UI.

**Benefits:**
* Reduces API calls from two to one.
* Improves performance and simplifies client-side logic.
* We are currently trying to replicate internal Open Dental business logic, but it is a moving target as we continue to find edge cases we were unaware of


We believe this addition would significantly improve API usability for integrations that manage claims programmatically.
Option 2 is preferable as it is aligned with Open Dental UI and drastically reduce API calls when we want to create Primary,Secondary,Tertiary claims for procedures.
Thank you for considering this request. Please let us know if further clarification or examples are needed.

Hello avdhutkotkar,

Claims can be very complicated, and there is a lot going on under the hood of the UI that if implemented in the API would make the claim endpoints even more convoluted. This is why the 'Medical Claim' workflow from the UI was not directly implemented, but instead the ability to create a medical claim by specifying ClaimType of "Other" paired with an insurance plan where insplan.IsMedical="true" was added, as this is what actually makes a medical claim in the database.

You are correct that clicking 'New Claim' in the UI will generate a secondary claim with ClaimStatus="H", however the API does not support or mimic the 'New Claim' workflow. When you provide ClaimType="S" in /claims POST, the API directly mimics clicking on 'Secondary' on the claim drop down in the UI, which sets ClaimStatus="W". The business logic of Open Dental is the same for the API here. The API supports all claim types (Primary, Secondary, Other - which includes medical and tertiary claims, Cap, and PreAuth), and also allows you to mimic any of the workflows seen in the UI.

• As mentioned above, to create a medical claim you would supply ClaimType="Other" with an InsSubNum associated with a medical insurance plan (insplan.IsMedical="true"). This mimics clicking 'Medical' in the claim drop down.

• To create a tertiary claim, you would supply ClaimType="Other" with an InsSubNum associated with the 3rd lowest ordinal dental insurance plan, and an InsSubNum2 associated with the 2nd lowest ordinal dental insurance plan (InsSubNum2 will be the same inssub that the secondary claim has InsSubNum set to).

• Cap claims are not created by specifying ClaimType="Cap", but instead they are created by specifying an InsSubNum associated with a capitation insurance plan (insplan.PlanType="c"), which also mimics the UI in claim creation. The ClaimType for creating a cap claim depends on the ordinal of the insurance plan (for example, ClaimType="P" would become a cap claim if the lowest ordinal insurance plan is capitation), but it's recommended to use ClaimType="Other".

If your goal is to mimic the 'New Claim' workflow, the recommended approach would be to create each claim (primary, secondary, tertiary) in separate requests, and then use /claims PUT to update the claims accordingly. The API is not able to implement the automated 'New Claim' workflow, as only one claim can be returned by /claims POST, and the ability to mimic this workflow via /claims POST and /claims PUT is already feasible.

Hope this helps!

[mandmdiet]

Thank you RyanH for clarification and your thoughtful consideration of our request.

It makes sense that creation of multiple claims/'New claim' behavior could add unwanted complexity to the implementation and it makes sense why Option 2 is not feasible.

I wanted to make sure, though, that you saw the Option 1 request as well, which was an option instead of #2 and not combined with or connected to it. Option 1 would be a simple additional optional field to the create claim API call allowing us to pass with the request a desired status for the claim new claim to have upon creation. Since it would be an optional field it wouldn't impact other users of the API using this in a different way.

The reason this is important to us is that creating a claim and then updating the claim does affect our application stability.

In a best case scenario, this would introduce a race condition for our application that will mistakenly import this claim if it's in the "Waiting to Send" status. Since it will only be in that status for a few seconds this will happen infrequently and will likely show up in our application as an intermittent bug, which can be hard to diagnose.

In a worst-case scenario the claim creation would succeed but the claim update would fail for whatever reason (network issues with the machine or with the client's internet, etc.). In this scenario we will either eventually successfully make the second call but the claim's status will be wrong for a much longer period of time OR the application will not be able to ever make the second call and the claim will need to be repaired manually.

In our observations of Open Dental's behavior with the database when automatically creating a secondary claim, Open Dental will create the claim and update the claim's status in the same transaction. This means that the behavior in this case would not result in a race condition for us and is behavior we can't currently imitate strictly with API calls.

I appreciate your help and hearing out our requests and for other functionality the Open Dental team has made from our requests in the past. We understand if this is something the Open Dental team isn't able to include in the project road map but wanted to make sure the request was made from our end as clearly as possible.

[justine]

Thank you RyanH for clarification and your thoughtful consideration of our request.

It makes sense that creation of multiple claims/'New claim' behavior could add unwanted complexity to the implementation and it makes sense why Option 2 is not feasible.

I wanted to make sure, though, that you saw the Option 1 request as well, which was an option instead of #2 and not combined with or connected to it. Option 1 would be a simple additional optional field to the create claim API call allowing us to pass with the request a desired status for the claim new claim to have upon creation. Since it would be an optional field it wouldn't impact other users of the API using this in a different way.

The reason this is important to us is that creating a claim and then updating the claim does affect our application stability.

In a best case scenario, this would introduce a race condition for our application that will mistakenly import this claim if it's in the "Waiting to Send" status. Since it will only be in that status for a few seconds this will happen infrequently and will likely show up in our application as an intermittent bug, which can be hard to diagnose.

In a worst-case scenario the claim creation would succeed but the claim update would fail for whatever reason (network issues with the machine or with the client's internet, etc.). In this scenario we will either eventually successfully make the second call but the claim's status will be wrong for a much longer period of time OR the application will not be able to ever make the second call and the claim will need to be repaired manually.

In our observations of Open Dental's behavior with the database when automatically creating a secondary claim, Open Dental will create the claim and update the claim's status in the same transaction. This means that the behavior in this case would not result in a race condition for us and is behavior we can't currently imitate strictly with API calls.

I appreciate your help and hearing out our requests and for other functionality the Open Dental team has made from our requests in the past. We understand if this is something the Open Dental team isn't able to include in the project road map but wanted to make sure the request was made from our end as clearly as possible.

Hello mandmdiet,

Thanks for the detailed follow-up and clearly outlining the risks you're seeing in your integration. We understand the concern around race conditions and partially completed workflows, and you're correct that the OD UI is able to update claim records and statuses in a single transaction.

That said, the Claims API is intentionally designed around explicit, discrete operations, not UI level workflows. While the UI may create or modify multiple related records as part of a single action, the API exposes lower level primitives that map directly to specific actions, rather than high level automation like the New Claim button behavior.

Allowing ClaimStatus to be set would introduce implicit business rules to the Claims POST endpoint. Claim status validity depends on claim type, insurance plan properties, ordinal relationships, and downstream workflows. Enforcing all those constraints reliably at creation would add complexity and ambiguity and would move the endpoint further away from its current goal of being explicit and predictable.

For these reasons, we do not currently plan to add support for specifying ClaimStatus during claim creation. The recommended approach remains:

1. Create claims via claims POST.
2. Update claim status (or any other dependent fields) via claims PUT.

We recognize that this may require additional client side coordination, but this design ensures that API behavior remains consistent, transparent, and aligned with the underlying data model rather than evolving UI workflows.

Thanks!