Appointment

This Appointment API is used to create new appointments on the business’ account based on the provided details. This API is limited in scope and does not allow the majority of overridable data, settings, etc. For a administrative workflow utilize this documentation instead: Appointments .


These are the endpoints that are available under the /scheduling/appointments path.

Endpoint

Description

Endpoint

Description

POST /scheduling/appointments

Creates a new appointment object on an account.

Request body/payload: Must pass an appointment object.

For these calls, you need to pass an appointments object with all required fields and any fields you want to set filled in the body of the payload. We have an example of an appointments object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

The objects below represent the minimum viable objects to pass that are needed to create or update an appointment object. Check whether or not a property can be written to by looking at the Object Values table below to see if the property is writable.

{ "status": "OPEN", "subStatus": "OPEN", "fields": [ { "schedulerPreferenceFieldDefnId": 29268, "businessId": 20344, "code": "UDF", "dataType": "AREA", "mode": "APPT", "label": "Comments", "hint": null, "fieldValues": null, "sortOrder": 24, "required": false, "visible": true, "userDefinedField": false, "visibleOnScheduler": true, "filterByService": false, "serviceIds": null, "active": true, "tagName": null, "oldFieldIds": null, "validationRegex": null, "validationError": null, "mask": null, "createdUser": "Mo122", "createdDate": 1659375013000, "modifiedUser": "Mo122", "modifiedDate": 1659375013000, "defaultValue": null, "defaultNullValue": null, "internalLabel": null, "depFieldDefnId": null, "depType": null, "depValue": null, "depCondition": null, "depAction": null, "depSetValue": null, "depError": null, "allowClientEdit": true, "requiredJSON": null, "styleJSON": null, "value": null, "extendedValue": null, "valueMap": null, "valueList": null, "errorMessage": null, "internalDisplayName": "Comments", "valueTag": "%CUSTOM_FIELD_29268%", "labelTag": "%CUSTOM_FIELD_29268_LABEL%", "basicTagName": null, "showOnScheduler": true, "enable": true, "depFieldDefnIdObjs": [], "depFieldDefnIds": [] }, { "schedulerPreferenceFieldDefnId": 35000, "businessId": 20344, "code": "UDF", "dataType": "DATE", "mode": "APPT", "label": "Date of incident", "hint": null, "fieldValues": null, "sortOrder": 26, "required": false, "visible": true, "userDefinedField": true, "visibleOnScheduler": true, "filterByService": false, "serviceIds": null, "active": true, "tagName": null, "oldFieldIds": null, "validationRegex": null, "validationError": null, "mask": null, "createdUser": "MO122", "createdDate": 1706817071000, "modifiedUser": "MO122", "modifiedDate": 1706817071000, "defaultValue": null, "defaultNullValue": null, "internalLabel": null, "depFieldDefnId": null, "depType": null, "depValue": null, "depCondition": null, "depAction": null, "depSetValue": null, "depError": null, "allowClientEdit": true, "requiredJSON": null, "styleJSON": null, "value": null, "extendedValue": null, "valueMap": null, "valueList": null, "errorMessage": null, "internalDisplayName": "Date of incident", "valueTag": "%CUSTOM_FIELD_35000%", "labelTag": "%CUSTOM_FIELD_35000_LABEL%", "basicTagName": null, "showOnScheduler": true, "enable": true, "depFieldDefnIdObjs": [], "depFieldDefnIds": [] }, { "schedulerPreferenceFieldDefnId": 35001, "businessId": 20344, "code": "UDF", "dataType": "LIST", "mode": "APPT", "label": "Within Number of days", "hint": null, "fieldValues": "Yes\nNo", "sortOrder": 27, "required": false, "visible": true, "userDefinedField": true, "visibleOnScheduler": true, "filterByService": false, "serviceIds": null, "active": true, "tagName": null, "oldFieldIds": null, "validationRegex": null, "validationError": null, "mask": null, "createdUser": "MO122", "createdDate": 1706817100000, "modifiedUser": "MO122", "modifiedDate": 1706817100000, "defaultValue": null, "defaultNullValue": null, "internalLabel": null, "depFieldDefnId": null, "depType": null, "depValue": null, "depCondition": null, "depAction": null, "depSetValue": null, "depError": null, "allowClientEdit": true, "requiredJSON": null, "styleJSON": null, "value": null, "extendedValue": null, "valueMap": null, "valueList": null, "errorMessage": null, "internalDisplayName": "Within Number of days", "valueTag": "%CUSTOM_FIELD_35001%", "labelTag": "%CUSTOM_FIELD_35001_LABEL%", "basicTagName": null, "showOnScheduler": true, "enable": true, "dropdownValues": [ "Yes", "No" ], "depFieldDefnIdObjs": [], "depFieldDefnIds": [] } ], "businessId": 20344, "location": { "locationId": 42173, "locationName": "My Office", "description": "", "directions": null, "logoUrl": null, "locationType": "Office", "allowTZChange": null, "latitude": null, "longitude": null, "officePhone": null, "timezone": "America/New_York", "virtualRoomUrl": null, "displayName": "My Office", "selected": true }, "reason": { "reasonId": 99753, "businessId": 20344, "visitMinutes": 60, "reasonDesc": "Test Service", "reasonDetail": null, "price": null, "originalPrice": null, "depositAmount": null, "imageUrl": null, "numberSessions": null, "reasonType": "SERVICE", "requireStaffConfirmation": null, "bookMultipleAppts": false, "allowWaitList": false, "requirePreAuthPayment": false, "requirePayment": false, "showPayNowButton": null, "screeningQuestion": null, "durationList": null, "apptHrMin": 1, "apptDayMax": 90, "taxable": false, "emailInstructions": null, "emailInstructions2": null, "allowRepeating": -1, "repeatingApptOptionList": null, "allowChoosePayAmount": true, "addOnReasonList": null, "requireApptIntent": false, "displayName": "Test Service", "multiDuration": false, "friendlyDuration": "1 Hour ", "selected": true, "needToSelectDuration": false, "needToSelectRepeatingOption": false }, "price": null, "addOnReasonIdList": null, "staff": null, "startTime": 1500, "clientStartTime": 1500, "clientStartTimeForDisplay": 1300, "clientStartTimeDate": "2024-06-05T13:00:00-06:00", "endTime": 1600, "clientEndTime": 1600, "clientEndTimeForDisplay": 1400, "clientEndTimeDate": "2024-06-05T14:00:00-06:00", "clientStartDate": "2024-06-05", "clientEndDate": "2024-06-05", "classScheduleId": null, "recurringSchedule": { "recurringScheduleId": null }, "recurringScheduleId": null, "hideGuestOption": false, "cartDisplayStartDateTime": "2024-06-05T13:00:00-06:00", "cartDisplayEndDateTime": "2024-06-05T14:00:00-06:00", "maxCapacity": null, "currentCapacity": null, "reasonId": 99753, "professionalId": null, "locationId": 42173, "timeSlotId": "2024-6-5:1500-1600", "clientTimeSlotId": "2024-6-5:1300-1400", "htmlId": "2024-6-5:1500-16002024-6-5:1300-1400", "calTimeSlot": { "staffStartDate": "2024-06-05", "staffEndDate": "2024-06-05", "staffStartTime": 1500, "staffEndTime": 1600, "startTime": 1500, "endTime": 1600, "clientStartDate": "2024-06-05", "clientEndDate": "2024-06-05", "clientStartTime": 1300, "clientEndTime": 1400, "timeString": "1:00 PM - 2:00 PM", "units": [ { "professionalId": 44501, "locationId": 42173, "reasonId": 99753, "resourceId": null, "bundleResourceIdList": null, "businessRoleId": 8, "tandemStaffIdList": null, "roundRobin": false, "roleSet": null }, { "professionalId": 44502, "locationId": 42173, "reasonId": 99753, "resourceId": null, "bundleResourceIdList": null, "businessRoleId": 9, "tandemStaffIdList": null, "roundRobin": false, "roleSet": null }, { "professionalId": 44503, "locationId": 42173, "reasonId": 99753, "resourceId": null, "bundleResourceIdList": null, "businessRoleId": 9, "tandemStaffIdList": null, "roundRobin": false, "roleSet": null }, { "professionalId": 44504, "locationId": 42173, "reasonId": 99753, "resourceId": null, "bundleResourceIdList": null, "businessRoleId": 9, "tandemStaffIdList": null, "roundRobin": false, "roleSet": null }, { "professionalId": 44077, "locationId": 42173, "reasonId": 99753, "resourceId": null, "bundleResourceIdList": null, "businessRoleId": 11, "tandemStaffIdList": null, "roundRobin": false, "roleSet": null }, { "professionalId": 44587, "locationId": 42173, "reasonId": 99753, "resourceId": null, "bundleResourceIdList": null, "businessRoleId": 10, "tandemStaffIdList": null, "roundRobin": false, "roleSet": null } ], "staffStartDateTimeUTC": 1717614000000, "staffEndDateTimeUTC": 1717617600000, "calendarRoleList": null, "appointmentIntentId": null, "waitListMode": false, "startTimeDateForTimeslotDisplay": "2024-06-05T13:00:00-06:00", "endTimeDateForTimeslotDisplay": "2024-06-05T14:00:00-06:00", "startTimeDate": "2024-06-05T21:00:00.000Z", "endTimeDate": "2024-06-05T22:00:00.000Z", "timeSlotId": "2024-6-5:1500-1600", "clientTimeSlotId": "2024-6-5:1300-1400", "htmlId": "2024-6-5:1500-16002024-6-5:1300-1400", "classScheduleId": null }, "waitListMode": false, "isWaitListFirstAvail": false, "startDateTimeUTC": 1717614000000, "endDateTimeUTC": 1717617600000, "startDate": "2024-06-05", "endDate": "2024-06-05", "apptDurationMinutesClient": 60, "sendConfirmationToStaff": true, "sendConfirmationToClient": true, "staffStartTimeDate": "2024-06-05T13:00:00-06:00", "staffEndTimeDate": "2024-06-05T14:00:00-06:00", "remindClientSmsHrs": 0, "client": { "clientId": 2199432, "businessId": 20344, "fullName": "Test User", "firstName": "Test", "lastName": "User", "companyName": null, "status": "Active", "deleted": false, "locale": "en-US", "emailAddress": "test@test.com", "timeZoneCode": { "timeZoneId": 39, "timeZoneCode": "America/Denver", "timeZoneDesc": "America/Denver", "visible": null, "sortOrder": null }, "clientAccountId": null, "password": null, "fields": [ { "schedulerPreferenceFieldDefnId": 29244, "businessId": 20344, "code": "firstName", "dataType": "TXT", "mode": "CLIENT", "label": "First Name", "hint": null, "fieldValues": null, "sortOrder": 0, "required": true, "visible": true, "userDefinedField": false, "visibleOnScheduler": true, "filterByService": false, "serviceIds": null, "active": true, "tagName": "CLIENT_FIRSTNAME", "oldFieldIds": null, "validationRegex": null, "validationError": null, "mask": null, "createdUser": "Mo122", "createdDate": 1659375013000, "modifiedUser": "Mo122", "modifiedDate": 1659375013000, "defaultValue": null, "defaultNullValue": null, "internalLabel": null, "depFieldDefnId": null, "depType": null, "depValue": null, "depCondition": null, "depAction": null, "depSetValue": null, "depError": null, "allowClientEdit": true, "requiredJSON": null, "styleJSON": null, "value": "Test", "extendedValue": "Test", "valueMap": null, "valueList": null, "errorMessage": null, "internalDisplayName": "First Name", "valueTag": "%CLIENT_FIRSTNAME%", "labelTag": "%CLIENT_FIRSTNAME_LABEL%", "basicTagName": "CLIENT_FIRSTNAME" }, { "schedulerPreferenceFieldDefnId": 29245, "businessId": 20344, "code": "lastName", "dataType": "TXT", "mode": "CLIENT", "label": "Last Name", "hint": null, "fieldValues": null, "sortOrder": 1, "required": true, "visible": true, "userDefinedField": false, "visibleOnScheduler": true, "filterByService": false, "serviceIds": null, "active": true, "tagName": "CLIENT_LASTNAME", "oldFieldIds": null, "validationRegex": null, "validationError": null, "mask": null, "createdUser": "Mo122", "createdDate": 1659375013000, "modifiedUser": "Mo122", "modifiedDate": 1659375013000, "defaultValue": null, "defaultNullValue": null, "internalLabel": null, "depFieldDefnId": null, "depType": null, "depValue": null, "depCondition": null, "depAction": null, "depSetValue": null, "depError": null, "allowClientEdit": true, "requiredJSON": null, "styleJSON": null, "value": "User", "extendedValue": "User", "valueMap": null, "valueList": null, "errorMessage": null, "internalDisplayName": "Last Name", "valueTag": "%CLIENT_LASTNAME%", "labelTag": "%CLIENT_LASTNAME_LABEL%", "basicTagName": "CLIENT_LASTNAME" }, { "schedulerPreferenceFieldDefnId": 29248, "businessId": 20344, "code": "emailAddress", "dataType": "TXT", "mode": "CLIENT", "label": "Email", "hint": null, "fieldValues": null, "sortOrder": 4, "required": true, "visible": true, "userDefinedField": false, "visibleOnScheduler": true, "filterByService": false, "serviceIds": null, "active": true, "tagName": "CLIENT_EMAILADDRESS", "oldFieldIds": null, "validationRegex": null, "validationError": null, "mask": null, "createdUser": "Mo122", "createdDate": 1659375013000, "modifiedUser": "Mo122", "modifiedDate": 1659375013000, "defaultValue": null, "defaultNullValue": null, "internalLabel": null, "depFieldDefnId": null, "depType": null, "depValue": null, "depCondition": null, "depAction": null, "depSetValue": null, "depError": null, "allowClientEdit": true, "requiredJSON": null, "styleJSON": null, "value": "test@test.com", "extendedValue": "test@test.com", "valueMap": null, "valueList": null, "errorMessage": null, "internalDisplayName": "Email", "valueTag": "%CLIENT_EMAILADDRESS%", "labelTag": "%CLIENT_EMAILADDRESS_LABEL%", "basicTagName": "CLIENT_EMAILADDRESS" }, { "schedulerPreferenceFieldDefnId": 29251, "businessId": 20344, "code": "homePhone", "dataType": "TXT", "mode": "CLIENT", "label": "Home Phone", "hint": null, "fieldValues": null, "sortOrder": 7, "required": false, "visible": true, "userDefinedField": false, "visibleOnScheduler": true, "filterByService": false, "serviceIds": null, "active": true, "tagName": "CLIENT_HOME_PHONE", "oldFieldIds": null, "validationRegex": null, "validationError": null, "mask": null, "createdUser": "Mo122", "createdDate": 1659375013000, "modifiedUser": "Mo122", "modifiedDate": 1659375013000, "defaultValue": null, "defaultNullValue": null, "internalLabel": null, "depFieldDefnId": null, "depType": null, "depValue": null, "depCondition": null, "depAction": null, "depSetValue": null, "depError": null, "allowClientEdit": true, "requiredJSON": null, "styleJSON": null, "value": null, "extendedValue": null, "valueMap": null, "valueList": null, "errorMessage": null, "internalDisplayName": "Home Phone", "valueTag": "%CLIENT_HOME_PHONE%", "labelTag": "%CLIENT_HOME_PHONE_LABEL%", "basicTagName": "CLIENT_HOME_PHONE" }, { "schedulerPreferenceFieldDefnId": 29252, "businessId": 20344, "code": "cellPhone", "dataType": "TXT", "mode": "CLIENT", "label": "Cell Phone", "hint": null, "fieldValues": null, "sortOrder": 8, "required": false, "visible": true, "userDefinedField": false, "visibleOnScheduler": true, "filterByService": false, "serviceIds": null, "active": true, "tagName": "CLIENT_MOBILE_PHONE", "oldFieldIds": null, "validationRegex": null, "validationError": null, "mask": null, "createdUser": "Mo122", "createdDate": 1659375013000, "modifiedUser": "Mo122", "modifiedDate": 1659375013000, "defaultValue": null, "defaultNullValue": null, "internalLabel": null, "depFieldDefnId": null, "depType": null, "depValue": null, "depCondition": null, "depAction": null, "depSetValue": null, "depError": null, "allowClientEdit": true, "requiredJSON": null, "styleJSON": null, "value": null, "extendedValue": null, "valueMap": null, "valueList": null, "errorMessage": null, "internalDisplayName": "Cell Phone", "valueTag": "%CLIENT_MOBILE_PHONE%", "labelTag": "%CLIENT_MOBILE_PHONE_LABEL%", "basicTagName": "CLIENT_MOBILE_PHONE" } ], "createdDate": 1717607536345, "createdUser": "WebClient", "modifiedUser": "WebClient", "modifiedDate": 1717607536390, "externalUserName": null, "imageUrl": null, "viewClientAccountIds": null, "allowWaitListText": null, "hasCardOnFile": null, "formList": [], "clientHash": null, "excludeEmailCategoryIdList": null, "excludeEmailTemplateIdList": null } }

Appointments API Responses

{ "calendarId": 672612887, "businessId": 20344, "status": "OPEN", "subStatus": "OPEN", "staffTimeText": null, "reason": { "reasonId": 99753, "businessId": 20344, "visitMinutes": 60, "reasonDesc": "Test Service", "reasonDetail": null, "price": null, "originalPrice": null, "depositAmount": null, "imageUrl": null, "numberSessions": null, "reasonType": "SERVICE", "requireStaffConfirmation": null, "bookMultipleAppts": false, "allowWaitList": false, "requirePreAuthPayment": false, "requirePayment": false, "showPayNowButton": null, "screeningQuestion": null, "durationList": null,