Appointment Booking

In order to book an Appointment through the API you must first find Availability for the date/time you wish to create an Appointment.

Once an available time is chosen, you may use the data from an available time object in the Availability response to create an Appointment.

By default an Appointment is created with a status of Initial (IN), the Initial Status will lock the time slot while you are gathering customer information, collecting payment, generating meeting links, etc. After all relevant information is collected the Appointment Status must be updated to Booked (BK).

Requesting Availability for an Appointment

Beginning with Availability will ensure that there are no error validations returned from the POST or PUT /appointments request. During the request for Availability the following configurations for the Appointment will be made:

• Timezone
  If a tzOffset parameter is provided when requesting availability, the Available Times array will be returned with ISO startDateTime and endDateTime properties which include the requested timezone. If no tzOffset is provided, the timezone will be determined by the Location settings.
• Duration
  The duration will be defined by the Availability request, resulting in the endDateTime property which is required in the POST /appointments model. The duration must follow the rules you have set on the Service object, to set rules that allow the duration to vary visit Variable Duration Settings.
• Service ID
  The ID of a Service must be present to find Availability. The Service must either be a Company Scope Service that is created at the Primary Location and accessible by all Secondary Locations, or it must belong to the Secondary Location for which the Availability is being requested.
• Resource ID
  The Resource ID(s) may be specified when requesting Availability, if not specified then the defined Round Robin settings will be used. The Availability response will include the Resource ID found by OnSched or provided in the request.

Create an Appointment

Now that all configurations for the Appointment above have been determined, the response from Availability may be used to create an Appointment.

The following is an example response from a request for Availability. Below you will find instructions on how to use this response to craft the POST /appointment request.

{
  "locationId": "string",
  "serviceId": "string",
  "startDate": "string",
  "endDate": "string",
  "resourceId": "string",
  "resourceIds": "string",
  "tzRequested": 0,
  "availableTimes": [
    {
      "startDateTime": "string",
      "endDateTime": "string",
      "date": "string",
      "time": 0,
      "displayTime": "string",
      "duration": 0,
      "resourceId": "string",
      "resourceIds": "string",
    }
  ]
}

Above is an example of the Availability response, the following properties from the Availability response must be used to make the POST /appointments request:

• Location ID
  If a Location ID was provided to Availability, it must be included in the POST /appointments request. If no Location ID is provided to Availability it may be excluded, in which case the appointment will POST to the Primary Location.
• Service ID
  Include the Service ID from the top layer of the Availability response object in the Appointment post.
• Resource ID(s)
  Include the response for either resourceId or resourceIds (plural), whichever was expected from the Availability response.
• Start/End Date Time
  Include the startDateTime and endDateTime strings to the POST /appointment request. Using the values from a selected availableTimes object will ensure that the Appointment may be created for that time with no validation errors.

Updating an Appointment to Booked(BK) status

When an Appointment is created from a POST /appointment request, it will be returned with a status of Initial (IN). The Appointment will be held in Initial (IN) status until it is updated to Booked (BK) status. The Initial (IN) status Appointment will hold the time slot selected from being available for any other Availability requests until the Booking Timer Minutes has elapsed. To change your Booking Timer Minutes setting, please see the Location Settings in your Dashboard.

While the Appointment is being held in Initial status you may use this time to...

• Collect additional information about the Customer (I.e. Name, Email, Phone, etc.)
• Collecting payment using an external payment provider (I.e. Stripe, Square, Paypal, etc.)
• Generating a meeting link from Zoom, GoogleMeet, or other conference platforms
• Or any other steps required in your booking flow that must be completed before the Appointment is confirmed as Booked (BK)

Bypass the Initial (IN) status

The Initial (IN) Appointment status can be bypassed if a Customer is provided to the POST /appointments request. A Customer can be provided to the POST /appointment request with either of the following data:

• Customer ID
• Customer Name/Email

If enough Customer information is provided to the POST /appointment request and no other external actions need to be taken during the Initial (IN) status, then the Appointment can be set to Booked (BK) on the POST /appointment request by providing a value of BK to the query parameter completeBooking.