OnSched Consumer API

Delete Appointment Use this endpoint to permanently Delete an appointment. Only appointments with a of "IN" status, initial, can be deleted. Past dated appointments cannot be deleted. A valid appointment id is required. Use the appointment id returned from the initial POST /consumer/v1/appointments endpoint. For more information: Appointment Overview

Delete Customer Use this endpoint to permanently Delete a Customer object. A valid customer id is required.

Get Appointments Use this endpoint to return a List of Appointments. Use the offset and limit parameters to control the page start and number of results. Default offset is 0, limit is 20, max is 100. Use the query parameters to filter the results further. For more information: Appointments Overview

Get Custom Fields Labels Use this endpoint to return a locations Appointment Booking Fields. Appointment booking fields are stored with each Appointment record. They are used when you need additional information collected during your booking process. It is tied to an appointment/visit and will be stored in the appointment record. Use the field name, type, and length to determine how to update these field values when posting an appointment.

Get Custom Fields List Use this endpoint to return a locations Appointment Custom Field definitions. Appointment custom fields are stored with each appointment. They are used when the information collected during the booking is specific to a particular appointment/visit. The response will list the custom fields used (customField1 - 10), the field type (string, number, date, boolean) and the length of each one.

Get Appointment Use this endpoint to return an Appointment object. A valid appointment id is required. For more information: Appointments Overview

Get Available Times Choose your search criteria carefully. Availability is an expensive call. If you search availability for all resources, you should only do so for a single date. If you search availability for multiple dates, you should only do so for a specific resource by specifying the optional resourceId parameter. A serviceId is required. The startDate and endDate are required and are formatted as: YYYY-MM-DD A resourceId is optional, it is recommended if known at the time of availability call. timezoneName is optional, it allows you to specify the IANA formatted name for the end user's timezone to view availability. e.g., America/New_York. NOTE: This is the recommended approach for your implementation. The "tzOffset" parameter remains for backward compatibility. For JavaScript, use moment.js in your client for ease of timezone detection and selection. For iOS, use the name property of the NSTimeZone returned from the localTimeZone method. For .NET, consider NodaTime or TimeZoneConverter via NuGet. duration should only be populated if you allow the end user to select a duration, otherwise the service's duration will be used. startTime and endTime are optional and are specified in military time e.g., 800 = 8:00am, 2230 = 10:30pm. Note: You will only see availability within the boundary of your business location start and end times. dayAvailability will return day level availability for the number of days requested from the start date. See GET /consumer/v1/availability/{serviceId}/{startDate}/{endDate}/days for details. firstDayAvailable only works with day availability. If set to true it will look for the first day available within the range specified by the dayAvailability parameter. The two parameters together can be a clever way to display availability for a week or month. Tip - pass in the beginning of the week or month, and available times are displayed for the first available date if exists. tzOffset allows you to pass in the timezone offset for the end user's timezone of choice, e.g., (-240) for EST. If you use this option, your application should be timezone aware. The requested timezone is specified as an offset (plus or minus) from GMT time. Availability can be complex. For further troubleshooting refer to the: GET /consumer/v1/availability/{serviceId}/{startDate}/{endDate}/unavailable endpoint. This endpoint will show you all unavailable times for a given date range. Available times are created from any unblocked time periods. For more information: Availability Overview

Get Available Days This endpoint will return Day Level Availability for the range of dates requested. For example, if the business is closed, or there is a public holiday this endpoint will return that the "Day is unavailable". Day Availability is a high-level check for Holidays and Open/Available hours of a location, service and/or resource and should be used to restrict your choices of days available in your application to improve usability and performance. A serviceId is required. The startDate and endDate are required and are formatted as: YYYY-MM-DD The locationId is optional, however if not supplied it defaults to the Primary Business Location for open/closed hours information. It is recommended you always provide the locationId. A resourceId is optional. If used the available days will be return day availability for the resource specified. The tzOffset parameter should be used if the appointment requester, the end user, is in a different timezone than the location or resource.

Get Unavailable Times This endpoint is used to show Unavailable times and provides valuable information as to why a time slot is unavailable. If you question your availability results, populate the same parameters to this endpoint to find out why. A serviceId is required. The startDate and endDate are required and are formatted as: YYYY-MM-DD Location hours, holidays, services, resources, blocks, allocations, and appointments are just some of variables that may cause time slots to become unavailable. Use this endpoint to understand why you don't see availability.

List Customers Use this endpoint to return a List of Customers. The results are returned in pages. Use the offset and limit parameters to control the page start and number of results. Default offset is 0, limit is 20, max is 100. Use the query parameters to filter the results further. When providing a first name, last name is required.

Get Customer Booking Fields Use this endpoint to return Customer Booking Fields. Customer booking fields are stored with each customer object. They are used when the information collected during the booking is for a particular customer. Customer Booking Fields include any custom customer fields you define and want to capture with the Booking.

List Country Codes Use this endpoint to return a List of Countries with their associated Country Code. Country codes are based on the 2-character ANSI standard. If your countries of operation are not currently listed, contact us at [email protected].

Get Customer Custom Fields Use this endpoint to return Customer Custom Fields. Customer custom fields are stored with the customer object. They are used when the information collected during the booking is specific to a particular customer.

Get Customer Use this endpoint to return a Customer object. A valid customer id is required. Find customer id's by using the GET /consumer/v1/customers endpoint.

List Country States Use this endpoint to return a List of Countries with their associated State Codes. Supply a country code to filter results further. If states for your countries of operation are not currently listed, contact us at [email protected].

List Locations Use this endpoint to return a List of Business Locations. The results are returned in pages. Use the offset and limit parameters to control the page start and size. Default offset is 0, and limit is 20 and maximum is 100. Use the other query parameters to filter the results further. IMPORTANT DEPRECATION NOTICE: The following online settings parameters were intended for internal use in our Portal application only. They will be deprecated on OCTOBER 15, 2022. These fields are currently part of the SETTINGS object in all location endpoints: businessId, enabled, familyMembersEnabled, serviceLabel, resourceLabel, resourceAnyLabel, resourceSelection, liveMode, formFlow, availabilityForm, showServiceGroups, showOnSchedLogo, showBusinessLogo, disableAuthorization, hideNavBar, hideLocationNav, hideServiceGroupsNav, hideServicesNav, hideContinueBooking, returnToService, returnToAvailability, hideBreadCrumbNav. If you are using these fields, please adjust your code to handle the deprecation or let us know by submitting a ticket to: [email protected] as we do not want to interrupt your existing workflows.

Get Location Use this endpoint to return a Location object. A valid business location id is required. Find all location id's by using the GET /consumer/v1/locations endpoint. IMPORTANT DEPRECATION NOTICE: The following online settings parameters were intended for internal use in our Portal application only. They will be deprecated on OCTOBER 15, 2022. These fields are currently part of the SETTINGS object in all location endpoints: businessId, enabled, familyMembersEnabled, serviceLabel, resourceLabel, resourceAnyLabel, resourceSelection, liveMode, formFlow, availabilityForm, showServiceGroups, showOnSchedLogo, showBusinessLogo, disableAuthorization, hideNavBar, hideLocationNav, hideServiceGroupsNav, hideServicesNav, hideContinueBooking, returnToService, returnToAvailability, hideBreadCrumbNav. If you are using these fields, please adjust your code to handle the deprecation or let us know by submitting a ticket to: [email protected] as we do not want to interrupt your existing workflows.

List Resource Groups Use this endpoint to return a list of Resource Groups for the requested location. If not specified, the business location defaults to the primary business location.

Get Resource Group Use this endpoint to return a Resource Group object. A valid resourceGroup id is required. Find resourceGroup id's by using the GET /consumer/v1/resourceGroups endpoint.

List Resources Use this endpoint to return a List of Resources associated with a business location. If not specified, the business location defaults to the primary business location. The results are returned in pages. Use the offset and limit parameters to control the page start and number of results. Default offset is 0, limit is 20, max is 100. Use the query parameters to filter the results further.

Get Resource Use this endpoint to return a Resource object. A valid resource id is required. Find resource id's by using the GET consumer/v1/resources endpoint.

Get Resource Linked Services Use this endpoint to get a List of Linked Services associated with the resource requested. The results are returned in pages. Use the offset and limit parameters to control the page start and size. Default offset is 0, limit is 20, the maximum limit is 100. Use the other query parameters to filter the results further. Resource linked services are used to explicitly define the services that can be booked for a specified resource. By default, all services are bookable for any resource. For more information: Linked Services Overview

List Service Groups Use this endpoint to return a list of Service Groups for the requested location. If not specified, the business location defaults to the primary business location. Use the offset and limit parameters to control the page start and size. Default offset is 0, limit is 20, maximum is 100. Use the other query parameters to filter the results further.

Get Service Group Use this endpoint to return a Service Group object. A valid serviceGroup id is required. Find serviceGroup id's by using the GET /consumer/v1/serviceGroups endpoint.

List Services Use this endpoint to List Services available at your business location and/or company. If not specified, the business location defaults to the primary business location. Use the offset and limit parameters to control the page start and number of results. Default offset is 0, limit is 20, max is 100. Use the query parameters to filter the results further.

Get Service Allocation Use this endpoint to return a Service Allocation object. A valid serviceAllocation id is required. Find service allocation id's by using the GET/consumer​/v1​/services​/{id}​/allocations endpoint.

Get Service Use this endpoint to return a Service object. A valid service id is required. Find service id's by using the GET /consumer/v1/services endpoint.

List Service Allocations Use this endpoint to return a List of Service Allocations associated with the requested service. A valid service id is required. Allocations are used for Event type services/bookings. Retrieve all allocations for a location by passing in zero as the service id. Otherwise, to get allocations for a specific service supply the service id. Use the offset and limit parameters to control the page start and number of results. Default offset is 0, limit is 20, max is 100. Use the query parameters to filter the results further. For more information: Create Service Allocations

List Resources for Service Use this endpoint to return a list of Resources that provide the Service requested. A valid service id is required. The results are returned in pages. Use the offset and limit parameters to control the page start and number of results. Default offset is 0, limit is 20, max is 100. Use the query parameters to filter the results further.

Create Appointment Use this endpoint to Create a new appointment. The appointment will be created with an "IN", Initial status. Posting an appointment with "IN" status requires minimal information and requires a "PUT book" call to complete the booking transaction, PUT ​/consumer​/v1​/appointments​/{id}​/book. Alternatively, you can post an appointment using the completeBooking option which completes the booking in one transaction, but it will require more data. The method you choose depends on your solutions workflow. StartDateTime and EndDateTime are required. Use the ISO 8601 format for DateTime Timezone, e.g., 2016-10-30T09:00:00-5:00 A valid serviceId is required. The serviceId provided must be valid for the location being booked. A valid serviceId is one that is scoped to a Primary Company Location or is associated with a Business Location OPTIONAL FIELDS INCLUDE: locationId - if not supplied, the appointment will be posted to the primary business location. If you support multiple location, we recommend always supplying the locationId. resourceId - not required when posting with an "IN" status but is required when the appointment is booked. Use GET /consumer/v1/resources for a list of resources. customerId - if supplied the name and email will be retrieved from the customer record. BookedBy - if not supplied the email address of the booked appointment is used or the ip address if no email address is provided. BookedBy is used in the Appointment Audit trail which can be viewed in the appointment object. Location - is a string value representing the location of the appointment. It provides no added functionality in OnSched and should not be confused with locationId. TimezoneName - if used timezoneName must be in IANA format, America/New_York. This is the timezone the appointment was booked in. Populating this information can help later in situations where appointments are booked before a Daylight Savings change. If no timezoneName is supplied, the Business Locations timezone will be used. COMPLETE BOOKING: This parameter provides a mechanism for immediate booking with the POST appointment endpoint. To complete the booking in one transaction, populate the completeBooking parameter with a "BK", booked or an "RS", reserved status and provide an (email and name) or a customerId in the post body. Doing so will book the appointment and send notifications all in one transaction. Note: "IN" can also be used as a completeBooking option to support payment flows. With the "IN" option, notifications are NOT sent. For more information: Appointments Overview

Create Customer Use this endpoint to Create a new Customer. A customer object is automatically created with the first appointment booking if it doesn't already exist. If not specified, the business location id defaults to the primary business location. Required Fields: Email and Name or First and Lastname depending on customer type. Type 0 = Person, Type 1 = Business. For type 0, the firstname and lastname fields are used. For type 1, the Name field is used, and the name field is also used to populate the lastname.

Book Appointment Use this endpoint to Book an appointment. Only appointments with an "IN" status, Initial, can be booked. A valid appointment id is required. Use the appointment id returned from the initial POST /consumer/v1/appointments endpoint. Other pertinent fields can also be updated at the time of booking by including them in the post body. Note: If no name or email address was provided in the initial Post Appointment, it will be required in the post body. For more information: Appointments Overview

Cancel Appointment Use this endpoint to Cancel an appointment booking or reservation. Only appointments with a "BK", booked or "RS", reserved status can be cancelled. Past dated appointments cannot be cancelled. A valid appointment id is required. For more information: Appointment Overview

Confirm Appointment Use this endpoint to Confirm an appointment. This updates the boolean confirmed field to TRUE. NOTE: If the appointment status is set to "RS", Reserved, it also updates the status of the appointment to "BK", Booked. For more information: Appointment Overview

Set NoShow Status Use this endpoint to change the status of an appointment from "BK", Booked to "NS", NoShow. This gives API consumers a way to internally track No Show appointments. It provides no added functionality in OnSched. For more information: Appointment Overview

Reschedule Appointment Use this endpoint to Reschedule an appointment booking. Only appointments in "BK", booked status, can be Rescheduled. Past dated appointments cannot be rescheduled. A valid appointment id is required. The StartDateTime and EndDateTime are required. Use the ISO 8601 format for DateTime Timezone, e.g., 2016-10-30T09:00:00-5:00. The serviceId is optional. If changing the serviceId, the new service id's duration must match the original service's duration. The resourceId is optional. If changing the resourceId, verify the availability of the new resource prior to rescheduling. IMPORTANT: Always run availability before rescheduling an appointment to verify the timeslot is open and available for the new time, service and/or resource requested. This is the only way to assure the slot is available. You cannot reschedule an appointment to a different location. If necessary, you should cancel and then book an appointment in the other location. For more information: Appointment Overview

Reserve Appointment Use this endpoint to Reserve an appointment. Only appointments with an "IN" status, Initial, can be reserved. A valid appointment id is required. Use the appointment id returned from the initial POST /consumer/v1/appointments endpoint. NOTE: Reservations are different from Bookings as reservations are a two-step booking process that must be managed by the API consumer. An appointment that is reserved is not completely booked until other business conditions have been met. For example, an appointment may be reserved if it is not yet assigned to a resource or until the customer or resource explicitly confirms it. With reservations you have the ability to notify the customer of a reservation prior to officially booking and the workflow can be designed to indicate what conditions will need to be met in order to convert the reservation to a complete booking. A reservation converts to a complete booking when it is either Confirmed or Booked. IMPORTANT: A reserved appointment time will not be released, i.e., become available to others, until it is Cancelled. The booking timer is not used with reserved appointments. For more information: Appointments Overview

Update Customer Use this endpoint to Update a Customer object. A valid customer id is required. Note: Blank fields are not changed.