API Appointments

See API Specification

Appointments GET (single)

Version Added: 21.1

Example Request:
GET /appointments/18

Example Response:
{
"serverDateTime":"2021-05-04 09:32:45",
"AptNum": 18,
"PatNum": 17,
"AptStatus": "Scheduled",
"Pattern": "//XXXX//",
"Confirmed": 19,
"confirmed": "Not Called",
"Op": 3,
"Note": "",
"ProvNum": 1,
"provAbbr": "DOC1",
"ProvHyg": 0,
"AptDateTime": "2020-07-31 08:30:00",
"IsNewPatient": "false",
"ProcDescript": "Seal, Seal",
"ClinicNum": 0,
"IsHygiene": "false",
"DateTStamp":"2021-05-03 08:30:12",
"Priority": "Normal",
"AppointmentTypeNum": 0
}

Appointments GET (multiple)

Version Added: 21.1

Parameters: All optional.

date: For a single day.
dateStart, dateEnd: For a date range, inclusive of both dates.
DateTStamp: Only include appointments with a DateTStamp altered after the specified date and time. This provides a good way for you to keep a synchronized copy of appointments. Store serverDateTime (added in 21.2) that gets returned, and use it to run the next GET.
ClinicNum: Not specifying ClinicNum will get for all clinics because it will not filter on clinics. Use ClinicNum 0 for appointments not attached to clinics.
PatNum: (Added in version 21.4) Filter responses by PatNum.

Example Requests:
GET /appointments?Offset=400
GET /appointments?date=2020-07-30&Offset=200
GET /appointments?dateStart=2020-07-30&dateEnd=2020-08-02&DateTStamp=2020-07-30&ClinicNum=3
GET /appointments?PatNum=20

Example Response:
[
{
"serverDateTime":"2021-05-04 09:32:45",
"AptNum": 4,
"PatNum": 20,
"AptStatus": "Scheduled",
"Pattern": "//XXXX//",
"Confirmed": 19,
"confirmed": "Not Called",
"Op": 2,
"Note": "",
"ProvNum": 3,
"provAbbr": "DOC2",
"ProvHyg": 0,
"AptDateTime": "2020-07-31 09:00:00",
"ProcDescript": "Ex, PA",
"ClinicNum": 0,
"IsHygiene": "false",
"IsNewPatient": "false",
"DateTStamp":"2021-05-03 08:30:12",
"Priority": "Normal",
"AppointmentTypeNum": 0
},
{
"serverDateTime":"2021-05-04 09:32:45",
"AptNum": 3,
"PatNum": 21,
"AptStatus": "Complete",
"Pattern": "//XXXXXX//",
"Confirmed": 19,
"confirmed": "Not Called",
"Op": 6,
"Note": "",
"ProvNum": 3,
"provAbbr": "DOC2",
"ProvHyg": 4,
"AptDateTime": "2020-07-31 09:00:00",
"ProcDescript": "Ex",
"ClinicNum": 0,
"IsHygiene": "true",
"IsNewPatient": "false",
"DateTStamp":"2021-05-03 08:30:12",
"Priority": "Normal",
"AppointmentTypeNum": 1
}
]

Appointments GET (ASAP)

Version Added: 21.1

Gets the ASAP list. An appointment is considered to be on the ASAP list if the Priority field is set to ASAP instead of Normal.

Parameters:

ClinicNum: Required only if Clinics are enabled.
ProvNum: Optional.

Example Requests:
GET /appointments/ASAP
GET /appointments/ASAP?ClinicNum=2
GET /appointments/ASAP?Offset=200

Example Response:
[
{
"serverDateTime":"2021-05-04 09:32:45",
"AptNum": 4,
"PatNum": 20,
"AptStatus": "Scheduled",
"Pattern": "//XXXX//",
"Confirmed": 19,
"confirmed": "Not Called",
"Op": 2,
"Note": "",
"ProvNum": 3,
"provAbbr": "DOC2",
"ProvHyg": 0,
"AptDateTime": "2020-07-31 09:00:00",
"IsNewPatient": "false",
"ProcDescript": "Ex, PA",
"ClinicNum": 0,
"IsHygiene": "false",
"DateTStamp":"2021-05-03 08:30:12",
"Priority": "ASAP",
"AppointmentTypeNum": 1
},
{
"serverDateTime":"2021-05-04 09:32:45",
"AptNum": 3,
"PatNum": 21,
"AptStatus": "Scheduled",
"Pattern": "//XXXXXX//",
"Confirmed": 19,
"confirmed": "Not Called",
"Op": 6,
"Note": "",
"ProvNum": 3,
"provAbbr": "DOC2",
"ProvHyg": 4,
"AptDateTime": "2020-07-31 09:00:00",
"IsNewPatient": "false",
"ProcDescript": "Ex",
"ClinicNum": 0,
"IsHygiene": "true",
"DateTStamp":"2021-05-03 08:30:12",
"Priority": "ASAP",
"AppointmentTypeNum": 0
}
]

Appointments GET SlotsWebSched

Version Added: 21.1

Rarely used.

This gets slots according to the existing logic used for WebSched existing patient or new patient. Customer must first have gone to Setup WebSched (Existing Patient or New Patient) and done all the setup, including creating Appointment Types and linking Appointment Types to WebSched. This all requires a fair amount of setup on the customer's end, but that restriction is usually preferred when patients are making their own appointments.

After calling this method, use Appointments POST WebSched to create a new WebSched appointment.

Parameters:

date: For a single day.
dateStart, dateEnd: For a date range, inclusive of both dates. If no dates at all are supplied, the default is the next two weeks.
ClinicNum: Required if clinics enabled.
defNumApptType: Optional. definition.DefNum where definition.Category=42 (NewPat) or 51 (ExistingPat). There must also be an AppointmentType assigned to that DefNum and it must be set to be used in WebSched.
isNewPatient: Optional. Defaults to false. Just make this match the kind of defNumApptType that you use.

Example Request:
GET /appointments/SlotsWebSched?dateStart=2021-02-15&dateEnd=2021-02-15&defNumApptType=326

Example Response:
[
{
"DateTimeStart": "2021-02-15 08:00:00",
"DateTimeEnd": "2021-02-15 08:30:00",
"ProvNum": 1,
"OpNum": 1
},
{
"DateTimeStart": "2021-02-15 08:30:00",
"DateTimeEnd": "2021-02-15 09:00:00",
"ProvNum": 1,
"OpNum": 1
},
{
"DateTimeStart": "2021-02-15 09:00:00",
"DateTimeEnd": "2021-02-15 09:30:00",
"ProvNum": 1,
"OpNum": 1
},
etc
]

Appointments GET Slots

Version Added: 21.1

This is closer to how search behaves from within Open Dental instead of WebSched. This requires no advanced setup. It looks at open schedule times, whether the schedules are attached to a provider or an operatory.

There are, however, some differences between this and the Search in Open Dental. This returns entire open slots instead of a series of suggested appointment times or the first appointment time for each day. It also currently searches by entire appointment length instead of the XXX provider times on appointments. For single operatories, the results will be the same as what a person would see if looking at the Appointments Module. If a provider has existing appointments in multiple operatories, it considers all of them as a whole and only returns slots that are available in all operatories for that provider simultaneously.

Most users will specify a Provider and an Operatory.

Parameters: All parameters are optional.

date: For a single day. Must be today or a future date. Default is the next 14 days.
dateStart, dateEnd: For a date range, inclusive of both dates.
lengthMinutes: This allows ignoring slots that are too small.
ProvNum: Provider. Defaults to the Practice Default Provider.
OpNum: (Added in version 22.1) The operatory that the provider is assigned to.

Example Request:
GET /appointments/Slots?date=2021-02-15
GET /appointments/Slots?date=2022-03-30&ProvNum=50&OpNum=16
GET /appointments/Slots?ProvNum=1&OpNum=18&dateStart=2022-03-28&dateEnd=2022-04-01

Example Response:
[
{
"DateTimeStart": "2021-02-15 08:00:00",
"DateTimeEnd": "2021-02-15 10:30:00",
"ProvNum": 1,
"OpNum": 1
},
{
"DateTimeStart": "2021-02-15 13:00:00",
"DateTimeEnd": "2021-02-15 15:00:00",
"ProvNum": 1,
"OpNum": 1
},
etc
]

or

[
{
"DateTimeStart": "2022-03-30 07:00:00",
"DateTimeEnd": "2022-03-30 08:20:00",
"ProvNum": 50,
"OpNum": 16
},
{
"DateTimeStart": "2022-03-30 09:00:00",
"DateTimeEnd": "2022-03-30 10:00:00",
"ProvNum": 50,
"OpNum": 16
},
{
"DateTimeStart": "2022-03-30 12:30:00",
"DateTimeEnd": "2022-03-30 13:20:00",
"ProvNum": 50,
"OpNum": 16
},
{
"DateTimeStart": "2022-03-30 13:50:00",
"DateTimeEnd": "2022-03-30 15:00:00",
"ProvNum": 50,
"OpNum": 16
}
]

or

[
{
"DateTimeStart": "2022-03-28 08:00:00",
"DateTimeEnd": "2022-03-28 11:00:00",
"ProvNum": 1,
"OpNum": 18
},
{
"DateTimeStart": "2022-03-29 08:00:00",
"DateTimeEnd": "2022-03-29 08:10:00",
"ProvNum": 1,
"OpNum": 18
},
{
"DateTimeStart": "2022-03-29 08:50:00",
"DateTimeEnd": "2022-03-29 11:00:00",
"ProvNum": 1,
"OpNum": 18
},
{
"DateTimeStart": "2022-03-30 08:00:00",
"DateTimeEnd": "2022-03-30 09:20:00",
"ProvNum": 1,
"OpNum": 18
},
{
"DateTimeStart": "2022-03-30 09:30:00",
"DateTimeEnd": "2022-03-30 11:00:00",
"ProvNum": 1,
"OpNum": 18
},
{
"DateTimeStart": "2022-03-31 08:00:00",
"DateTimeEnd": "2022-03-31 11:00:00",
"ProvNum": 1,
"OpNum": 18
},
{
"DateTimeStart": "2022-04-01 08:00:00",
"DateTimeEnd": "2022-04-01 11:00:00",
"ProvNum": 1,
"OpNum": 18
}
]

Appointments GET WebSched

Version Added: 21.3

Rarely used. Probably just use Appointments GET (multiple) instead.

Gets a list of all appointments, indicating which were made through the WebSched service. This is displayed in the eServiceLogType field as either "Recall", "NewPat", "ExistingPat", or "ASAP". Appointments not made through WebSched will have an eServiceLogType of "None".

Parameters: All parameters are optional.

date: Search for a single day in "yyyy-MM-dd" format.
dateStart, dateEnd: Search for a date range, inclusive of both dates, in "yyyy-MM-dd" format.
DateTStamp: String in "yyyy-MM-dd HH:mm:ss" format.
ClinicNum:

Example Requests:
GET /appointments/WebSched
GET /appointments/WebSched?date=2021-02-15
GET /appointments/WebSched?date=2021-02-15&Offset=200

Example Response:
[
{
"AptNum": 3,
"PatNum": 21,
"AptStatus": "Scheduled",
"Pattern": "//XXXXXX//",
"Confirmed": 19,
"confirmed": "Not Called",
"Op": 6,
"Note": "",
"ProvNum": 3,
"provAbbr": "DOC2",
"ProvHyg": 4,
"AptDateTime": "2021-07-31 09:00:00",
"ProcDescript": "Ex",
"ClinicNum": 0,
"IsHygiene": "True",
"DateTStamp":"2021-08-03 08:30:12",
"serverDateTime":"2021-08-04 09:32:45" ,
"eServiceLogType": "NewPat",
"AppointmentTypeNum": 0
},
{
"AptNum": 35,
"PatNum": 37,
"AptStatus": "Scheduled",
"Pattern": "/XXXX/",
"Confirmed": 19,
"confirmed": "Not Called",
"Op": 5,
"Note": "",
"ProvNum": 3,
"provAbbr": "DOC2",
"ProvHyg": 7,
"AptDateTime": "2021-10-18 13:30:00",
"ProcDescript": "",
"ClinicNum": 2,
"IsHygiene": "False",
"DateTStamp": "2021-08-23 10:52:22",
"serverDateTime": "2021-09-13 09:09:37",
"eServiceLogType": "None",
"AppointmentTypeNum": 1
}
]

200 OK
400 BadRequest (Missing or Invalid fields)

Appointments POST (create)

Version Added: 21.1

The following fields cannot be set as part of a POST: AptNum, provAbbr, and ProcDescript. Attempts to set them will be silently ignored.

PatNum: Required.
Op: Required.
AptDateTime: Required. String in "yyyy-MM-dd HH:mm:ss". Use Appointments GET Slots to find available times.
AptStatus: Optional. Either "Scheduled", "Complete", "UnschedList", "Planned", or (rarely used) "PtNote", "PtNoteCompleted". Default "Scheduled".
Pattern: Optional. Time pattern in 5 minute increments. A string consisting of 'X' and '/' characters only. Default "/XX/" (20 minutes).
Confirmed: Optional. Definition.DefNum where definition.Category=2. Default is the first definition in that Category.
Note: Optional. Default blank.
ProvNum: Optional. Defaults to the PriProv of the patient, if set, or the dental office's default provider.
ProvHyg: Optional. Default 0.
ClinicNum: Optional. Default is the Patient's Clinic, should that not be obtained, then it will set it to 0..
IsHygiene: Optional. Default "false".
IsNewPatient: (Added in version 21.3) Optional. Either "true" or "false". Default "false".
Priority: (Added in version 22.1) Optional. Either "Normal" or "ASAP". Default "Normal".
AppointmentTypeNum: (Added in version 22.1) Optional. FK to AppointmentType.AppointmentTypeNum. Default 0 (None).

Example Request:
POST /appointments

{
"PatNum": 21,
"Op": 6,
"AptDateTime": "2020-07-31 09:00:00"
}

Example Response:
{
"AptNum": 3,
"PatNum": 21,
"AptStatus": "Scheduled",
"Pattern": "/XX/",
"Confirmed": 19,
"confirmed": "Not Called",
"Op": 6,
"Note": "",
"ProvNum": 3,
"provAbbr": "DOC2",
"ProvHyg": 0,
"AptDateTime": "2020-07-31 09:00:00",
"IsNewPatient": "false",
"ProcDescript": "",
"ClinicNum": 0,
"IsHygiene": "false"
"DateTStamp": "",
"serverDateTime": "",
"Priority": "Normal",
"AppointmentTypeNum": 0
}

201 Created Header "location": https://api.opendental.com/api/v1/appointments/3
400 Bad Request (with explanation)
404 NotFound (with explanation)

Appointments POST WebSched

Version Added: 21.3

See Appointments GET WebSched
See Appointments GET SlotsWebSched

Rarely used. Probably just use Appointments POST (create) instead.

Creates a WebSched appointment. This appointment is similar to appointments made through Open Dental's WebSched eServices, which the dental office must have set up.

Prior to running this method, use Appointments GET SlotsWebSched to get the specific timeslots available for WebSched appointments. The ProvNum, OpNum, and time stamps returned from that method are used below.

PatNum: Required.
DateTimeStart: Required. The start time of the appointment timeslot.
DateTimeEnd: Required. The end time of the appointment timeslot.
ProvNum: Required. The ProvNum of the appointment timeslot.
OpNum: Required. The OpNum of the appointment timeslot.
defNumApptType: Required. This must the be the same defNumApptType used to find the timeslot.

Example Request:
POST /appointments/WebSched

{
"PatNum": 21,
"dateTimeStart": "2021-11-19 09:00:00",
"dateTimeEnd":"2021-11-19 09:30:00",
"ProvNum": 5,
"OpNum": 3,
"defNumApptType": 326
}

Example Response:
{
"AptNum": 121,
"PatNum": 21,
"AptStatus": "Scheduled",
"Pattern": "//XX",
"Confirmed": 395,
"confirmed": "Created from Web Sched",
"Op": 3,
"Note": "Appointment Reason: New Patient Exam",
"ProvNum": 5,
"provAbbr": "SMITH",
"ProvHyg": 0,
"AptDateTime": "2021-11-19 09:00:00",
"IsNewPatient": "true",
"ProcDescript": "LimEx, 2BW",
"ClinicNum": 1,
"IsHygiene": "false",
"DateTStamp": "0001-01-01 00:00:00",
"AppointmentTypeNum": 0
}

201 Created
400 BadRequest (Missing or Invalid fields)
404 NotFound "Patient not found" or "Timeslot is no longer available"

Appointments PUT (update)

The following fields cannot be set as part of a PUT: AptNum, PatNum, provAbbr, and ProcDescript. Attempts to set them will be silently ignored. All remaining fields are optional and it is common to only set one or two fields. Note will overwrite any existing note. Use appointments PUT Note to instead append a note.

It is rare to use this method. There would be complex issues involved. It is recommended to instead use Appointments PUT Note, PUT Confirm, and PUT Break.

AptNum: Required in the URL.
AptStatus: Either "Scheduled", "Complete", "UnschedList", "Broken", "Planned", "PtNote", or "PtNoteCompleted".
Pattern: Time pattern in 5 minute increments. A string consisting of 'X' and '/' characters only.
Confirmed: Definition.DefNum where definition.Category=2.
Op: OperatoryNum for a single operatory.
Note: String.
ProvNum: ProvNum for a provider.
ProvHyg: ProvNum for a hygeine provider.
AptDateTime: Start time for the appointment. String in "yyyy-MM-dd HH:mm:ss" format.
ClinicNum: ClinicNum of a clinic.
IsHygiene: Either "true" or "false". True if a hygiene appointment.
IsNewPatient: (Added in version 21.3) Either "true" or "false".
Priority: (Added in version 22.1) Either "Normal" or "ASAP".
AppointmentTypeNum: (Added in version 22.1) FK to AppointmentType.AppointmentTypeNum. Use 0 to indicate None.

Example Request:
PUT /appointments/34

{
"Note":"Note on appointment."
}

Example Response:
200 OK
400 BadRequest (Invalid fields)
404 NotFound "Appointment not found"

Appointments PUT Break

Version Added: 21.3

Breaks an appointment. Only appointments with an AptStatus of Scheduled can be broken. Creates a CommLog entry if the office has that preference turned on.

AptNum: Required in the URL.
sendToUnscheduledList: Required. Either "true" or "false". Usually use "true" to send the broken appointment to the Unscheduled List. This will allow the patient or the office to see that this appointment is ready to be scheduled when they are ready. The only reason you would ever use "false" is if you were setting breakType to "Missed" or "Cancelled". "false" would leave the appointment in place on the appointment book.
breakType: Optional. Rarely used. Only used if you want a procedure to be added, which is usually associated with a fee. Use "Missed" to add a procedure with code D9986, indicating that they missed their appointment without notice. Use "Cancelled" to add procedure with code D9987, indicating less than 24 hrs notice. Normally, if more than 24 hrs notice is given, you would not specify a breakType. These options cannot be used unless the offices has gone to Setup-Appointments-Appts Preferences, and changed the broken appointment procedure type to no longer be "None".

Example Request:
PUT /appointments/5/Break

{
"sendToUnscheduledList":"true"
}

Example Response:
200 OK
400 Bad Request (with explanation)
404 Not Found

Appointments PUT Note

Version Added: 21.1

Only one field is allowed in the JSON object: "Note". The note passed in does not damage any existing note. If a note already exists, a CR is included before adding the new note.

Example Request:
PUT /appointments/34/Note

{
"Note":"Requests reschedule"
}

Example Response:
200 OK
400 Bad Request (with explanation)
404 Not Found

Appointments PUT Confirm

Version Added: 21.1

Only one field is allowed in the JSON object, either confirmVal or defNum. A confirmVal of "None" corresponds to the default status for all new appointments, which is based on the first item listed in Definitions, Appt Confirmed. The other four confirmVal options are managed by the office in eServices Setup, Automated Messaging. Use the defNum field to set the status to any ApptConfirmed type.

confirmVal: Either "None", "Sent", "Confirmed", "Not Accepted", or "Failed".
defNum: (Added in version 21.2) Definition.DefNum where definition.Category=2.

Example Requests:
PUT /appointments/34/Confirm

{
"confirmVal":"Confirmed"
}

{
"defNum":209
}

Example Response:
200 OK
400 Bad Request (with explanation)
404 Not Found