New API Request

[mandmdiet]

Use Case

1. We import a claim ready to be sent to the carrier into our software.
2. A user determines that one or more of the procedures on the claim need to be edited.
3. The user indicates which fields on the procedure they would like to change.
4. We use the Open Dental API to update the procedure.

Request 1

When a user needs to modify a procedure there are a few scenarios that can occur. Sometimes the procedure must be deleted and recreated and sometimes the claim must also be deleted and recreated. Most of the APIs we would need to do this already exist such as deleting a claim or deleting or updating a procedure.

To support this bare minimum functionality for us we would just need the ability to create a claim in Open Dental via the API. This would need to include providing procedures to include on the claim as well I believe since the Open Dental business logic currently doesn't allow you to create a claim with no procedures on it. So it would be great to be able to just create a claim outright with a claim POST endpoint in the API.

Request 1a

That being said, we do have a few scenarios that we need to support. They are:

Scenario 1 - The claim(s) must be recreated but the procedure(s) only need to be modified

1. Edit Procedure(s)
2. Create new claim(s)
3. Delete old claim(s)

Scenario 2 - Both the claim(s) and the procedure(s) must be recreated

1. Create new Procedure(s)
2. Create new claim(s) (attaching new procedure)
3. Delete old claim(s)
4. Delete old procedure(s)

In either of these scenarios, we're creating the new objects first, then deleting the old objects at the end as cleanup. This is necessary because if we do the deletion first, then something goes wrong and the creation never succeeds, then we have lost data. However, even with the ordering of the steps above, we don't have a great way to implement this reliably because if any of the steps succeed after which any of the steps fail, for example, if steps 1,2 and 4 succeed but step 3 fails we have no way to roll back the successful steps.

To this end, what we'd like to request is an API that allows us to edit procedures that encapsulates the necessary business logic to edit a procedure in Open Dental whether that procedure is attached to a claim or not. So, for example, we pass a PUT command to the Procedure service to change the tooth number on an existing procedure already attached to the claim. In this case, I believe the required steps to make this happen are:

1. Create new Procedure(s)
2. Create new claim(s) (attaching new procedure)
3. Delete old claim(s)
4. Delete old procedure(s)

So, the Open Dental API would in this case do those steps for us in a transaction, preventing the possibility of this process from partially completing and putting the claim or procedure or both in a bad or confusing state for the client. We'd also want it to do some basic checks such as making sure the claim is in a state where it can be modified i.e. it is still unsent and there isn't another claim with the same procedure on it that is already sent (for example when dealing with a sent primary claim and an unsent secondary claim).

Another note, I put an "(s)" at the end of the claim steps above because when editing one or more procedures it could require that one more more claims be changed for example when there is a primary and secondary claim each with their own procedure. Where it appears next to a procedure it is because we'd like to be able to pass in edits for more than one procedure at a time, for example when a user is making an edit to two procedures on the same claim.

Thank you for looking at our request, we look forward to hearing back from you on this.

[SLeon]

Good afternoon,

Thank you for thoroughly describing your use case and concerns. As you mentioned, creating claims and attaching procedures is a common, yet complex, process. With anything we implement in the API, we also want to make sure we do not leave items in "a confusing state for the client".

I have added Claims POST to our development list. This will allow you to create a claim (Primary, Secondary, etc.) for a patient with a list of specified procedures. We will implement this in such a way that the transaction model you describe is not necessary.

I will also point out in your Scenario 2, item 4: ProcedureLogs DELETE can only be used with Treatment Planned procedures. These can only be added to claims with ClaimType of “PreAuth”.

[mandmdiet]

I have added Claims POST to our development list. This will allow you to create a claim (Primary, Secondary, etc.) for a patient with a list of specified procedures. We will implement this in such a way that the transaction model you describe is not necessary.

Thanks SLeon and thank you, again, for taking up one of our API requests and working on it right away. We really appreciate it. Will we be able to get the details of how the POST for claim creation is implemented so that we understand how we need to support it on our end in terms of data consistency with creating / deleting procedures?

I will also point out in your Scenario 2, item 4: ProcedureLogs DELETE can only be used with Treatment Planned procedures. These can only be added to claims with ClaimType of “PreAuth”.

OK, I didn't realize that this was the case. Can the ability to DELETE all procedures be added to that API? We wouldn't want to leave an incorrect procedure in place and simply create a new one as that would give the patient an invalid history and in some cases you can't edit the procedure, such as when you're changing the procedure code and the treatment area is different.

Following this Open Dental documentation, it looks like there are scenarios where it is recommended that other types of procedures be deleted and recreated in order to fix a claim. https://www.opendental.com/manual/claim ... tproc.html.

If you create a claim that contains incorrect procedure codes and have not sent it:

1. Delete the Claim.
2. Edit or delete the procedures.
3. Recreate claim, then send it.

[SLeon]

Yes, we will develop a way for you to delete procedures for this purpose. I will update this thread with more information on Claims POST as it nears completion.

[mandmdiet]

Awesome SLeon, thank you very much.

[beacondental]

It would be great if Claim PUT or Claim POST can have the ability to attach xrays, periocharts, doc narratives to the claim. We would like to the ability to edit attachments and add attachments.

[SLeon]

Are you referring to attachments made in the DXC tab? I ask because web calls to a third party (Dental X Change) occur as part of the validation when attaching these items. We cannot add API methods that make web calls within them.

Or are you referring to the other Attachment tabs, "NEA/Manual" and "Canada"?

[beacondental]

I am referring to DXC tab attachments. We wanted an API protocol for get and post attachments to DXC tab.

[DerekR]

We have completed one of these feature requests. The ProcedureLogs DELETE method can now delete procedures with a ProcStatus of C, "Complete". The enhancement to this method is available starting in our beta version (23.1.11).

See: https://www.opendental.com/site/apiprocedurelogs.html for more information.

[mandmdiet]

Thanks for the update DerekR. Is there any news on the progress of the other feature requests?

[DerekR]

Good Morning,

Claims POST is in the final stages of development, and I expect it to be completed in a couple weeks. We will update this thread as soon as it is available.

[mandmdiet]

Thanks for the response DerekR.

[DerekR]

The feature request for Claims POST has been completed and is available in our beta version, 23.2.5. This method will allow the creation of a Primary, Secondary, or PreAuth Claim. Documentation can be found at https://www.opendental.com/site/apiclaims.html.

[beacondental]

A few questions regarding Claims Post.
1) Will Claims POST allow the API service to skip codes that are marked as "do not bill” codes or $0 procedure codes when posting a claim?
2) Will Claims POST posting and finalizing a claim whereby the total insurance estimate comes to $0 for insurance estimate payment and have it marked as received.

[DerekR]

Good Morning,

When using Claims POST, you can create a claim with a $0 procedure only if the dental office has the preference, "Creating claims with $0 procedures" set to either "Allow" or "Warn". If the dental office has this preference set to "Block", the API will honor this preference and not allow the creation of a Claim with a $0 procedure.

Claims POST will not skip procedures that are marked "No Bill Ins". If you include the procNum of a procedure that is marked "No Bill Ins", you will receive a 400 BadRequest and will need to remove that procedure from the procNums array in order to create a claim.

Claims POST does not finalize a claim, it will only create a new one. ClaimProcs PUT and Claims PUT will allow you to update the claim and mark it as Received.

[beacondental]

Is there a way to create Claim Finalize POST and PUT functions? It is helpful when a claim has $0 of estimated payment, and offices do not want to send a claim just to get a denial.

[DerekR]

To create a claim with $0 procedures, the dental office must have the preference, "Creating claims with $0 procedures" set to either "Allow" or "Warn". Then that claim can be finalized by using the Claims PUT and ClaimProcs PUT methods. Please see https://www.opendental.com/site/apiclaims.html and https://www.opendental.com/site/apiclaimprocs.html for more information.