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.

Appointments can either be made using the POST /appointment/hold endpoint, which will hold the appointment in an Initial (IN) status, 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).

Alternatively, Appointments can be made using the POST /appointment endpoint in which you must pass the customer information on the POST request. This means that the appointment will be immediately created in Booked (BK) status.

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:

• startDate
  The startDate is now formatted in a date time string (e.g. 2025-05-01T00:00:00Z)
• endDate
  The endDate is now formatted in a date time string (e.g. 2025-05-01T00:00:00Z)
• LocationId
  The ID of a Location will define which Location the appointment is booked with.
• ServiceId
  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.
• ResourceIds
  The Resource IDs 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.
• roundRobin
  Round Robin randomly selects between any one of the Resources passed in the ResourceIds parameter. The value of roundRobin is an ENUM, one of the following values must be used:
  • NONE
  • RANDOM
  • BALANCED
• syncExternal
  This new property allows you to specify whether or not you wish to include external calendar events when calculating availability on each call. For example if a Resource has a connected Google Calendar, and you wish to find availability that includes the Google events in its calculation, then you will set syncExternal to true. Setting syncExternal to false will shave off a few milliseconds of time that will come in handy if none of your Resources are connected to a Google or Outlook calendar.

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.

{
  "success": true,
  "data": {
    "ServiceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "availableDays": {
      "2024-12-18": [
        {
          "start_time": "2024-12-18T22:22:45.993Z",
          "end_time": "2024-12-18T22:22:45.993Z"
        }
      ],
      "2024-12-19": [
        {
          "start_time": "2024-12-19T22:22:45.993Z",
          "end_time": "2024-12-19T22:22:45.993Z"
        }
      ]
    },
    "availableTimes": [
      {
        "start_time": "2024-12-18T22:22:45.993Z",
        "end_time": "2024-12-18T22:22:45.993Z",
        "ResourceIds": [
          "e462cc7d-e8ce-4d4e-b2f5-0c98ec7a3172"
        ],
        "LocationId": "e462cc7d-e8ce-4d4e-b2f5-0c98ec7a3172"
      },
      {
        "start_time": "2024-12-19T22:22:45.993Z",
        "end_time": "2024-12-19T22:22:45.993Z",
        "ResourceIds": [
          "e462cc7d-e8ce-4d4e-b2f5-0c98ec7a3172"
        ],
        "LocationId": "e462cc7d-e8ce-4d4e-b2f5-0c98ec7a3172"
      }
    ]
  }
}

🤷‍♂️

Find by ID

In the following example the Customer object includes a firstName and lastName in order to find or create the customer. Instead of firstName and lastName you may instead pass id if the Customer already exists and you have the id stored.

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

• LocationId
  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.
• ServiceId
  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.
• ResourceIds
  Include the response for either resourceId or resourceIds (plural), whichever was expected from the Availability response.
• Customer:
  • firstName
  • lastName

❗️

Optional for /appointment/hold

The Customer object is only required when making a POST request without /hold in the request URL. If using /hold then the customer information may be included on the proceeding PUT request to book the appointment.

• Unavailability:
  • startTime
    Include the startTime in the format of a date time string (e.g. 2025-05-01T00:00:00Z) to the POST /appointment request nested within an object labelled Unavailability.
  • endTime
    Include the endTime in the format of a date time string (e.g. 2025-05-01T00:00:00Z) to the POST /appointment request nested within an object labelled Unavailability.

👍

Use a time from availability

Using the values from a selected time object within the availableTimes array will ensure that the Appointment may be created for that time with no validation errors.

In addition to the required fields above, the following properties may be included in the request body for both POST /appointment and POST appointment/hold

Updating an Appointment to Booked(BK) status

🤷‍♂️

Only required when using /appointment/hold

When an Appointment is created from a POST /appointment/hold 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 Expiration Delay has elapsed. To change your Expiration Delay setting update the expirationDelay (in seconds) property on the Location.

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 /appointment request. A Customer object can be provided to the POST /appointment request with the following data:

• id
  ID of the Customer if already created and stored
• firstName, lastName, email, phone
  We will find the customer by email if they already exist, otherwise a new customer object will be created in the Location.