FHIR API: book appointment with procedure possible?

[bravegag]

Hello,

Is it possible to book an appointment providing the desired procedure e.g. when a patient knows she wants to do invisialign or an implant, these are things the patient may want to do ...

Does the create `appointment` API allows to fit in a desired procedure?

TIA,
Best regards,
Giovanni

[cmcgehee]

Coming soon in 19.2: attach procedures to appointments through FHIR.

[bravegag]

Thanks! looking forward to this

Best regards,
Giovanni

[bravegag]

Hi Chris,

Is this functionality already available in the current 19.2 beta? can you please provide an example or the new FIHR API for 19.2?

Thanks in advance,
Best regards,
Giovanni

[cmcgehee]

Giovanni,

This is available if your Open Dental database is on 19.2. The Appointment resource has two new fields: reasonReference and basedOn. To link completed procedures to a completed appointment, include those procedures in the reasonReference field. To link treatment planned procedures to a scheduled appointment, include those procedures in the basedOn field. Here's an example of what you would POST to the appointment resource (with other fields omitted):

Code: Select all

{
	"status": "fulfilled",
	"start": "2019-07-27T16:00:00",
	"end": "2019-07-27T17:00:00",
	"reasonReference": [{
			"reference": "Procedure/183"
		}, {
			"reference": "Procedure/185"
		}
	]
}

It is important to note that the API endpoint is different for 19.2: it is https://api.opendental.com/fhir/v2/ instead of https://api.opendental.com/fhir/. If you want to use a demo API key, you can use JAvSDW5ezml37elr.

I'll let you know once we're finished with the API documentation for 19.2.

[bravegag]

Hi Chris,

Fantastic! thanks for the throughout response!

Best regards,
Giovanni

[bravegag]

Hi Chris,

I have tried submitting a book appointment request including procedures using the v2 API and it gives the following error:

This is what I submit:

Code: Select all

FHIR POST request https://api.opendental.com/fhir/v2/appointment with body
...
{
  "start": "2019-09-14T09:00:00",
  "end": "2019-09-14T10:00:00",
  "minutesDuration": 60,
  "status": "booked",
  "priority": 5,
  "participant": [
    {
      "actor": {
        "reference": "Patient/221"
      },
      "status": "accepted",
      "type": [
        {
          "code": [
            {
              "code": "PART",
              "system": "http://hl7.org/fhir/participant-type"
            }
          ]
        }
      ]
    },
    {
      "actor": {
        "reference": "Practitioner/1"
      },
      "type": [
        {
          "code": [
            {
              "code": "PPRF",
              "system": "http://hl7.org/fhir/participant-type"
            }
          ]
        }
      ]
    },
    {
      "actor": {
        "reference": "Location/0"
      },
      "type": [
        {
          "code": [
            {
              "code": "PART",
              "system": "http://hl7.org/fhir/participant-type"
            }
          ]
        }
      ]
    }
  ],
  "reasonReference": [
    {
      "reference": "Procedure/1"
    },
    {
      "reference": "Procedure/2"
    },
    {
      "reference": "Procedure/3"
    }
  ]
}

and this is the error I get:

Code: Select all

{"issue":[{"severity":"error","code":"business-rule","details":{"text":"Location (Operatory) does not exist."}},{"severity":"error","code":"business-rule","details":{"text":"At least one procedure must be attached to this appointment. Attachthrough the basedOn or reasonReference fields."}},{"severity":"error","code":"business-rule","details":{"text":"At least one ServiceRequest/Procedure specified in the basedOn or reasonReference fields are invalid. Ensure that the id's are numeric, that the resources exist, and that the resources are ofthe correct type."}}]}

Can you please share a complete example for this use-case? if it's a two-step approach then please include the complete JSON requests ...

TIA,
Best regards,
Giovanni

[cmcgehee]

Here's an example. I'm using the test API key (JAvSDW5ezml37elr) on v2.

First you'll need to create the procedures (unless you want to use ones that are already existing). I make a POST to https://api.opendental.com/fhir/v2/procedure with this body:

Code: Select all

{
	"status": "completed",
	"code": {
		"coding": [{
				"system": "http://hl7.org/fhir/us/sid/cdt",
				"code": "D0140"
			}
		]
	},
	"subject": {
		"reference": "Patient/5"
	},
	"performedDateTime": "2018-12-11T00:00:00",
	"performer": [{
			"actor": {
				"reference": "Practitioner/1"
			},
			"onBehalfOf": {
				"reference": "Organization/0"
			}
		}
	]
}

That request returned an Id of 7854856268706751611. This can be found from the Location header in the response or in the "id" field in the response body.

Then I performed a POST to https://api.opendental.com/fhir/v2/appointment with this body:

Code: Select all

{
	"status": "fulfilled",
	"priority": 5,
	"start": "2019-07-27T16:00:00",
	"end": "2019-07-27T17:00:00",
	"participant": [{
			"type": [{
					"coding": [{
							"system": "http://hl7.org/fhir/participant-type",
							"code": "PART"
						}
					]
				}
			],
			"actor": {
				"reference": "Patient/5"
			},
			"required": "required",
			"status": "needsaction"
		}, {
			"type": [{
					"coding": [{
							"system": "http://hl7.org/fhir/participant-type",
							"code": "SPRF"
						}
					]
				}
			],
			"actor": {
				"reference": "Practitioner/1"
			},
			"required": "required",
			"status": "accepted"
		}, {
			"type": [{
					"coding": [{
							"system": "http://hl7.org/fhir/participant-type",
							"code": "PART",
							"display": "Participation",
							"userSelected": false
						}
					]
				}
			],
			"actor": {
				"reference": "Location/2",
				"display": "OP-2"
			},
			"required": "required",
			"status": "accepted"
		}
	],
	"basedOn": [],
	"reasonReference": [{
			"reference": "Procedure/7854856268706751611"
		}
	]
}

[bravegag]

Hi Chris,

Thanks for your support again

I have multiple questions. First, why does it work when I use your FHIR key and not when I use my personal key? I have updated my OD installation to the latest version.

Second, you use the statuses “fulfilled” and “completed” for the appointment and procedure respectively. In my use-case I’m booking the appointment for the future so would be “booked” for the appointment and what should the status be for the procedure? It hasn’t happened yet and thus, “completed” would not be appropriate or?

Third and last, is there a procedure codes reference somewhere? Are they always the same across practices and locations?

Many TIA,
Best regards,
Giovanni

[cmcgehee]

First, why does it work when I use your FHIR key and not when I use my personal key?

Are you getting the same errors you were getting in the post from Aug 12, 2019 7:09 am? If so, it sounds like the Location resource you're including on the appointment does not exist. First, perform a GET request against the Location resource to figure out which operatory you want the appointment to go into.

Second, you use the statuses “fulfilled” and “completed” for the appointment and procedure respectively. In my use-case I’m booking the appointment for the future so would be “booked” for the appointment and what should the status be for the procedure? It hasn’t happened yet and thus, “completed” would not be appropriate or?

For the procedures, instead of using a Procedure resource with the status "completed", you would use the ServiceRequest resource with a status of "active". In the FHIR standard, a Procedure is something that has happened or is happening, so we had to use their different resource for procedures that we call treatment planned. Then after you've created the ServiceRequest resource, when creating the appointment, you would attach the ServiceRequest to the appointment using the "basedOn" field.

Third and last, is there a procedure codes reference somewhere? Are they always the same across practices and locations?

We use CDT codes from the American Dental Association (at least for practices in the US). This is a proprietary codeset so there isn't any online list I can point you to. If you're on support with Open Dental, you can look at the codes in your program. You could also purchase the official CDT book for a more detailed reference resource: https://www.ada.org/en/publications/ada ... t-products. These codes will be virtually the same across US practices. The only exception you might see is that practices on an older version of Open Dental might not have the latest CDT codes in their database.

Many TIA,
Best regards,
Giovanni[/quote]

[bravegag]

Hello Chris,

Thank you for your support.

I cleared up the first issue, the error was due to a different default organization id for my demo key installation and for the demo key you shared. The default organization id in the former is 0 while in the later is 1. I do now a default organization id auto-discovery and should work for any key in the future.

Thanks! make sense for the second question .. can you please share a MRE (minimal reproducible example) of how to create the service request resource?

Thanks also for the third and last question.

Best regards,
Giovanni

[bravegag]

Hi Chris,

I have been trying to put together a servicerequest creation and I'm getting server errors. This is my request:

Code: Select all

FHIR POST request https://api.opendental.com/fhir/v2/servicerequest 

with body:

Code: Select all

{
  "status": "active",
  "code": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/us/sid/cdt",
        "code": "T1356"
      }
    ]
  },
  "subject": {
    "reference": "Patient/24"
  },
  "occurrenceDateTime": "2019-09-16T11:00:00",
  "performer": [
    {
      "actor": {
        "reference": "Practitioner/1"
      },
      "onBehalfOf": {
        "reference": "Organization/0"
      }
    }
  ]
}

and get back:

Code: Select all

{
  "issue": [
    {
      "severity": "error",
      "code": "exception",
      "details": {
        "text": "The server has encountered an error."
      }
    }
  ]
}

Do you have an example?

Thanks in advance,
Best regards,
Giovanni

[cmcgehee]

Here is an example POST request to create a ServiceRequest. It will create a treatment planned procedure for a filling on tooth 18 on the distal lingual surface for patient 5 with practitioner 1.

Code: Select all

{
	"status": "active",
	"intent": "proposal",
	"code": {
		"coding": [{
				"system": "http://hl7.org/fhir/us/sid/cdt",
				"code": "D2331"
			}
		]
	},
	"subject": {
		"reference": "Patient/5"
	},
	"occurenceDateTime": "2019-11-11T00:00:00",
	"performer": [{
			"reference": "Practitioner/1"
		}
	],
	"bodySite": [{
			"coding": [{
					"system": "http://hl7.org/fhir/ex-tooth",
					"code": "18",
					"display": "18"
				}, {
					"system": "http://hl7.org/fhir/FDI-surface",
					"code": "D",
					"display": "Distal"
				}, {
					"system": "http://hl7.org/fhir/FDI-surface",
					"code": "L",
					"display": "Lingual"
				}
			]
		}
	]
}

The error you were getting was because the practitioner field is different on a ServiceRequest than on a Procedure. In a ServiceRequest, it is simply a list of Reference objects. Again, our business rule is that you can only specify one practitioner in this field. It is a bug on our side that we were showing an internal server error. I'll get that fixed.

One thing I want to make sure you're aware of. All CDT procedure codes start with the letter "D". When you first download Open Dental, it will have codes that start with "T" (for temporary). Once you are signed up for the full version, you need to run the procedure codes tool to replace all "T" codes with the real "D" codes. https://opendental.com/manual/procedurecodetools.html.

[bravegag]

Hi Chris,

Thanks! It's all working

However, I didn't use the `bodySite` entry for now.

Best regards,
Giovanni