Skip to main content

Appointment Scheduling AJAX Endpoints

Several AJAX (Asynchronous Javascript and XML) endpoints are available for use with the Appointment Scheduling feature to retrieve reading room and appointment information in various contexts and to handle creating and rescheduling appointments. Each endpoint will return a JSON response as detailed below.

JSON Object Returned | AJAX Endpoints

JSON Object Returned​

Successful calls to one of these endpoints will return a JSON object with a status property that has the value "success" and a data property that contains the data returned from the operation.

{ "status": "success", "data": { .... }}

Unsuccessful calls to one of these endpoints will return a JSON object with a status property that indicates whether the request failed because insufficient information was submitted (status = 'fail') or because there was an unrelated server error (status = 'error'), along with a message property to explain the error.

{ "status": "fail", "message": "AppointmentID is a required field."}
{ "status": "error", "message": "Unable to retrieve appointment details."}

AJAX Endpoints​

GetAppointments | GetReadingRooms | GetAppointmentAvailability | GetAppointmentAvailabilities | CreateAppointment | RescheduleAppointment

GetAppointments​

Returns a list of available appointments for a user or their researcher that are still pending (i.e. their StopTime is still in the future). If the reading room does not require appointments, an empty result will also be included in the result set to allow for submitting a request without an appointment.

Parameters​

NameRequired/OptionalDescription
ReadingRoomIDRequiredThe ID of the reading room to which the appointments must belong.
ResearcherUsernameOptionalIf ResearcherUsername is provided, the AJAX method will return only appointments for that researcher that are available to proxies and only if the current user is a proxy for the said researcher. Otherwise, it will return only appointments for the current user. This information is determined from the user's active web session.
TransactionNumberOptionalIf TransactionNumber is provided and the transaction has a linked appointment, that appointment will be included in the results even if it doesn't meet the other criteria or has already passed its expiration date.

Data Returned​

A JSON object representing the list of appointments.

GetReadingRooms​

Returns a list of reading rooms, restricting the list to those associated with a specific site if this parameter is provided. This AJAX method is available anonymously, i.e. it does not require an active web session.

Parameters​

NameRequired/OptionalDescription
SiteOptionalWhen provided, the list of returned reading rooms will be limited to those associated with the given site as determined through the ReadingRoomsForSites database table.

Data Returned​

A JSON object representing the list of reading rooms.

GetAppointmentAvailability​

Returns a list of available appointment slots for the given reading room and date.

Parameters​

NameRequired/OptionalDescription
ReadingRoomIDRequiredThe ID of the reading room.
AppointmentDateRequiredThe date of the appointment.

Data Returned​

A JSON object containing the standard AppointmentAvailability fields (UTCStartTime, StartTime, SeatsAvailable, and MaximumAppointmentLength) as well as an additional field named StartTime-ISO8601. This field will contain the StartTime data formatted in the ISO 8601 standard for convenience of use, while the UTCStartTime and StartTime fields will be formatted using the system standard (e.g., month/day/year for US servers).

GetAppointmentAvailabilities​

This endpoint is only available in Aeon 5.2 or later.

Returns a list of available appointment slots for the given reading room across the specified date range.

Parameters​

NameRequired/OptionalDescription
ReadingRoomIDRequiredThe ID of the reading room.
AppointmentStartDateRequiredThe start of the date range for which to retrieve appointment availability information.
AppointmentEndDateRequiredThe end of the date range for which to retrieve appointment availability information.

Note: AppointmentStateDate and AppointmentEndDate must be entered in ISO-8601 format (yyyy-mm-dd). For example, "2022-11-01" should be entered for the date November 1st, 2022.

Data Returned​

A JSON object containing an array for each available appointment slot in the specified date range. Appointment slot arrays will contain the fields detailed in the GetAppointmentAvailability endpoint documentation above and will be grouped by date key for each date in the range. Any date for which no appointment slots are available will return an empty JSON array under that date key.

Click for an example response

The following is an example of data returned for a specified start date of November 1st, 2022, and an end date of November 3rd, 2022. Note that an empty JSON array is returned for November 2nd, 2022, meaning that no appointments are available for the reading room on that date:

{
    "status": "success",
    "data": {
        "2022-11-01": [
            {
                "UTCStartTime": "2022-11-01T13:00:00.000",
                "StartTime": "11/1/2022 9:00:00 AM",
                "StartTime-ISO8601": "2022-11-01T09:00:00.000",
                "SeatsAvailable": "1",
                "MaximumAppointmentLength": "120"
            },
            {
                "UTCStartTime": "2022-11-01T13:15:00.000",
                "StartTime": "11/1/2022 9:15:00 AM",
                "StartTime-ISO8601": "2022-11-01T09:15:00.000",
                "SeatsAvailable": "1",
                "MaximumAppointmentLength": "120"
            },
            {
                "UTCStartTime": "2022-11-01T13:30:00.000",
                "StartTime": "11/1/2022 9:30:00 AM",
                "StartTime-ISO8601": "2022-11-01T09:30:00.000",
                "SeatsAvailable": "1",
                "MaximumAppointmentLength": "120"
            }
        ],
        "2022-11-02": [],
        "2022-11-03": [
            {
                "UTCStartTime": "2022-11-03T13:00:00.000",
                "StartTime": "11/3/2022 9:00:00 AM",
                "StartTime-ISO8601": "2022-11-03T09:00:00.000",
                "SeatsAvailable": "1",
                "MaximumAppointmentLength": "120"
            }
        ]
   }
}

CreateAppointment​

Creates an appointment for a given user, reading room, and time slot.

Parameters​

NameRequired/OptionalDescription
ReadingRoomIDRequiredThe ID of the reading room in which to schedule the appointment.
StartTimeRequiredThe start time of the appointment in the time zone of the reading room.
StopTimeRequiredThe end time of the appointment in the time zone of the reading room.
NameOptionalThe name for the appointment.
ResearcherUsernameOptionalIf specified, the appointment will be created for the researcher instead of the current user.
AvailableToProxiesOptionalSpecifies whether the appointment will be available to proxy users. If ResearcherUsername is provided, this value will default to true.

Data Returned​

A JSON object representing the created appointment.

RescheduleAppointment​

Reschedules an existing appointment.

Parameters​

NameRequired/OptionalDescription
AppointmentIDRequiredThe ID of the appointment being rescheduled.
StartTimeRequiredThe start time of the new appointment time slot.
StopTimeRequiredThe end time of the new appointment time slot
NameOptionalSpecifies a new name for the appointment.

Data Returned​

A JSON object representing the rescheduled appointment.