Online Booking API

Complete

The OpenVPMS Booking API is a JSON API for making appointments in OpenVPMS.
This API first appears in OpenVPMS 2.0.

The current production version is the Online Booking API V2.

Online Booking API V1

Complete

The OpenVPMS Booking API is a JSON API for making appointments in OpenVPMS. This API first appears in OpenVPMS 2.0.

The following assumes:

OpenVPMS is accessed at http://localhost:8080/openvpms
a user with login name 'sample' and password 'changeit' exists, and has been assigned the Online Booking role

The openvpms-booking-api-v1.zip contains API documentation generated by Enunciate. Extract and browse from index.html.

You can also get an overview by browsing http://localhost:8080/openvpms/ws/booking/v1/application.wadl

Locations

To get the locations:

> curl -i -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/locations
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 126
Date: Tue, 25 Jul 2017 03:33:24 GMT

[{"id":99,"name":"Branch Clinic","timeZone":"Australia/Sydney"},
 {"id":113,"name":"Main Clinic","timeZone":"Australia/Sydney"}]

Notes:

for a location to be returned, its Online Booking flag must be ticked.

To get the schedules available at a location:

> curl -i -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/locations/113/schedules
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 117
Date: Tue, 25 Jul 2017 03:35:34 GMT

[{"id":144,"name":"Main Appointment Schedule","slotSize":15},
 {"id":130,"name":"Main Surgery Schedule","slotSize":30}]

For a schedule to be returned, its Online Booking flag must be ticked.

Appointment Types

To get the appointment types applicable to a schedule:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/schedules/144/appointmentTypes
[{"id":62,"name":"New Patient","slots":2},
 {"id":52,"name":"Long Consult","slots":2},
 {"id":50,"name":"Standard Consult","slots":1},
 {"id":46,"name":"Short Consult","slots":1}]

Notes:

the same appointment type may be used by multiple schedules, each with a different slot size
for an appointment type to be returned, its Online Booking flag must be ticked.

Free/Busy

A number of methods are provided to get free and busy times:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v1/schedules/144/free?from=2016-05-15T00:00:00%2B10:00&to=2016-05-16T00:00:00%2B10:00'
[{"start":"2016-05-15T10:30:00.000+10:00","end":"2016-05-15T11:00:00.000+10:00"},
 {"start":"2016-05-15T11:30:00.000+10:00","end":"2016-05-15T17:30:00.000+10:00"}]

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v1/schedules/144/busy?from=2016-05-15T00:00:00%2B10:00&to=2016-05-16T00:00:00%2B10:00'
[{"start":"2016-05-15T09:00:00.000+10:00","end":"2016-05-15T10:30:00.000+10:00"},
 {"start":"2016-05-15T11:00:00.000+10:00","end":"2016-05-15T11:30:00.000+10:00"}]

If you want both free and busy times, its more efficient to do a single call:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v1/schedules/144/freebusy?from=2016-05-15T00:00:00%2B10:00&to=2016-05-16T00:00:00%2B10:00'
{"free":[{"start":"2016-05-15T10:30:00.000+10:00","end":"2016-05-15T11:00:00.000+10:00"},  {"start":"2016-05-15T11:30:00.000+10:00","end":"2016-05-15T17:30:00.000+10:00"}],
 "busy":[{"start":"2016-05-15T09:00:00.000+10:00","end":"2016-05-15T10:30:00.000+10:00"},
              {"start":"2016-05-15T11:00:00.000+10:00","end":"2016-05-15T11:30:00.000+10:00"}]}

To return the free and busy times in slots, specify &slots=true e.g.:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v1/schedules/144/free?from=2016-05-15T00:00:00%2B10:00&to=2016-05-16T00:00:00%2B10:00&slots=true'
[{"start":"2016-05-15T10:00:00.000+10:00","end":"2016-05-15T10:15:00.000+10:00"},
{"start":"2016-05-15T10:15:00.000+10:00","end":"2016-05-15T10:30:00.000+10:00"},
{"start":"2016-05-15T10:30:00.000+10:00","end":"2016-05-15T10:45:00.000+10:00"},
{"start":"2016-05-15T10:45:00.000+10:00","end":"2016-05-15T11:00:00.000+10:00"},
{"start":"2016-05-15T11:30:00.000+10:00","end":"2016-05-15T11:45:00.000+10:00"},
{"start":"2016-05-15T11:45:00.000+10:00","end":"2016-05-15T12:00:00.000+10:00"},
{"start":"2016-05-15T12:00:00.000+10:00","end":"2016-05-15T12:15:00.000+10:00"},
{"start":"2016-05-15T12:15:00.000+10:00","end":"2016-05-15T12:30:00.000+10:00"},
{"start":"2016-05-15T12:30:00.000+10:00","end":"2016-05-15T12:45:00.000+10:00"},
{"start":"2016-05-15T12:45:00.000+10:00","end":"2016-05-15T13:00:00.000+10:00"},
{"start":"2016-05-15T13:00:00.000+10:00","end":"2016-05-15T13:15:00.000+10:00"},
{"start":"2016-05-15T13:15:00.000+10:00","end":"2016-05-15T13:30:00.000+10:00"},
{"start":"2016-05-15T13:30:00.000+10:00","end":"2016-05-15T13:45:00.000+10:00"},
{"start":"2016-05-15T13:45:00.000+10:00","end":"2016-05-15T14:00:00.000+10:00"},
{"start":"2016-05-15T14:00:00.000+10:00","end":"2016-05-15T14:15:00.000+10:00"},
{"start":"2016-05-15T14:15:00.000+10:00","end":"2016-05-15T14:30:00.000+10:00"},
{"start":"2016-05-15T14:30:00.000+10:00","end":"2016-05-15T14:45:00.000+10:00"},
{"start":"2016-05-15T14:45:00.000+10:00","end":"2016-05-15T15:00:00.000+10:00"},
{"start":"2016-05-15T15:00:00.000+10:00","end":"2016-05-15T15:15:00.000+10:00"},
{"start":"2016-05-15T15:15:00.000+10:00","end":"2016-05-15T15:30:00.000+10:00"},
{"start":"2016-05-15T15:30:00.000+10:00","end":"2016-05-15T15:45:00.000+10:00"},
{"start":"2016-05-15T15:45:00.000+10:00","end":"2016-05-15T16:00:00.000+10:00"},
{"start":"2016-05-15T16:00:00.000+10:00","end":"2016-05-15T16:15:00.000+10:00"},
{"start":"2016-05-15T16:15:00.000+10:00","end":"2016-05-15T16:30:00.000+10:00"},
{"start":"2016-05-15T16:30:00.000+10:00","end":"2016-05-15T16:45:00.000+10:00"},
{"start":"2016-05-15T16:45:00.000+10:00","end":"2016-05-15T17:00:00.000+10:00"},
{"start":"2016-05-15T17:00:00.000+10:00","end":"2016-05-15T17:15:00.000+10:00"},
{"start":"2016-05-15T17:15:00.000+10:00","end":"2016-05-15T17:30:00.000+10:00"}]

Submitting Bookings

> curl -u sample:changeit -H "Content-Type: application/json" --data @booking.json http://localhost:8080/openvpms/ws/booking/v1/bookings

Where booking.json is a file containing:

{
  "location": 113,
  "schedule": 144,
  "appointmentType": 50,
  "start": "2016-05-15T10:30:00.000+10:00",
  "end": "2016-05-15T11:00:00.000+10:00",
  "title": "Ms",
  "firstName": "Judith",
  "lastName": "Bourke",
  "mobile": "0418976543",
  "patientName": "Muffett"
}

Notes:

the email and phone attributes can be specified as well.
a booking customer is considered a match if its firstName and lastName are equal to an OpenVPMS customer, ignoring case, and at least one of the 3 contacts are present.
the reference returned is a concatenation of the appointment identifier, customer identifier and UUID. This is to:
- make it harder to retrieve/cancel bookings not made through the API
- prevent retrieval of appointments subsequently assigned to another customer

Retrieving Bookings

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/bookings/603:3:be08f3c6-1afb-11e6-be41-3dbaef689d97

Notes:

the mobile, phone and email submitted with the request are not stored; the values returned are those associated with the existing customer
the notes aren't returned as these may have been updated since the booking was made and contain information that shouldn't be disclosed

Cancelling Bookings

> curl -X DELETE -u sample:changeit http://localhost:8080/openvpms/ws/booking/v1/bookings/391:a98f02c9-1a4b-...

Notes:

bookings can only be cancelled while their corresponding appointment is pending
once cancelled, bookings cannot be retrieved

Security

There are a number of security considerations to be aware of:

an OpenVPMS user account is required to make online bookings. This should be a restricted account that only has the authorities required to make online bookings.
This can be done by creating a user that only has the Online Booking role assigned.
the OpenVPMS web application should not be exposed to the wider internet to allow external providers to connect. Restricted access can be provided through a VPN, IP filtering, and/or URL filtering. For the purposes of online booking, only the:
/openvpms/ws/booking
URL should be exposed.

Online Booking API V2

Complete

The OpenVPMS Booking API V2 is a JSON API for making appointments in OpenVPMS.

The following assumes:

OpenVPMS is accessed at http://localhost:8080/openvpms
a user with login name 'sample' and password 'changeit' exists, and has been assigned the Online Booking role
Online Booking has been configured
Rostering has been configured

The openvpms-booking-api-v2-draft.zip contains API documentation generated by Enunciate. Extract and browse from index.html.

You can also get an overview by browsing http://localhost:8080/openvpms/ws/booking/v2/application.wadl

Locations

To get the locations:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/locations
[{"id":106,"name":"Branch Clinic","timeZone":"Australia/Sydney"},
 {"id":98,"name":"Main Clinic","timeZone":"Australia/Sydney"}]

Notes:

for a location to be returned, its Online Booking flag must be ticked.

To get the schedules available at a location:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/locations/98/schedules
[{"id":136,"name":"Main Appointment Schedule","slotSize":15},
 {"id":211,"name":"Main Surgery Schedule","slotSize":30}]

Notes:

For a schedule to be returned, its Online Booking flag must be ticked.

Appointment Types

To get the appointment types applicable to a schedule:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/schedules/136/appointmentTypes
[{"id":79,"name":"Short Consult","slots":1},
 {"id":66,"name":"Standard Consult","slots":1},
 {"id":63,"name":"Long Consult","slots":2},
 {"id":76,"name":"New Patient","slots":2}]

Notes:

the same appointment type may be used by multiple schedules, each with a different slot size
for an appointment type to be returned, its Online Booking flag must be ticked.

Free/Busy

A number of methods are provided to get free and busy times:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/schedules/136/free?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00'
[{"start":"2019-02-15T09:00:00.000+11:00","end":"2019-02-15T10:45:00.000+11:00"},
 {"start":"2019-02-15T11:30:00.000+11:00","end":"2019-02-15T17:30:00.000+11:00"}]

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/schedules/136/busy?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00'
[{"start":"2019-02-15T10:45:00.000+11:00","end":"2019-02-15T11:30:00.000+11:00"}]

If you want both free and busy times, its more efficient to do a single call:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/schedules/136/freebusy?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00'
{"free":[{"start":"2019-02-15T09:00:00.000+11:00","end":"2019-02-15T10:45:00.000+11:00"},{"start":"2019-02-15T11:30:00.000+11:00","end":"2019-02-15T17:30:00.000+11:00"}],
 "busy":[{"start":"2019-02-15T10:45:00.000+11:00","end":"2019-02-15T11:30:00.000+11:00"}]}

To return the free and busy times in slots, specify &slots=true e.g.:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/schedules/136/free?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00&slots=true'
[{"start":"2019-02-15T09:00:00.000+11:00","end":"2019-02-15T09:15:00.000+11:00"},
 {"start":"2019-02-15T09:15:00.000+11:00","end":"2019-02-15T09:30:00.000+11:00"},
 {"start":"2019-02-15T09:30:00.000+11:00","end":"2019-02-15T09:45:00.000+11:00"},
 {"start":"2019-02-15T09:45:00.000+11:00","end":"2019-02-15T10:00:00.000+11:00"},
 {"start":"2019-02-15T10:00:00.000+11:00","end":"2019-02-15T10:15:00.000+11:00"},
 {"start":"2019-02-15T10:15:00.000+11:00","end":"2019-02-15T10:30:00.000+11:00"},
 {"start":"2019-02-15T10:30:00.000+11:00","end":"2019-02-15T10:45:00.000+11:00"},
 {"start":"2019-02-15T11:30:00.000+11:00","end":"2019-02-15T11:45:00.000+11:00"},
 {"start":"2019-02-15T11:45:00.000+11:00","end":"2019-02-15T12:00:00.000+11:00"},
 {"start":"2019-02-15T12:00:00.000+11:00","end":"2019-02-15T12:15:00.000+11:00"},
 {"start":"2019-02-15T12:15:00.000+11:00","end":"2019-02-15T12:30:00.000+11:00"},
 {"start":"2019-02-15T12:30:00.000+11:00","end":"2019-02-15T12:45:00.000+11:00"},
 {"start":"2019-02-15T12:45:00.000+11:00","end":"2019-02-15T13:00:00.000+11:00"},
 {"start":"2019-02-15T13:00:00.000+11:00","end":"2019-02-15T13:15:00.000+11:00"},
 {"start":"2019-02-15T13:15:00.000+11:00","end":"2019-02-15T13:30:00.000+11:00"},
 {"start":"2019-02-15T13:30:00.000+11:00","end":"2019-02-15T13:45:00.000+11:00"},
 {"start":"2019-02-15T13:45:00.000+11:00","end":"2019-02-15T14:00:00.000+11:00"},
 {"start":"2019-02-15T14:00:00.000+11:00","end":"2019-02-15T14:15:00.000+11:00"},
 {"start":"2019-02-15T14:15:00.000+11:00","end":"2019-02-15T14:30:00.000+11:00"},
 {"start":"2019-02-15T14:30:00.000+11:00","end":"2019-02-15T14:45:00.000+11:00"},
 {"start":"2019-02-15T14:45:00.000+11:00","end":"2019-02-15T15:00:00.000+11:00"},
 {"start":"2019-02-15T15:00:00.000+11:00","end":"2019-02-15T15:15:00.000+11:00"},
 {"start":"2019-02-15T15:15:00.000+11:00","end":"2019-02-15T15:30:00.000+11:00"},
 {"start":"2019-02-15T15:30:00.000+11:00","end":"2019-02-15T15:45:00.000+11:00"},{"start":"2019-02-15T15:45:00.000+11:00","end":"2019-02-15T16:00:00.000+11:00"},{"start":"2019-02-15T16:00:00.000+11:00","end":"2019-02-15T16:15:00.000+11:00"},{"start":"2019-02-15T16:15:00.000+11:00","end":"2019-02-15T16:30:00.000+11:00"},{"start":"2019-02-15T16:30:00.000+11:00","end":"2019-02-15T16:45:00.000+11:00"},{"start":"2019-02-15T16:45:00.000+11:00","end":"2019-02-15T17:00:00.000+11:00"},{"start":"2019-02-15T17:00:00.000+11:00","end":"2019-02-15T17:15:00.000+11:00"},{"start":"2019-02-15T17:15:00.000+11:00","end":"2019-02-15T17:30:00.000+11:00"}]

Users

Clinician users can be be scheduled for appointments, subject to their availability at a Practice Location.

Notes:

For a user to be returned, their Online Booking flag must be ticked.

Users at a Practice Location

To determine the users available at a practice location:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/locations/98/users
[{"id":1158,"name":"Andrew Turner"},
 {"id":1159,"name":"Chris Barton"}]

User Locations

To determine which locations a user may be available at:

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/users/1158/locations
[{"id":106,"name":"Branch Clinic","timeZone":"Australia/Sydney"},
 {"id":98,"name":"Main Clinic","timeZone":"Australia/Sydney"}]

User Availability at a Location

To determine user availability at a Practice Location, and which schedules they may be assigned appointments to:

> curl -u sample:changeit 'http://localhost:8080/openvpms/ws/booking/v2/users/1158/locations/98/free?from=2019-02-15T00:00:00%2B11:00&to=2019-02-16T00:00:00%2B11:00'
[{"start":"2019-02-15T11:00:00.000+11:00","end":"2019-02-15T17:00:00.000+11:00","schedule":136},
 {"start":"2019-02-15T09:00:00.000+11:00","end":"2019-02-15T17:00:00.000+11:00","schedule":211}

Notes:

The user must be rostered on to a Roster Area with Schedules attached
The returned times are per schedule, indicating the times that the user is free/busy for that schedule only.
It does not take into account other appointments on the schedule, or other appointments the user has on a different schedule.
To determine the times a user is available, the union of busy times needs to be removed from each schedule.

Submitting Bookings

> curl -u sample:changeit -H "Content-Type: application/json" --data @booking.json http://localhost:8080/openvpms/ws/booking/v2/bookings

Where booking.json is a file containing:

{
  "location": 98,
  "schedule": 136,
  "appointmentType": 66,
  "start": "2019-02-15T12:30:00.000+11:00",
  "end": "2019-02-15T12:45:00.000+11:00",
  "title": "Ms",
  "firstName": "Judith",
  "lastName": "Bourke",
  "mobile": "0418976543",
  "patientName": "Muffett"
  "user": 1158
}

Notes:

the email and phone attributes can be specified as well.
a booking customer is considered a match if its firstName and lastName are equal to an OpenVPMS customer, ignoring case, and at least one of the 3 contacts are present.
the reference returned is a concatenation of the appointment identifier, customer identifier and UUID. This is to:
- make it harder to retrieve/cancel bookings not made through the API
- prevent retrieval of appointments subsequently assigned to another customer
the user is optional

Retrieving Bookings

> curl -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/bookings/603:3:be08f3c6-1afb-11e6-be41-3dbaef689d97

Notes:

the mobile, phone and email submitted with the request are not stored; the values returned are those associated with the existing customer
the notes aren't returned as these may have been updated since the booking was made and contain information that shouldn't be disclosed

Cancelling Bookings

> curl -X DELETE -u sample:changeit http://localhost:8080/openvpms/ws/booking/v2/bookings/391:a98f02c9-1a4b-...

Notes:

bookings can only be cancelled while their corresponding appointment is pending
once cancelled, bookings cannot be retrieved

Security

There are a number of security considerations to be aware of:

an OpenVPMS user account is required to make online bookings. This should be a restricted account that only has the authorities required to make online bookings.
This can be done by creating a user that only has the Online Booking role assigned.
the OpenVPMS web application should not be exposed to the wider internet to allow external providers to connect. Restricted access can be provided through a VPN, IP filtering, and/or URL filtering. For the purposes of online booking, only the:
/openvpms/ws/booking
URL should be exposed.