Page Comparison

Anchor

	topOfPage
	topOfPage

The Appointments API is used to access, create, and modify the appointments on your business' account. The Appointments API is connected to the Locations, Staff, Services, and Resources APIs as appointments include all of those APIs. Since appointments are the main way your business will make money, it is crucial for you to familiarize yourself with how to get, create, and update the different appointments on your account.

Info

title	On this page

Table of Contents

These are the endpoints that are available under the /appointments path, which lists all the different appointments you have scheduled on your business' calendar.

Endpoint

Description

GET /appointmentList/report

Returns all appointment objects on an account in array format.

GET /appointmentList/reportWithCount

Returns an object that contains a list of appointments along with a count of the total number of appointments that match the parameters passed with the call.

GET /appointments/{calendarId}

Returns a JSON object for specified appointment.

GET /appointments/resource/{resourceId}/{statusList}

Returns all appointment objects that include specified resource in array format.

GET /appointments/recurringappointments/{recurringApptId}

Returns an array of appointment objects that were part of the recurring appointment series that contains specified appointment as determined by the value set in its recurringAppointmentId.

GET /appointments/{calendarId}/checkWaitList

Checks the waitlist of specified appointment before updating appointment object.

To send an invitation out to a waitlist registrant to claim a cancelled appointment, make this call and select which candidates that return you want to invite to claim it. You then take the waitListIds from each of those registrations and pass them in the waitListIds parameter of the PUT /appointments/{calendarId}/cancel/{sendStaffEmail}/{sendClientEmail} to place a hold event on your calendar that will stay until either the client claims it or the allotted time frame has elapsed.

POST /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.

PUT /appointments/{calendarId}

Updates an existing appointment object.

Request body/payload: Must pass an appointment object with the desired changes made.

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

PUT /appointments/{calendarId}/{status}/{subStatus}

Updates the specified appointment's status & substatus.

This call simply offers a generic method to update the status of an appointment instead of using a specific one.

PUT /appointments/{calendarId}/cancel/{sendStaffEmail}/{sendClientEmail}

Sets an appointment to a substatus of CANCELLED and alters the boolean property accordingly to notify the client via email. Effectively cancels an appointment with the option to send an email to the staff and the client.

To send an invitation out to a waitlist registrant to claim a cancelled appointment, make a GET /appointments/{calendarId}/checkWaitList call and then take the waitListIds from the returning waitlist objects that you want to invite and pass them in the waitListIds parameter of this call. This will place a waitlist hold event on your calendar that will stay until either the client claims it or the allotted time frame has expired. The waitlist hold is just an appointment without a client assigned to it. If you wish to remove this waitlist hold before a client claims it or the allotted time frame has expired you can use this endpoint to update the appointment and set the appointment object's status and substatus to CANCELLED.

Request body/payload: Optionally, you may pass a json payload with reason and substatus

Code Block
{ "reason": "", "subStatus": "CANCELLED" }

PUT /appointments/{calendarId}/noshow/{sendClientEmail}

Sets an appointment to a substatus of NO_SHOW and alters boolean flag accordingly to notify the client via email.

Request body/payload: Optionally, you may pass a json payload with reason and substatus

Code Block
{ "reason": "", "subStatus": "NO_SHOW" }

PUT /appointments/{calendarId}/completed/{sendClientEmail}

Sets an appointment to a substatus of COMPLETED and alters boolean flag accordingly to send a thank you email to the client.

Request body/payload: Optionally, you may pass a json payload with reason and substatus

Code Block
{ "reason": "", "subStatus": "COMPLETED" }

GET/POST /appointmentList/reportCount

Returns number of appointments based on the parameters that get passed. Acceptable parameters can be found in the Appointments API Parameters section.

GET/POST /appointmentList/reportCountsByStatus

Returns number of appointments based on the parameters that get passed for each appointment status that gets passed in the statusList parameter. Accepts the same parameters as the GET/POST /appointmentList/reportCount endpoint, looking at reasonIdList, locationIdList and staffIdList in particular.

Data points passed on in the request URL portion of the API call that are used to filter the data being requested. To aid with page load time, we have included pageNumber and pageSize parameters for server side pagination. The pageSize parameter will be the number of items shown per page.

Parameter	Type	Endpoints to be used with	Description
calendarIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of calendarIds connected to the appointments to be returned following the API call.
classScheduleId	integer	GET /appointments/report	Should be set as the unique numeric ID of client of appointment to be returned following the API call.
classScheduleIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of classScheduleIds connected to the appointments to be returned following the API call.
clientId	integer	GET /appointments/report	Should be set as the ID of client of appointment to be returned following the API call.
clientIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of the clientIds connected to the appointments to be returned following the API call.
couponIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus	Should be set as a comma-separated list of couponIds connected to the appointments to be returned following the API call.
endDate	string	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as the end date of appointments to be returned following the API call, formatted as YYYY-MM-DD.
excludeTimeOff	boolean	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	If set to TRUE then the API call does not return appointments that are set for reasons of reasonType PERSONAL; if set to FALSE then it does return appointments that are set for reasons of reasonType PERSONAL.
locationIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of locationIds connected to the appointments to be returned following the API call.
locationGroupIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of locationGroupIds connected to the appointments to be returned following the API call.
onlyTimeOff	integer	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Can be set to 0 or 1; if set to 0 then reads as essentially false; if set to 1 then only appointments that are set for reasons that are of reasonType PERSONAL will return following the API call.
order_field	string	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report	Should be set as the field that appointments returned following the API call should be ordered by.
order_mode	string	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report	Should be set as the mode ('asc'ending or 'desc'ending) in which appointments returned following the API call should appear.
override	boolean	POST /appointments	Can be set to 0 or 1; if set to 0 then staff for specified appointment is free during that time slot; if set to 1 you are overriding the staff's work schedule and effectively double booking him or her.
packageSoldIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of packageSoldIds connected to the appointments to be returned following the API call.
pageNumber	integer	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report	Works with the pageSize parameter to determine how appointments get returned following the API call. The pageNumber value represents the number of pages on which the appointments that get returned appear.
pageSize	integer	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report	Works with the pageNumber parameter to determine how appointments gets returned following the API call. The pageSize value represents the number of appointments appearing on each page that gets returned.
reasonIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of reasonIds connected to the appointments you want returned following the API call. This parameter is optional - if it is not sent in then the return results will include all reasons (except reasonTypes of PERSONAL if the excludeTimeOff property is set to false).
recurringApptIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of recurringApptIds connected to the appointments to be returned following the API call.
resourceIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of resourceIds connected to the appointments to be returned following the API call.
showApptTz	boolean	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report	Determines whether or not the apptTz field will be filled when making this API call.
showClientForms	boolean	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report	Should be set as TRUE or FALSE depending on whether or not the appointments to be returned following the API are set to show client forms.
staffIdList	integer array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of unique numeric IDs of staff of appointments to be returned following the API call.
startDate	string	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as the start date of appointments to be returned following the API call, formatted as YYYY-MM-DD.
statusList	string array	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as a comma-separated list of statuses of the appointments you want returned following the API call. Has acceptable values OPEN, CLOSED, INPROGRESS, COMPLETED, READ_ONLY, PENDING, PENDING_CONFIRMATION, PENDING_WAITLIST, CHECKEDIN, CANCELLED, and CONFIRMED.
uninvoiced	boolean	GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report	Should be set as TRUE or FALSE depending on whether or not the appointments to be returned following the API are invoiced.
waitListIds	integer array	PUT /appointments/{calendarId}	Should be set as a comma-separated list of waitListIds to be invited to claim the spot of a cancelled appointment.

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.

Code Block

language	js
title	POST /appointments
linenumbers	true
collapse	true

{
    "additionalStaffIdList": [],
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "calendarDateSelection": "2019-02-22T11:30:00",
    "classScheduleId": null,
    "client": {Client object for client of appointment - for more info, see Clients API page},
    "clientEndTime": 1630,
    "clientReminderHours": 0,
    "clientStartTime": 1530,
    "date": "2019-02-22",
    "endDate": "2019-02-22",
    "endTime": 1630,
    "fields": [{Fields object for scheduler fields of appointment - for more info, see Scheduler Fields API page}],
    "location": {Locations object for location of appointment - for more info, see Locations API page},
    "locationGroup": null,
    "locationSuperGroup": null,
    "note": "",
    "price": null,
    "reason": {Reason object for service of appointment - for more info, see Services API page}
    "reasonGroup": null,
    "remindClientSmsHrs": 0,
    "remindStaffSmsHrs": 0,
    "resource": null,
    "resourceId": null,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment - for more info, see Staff API page},
    "staffReminderHours": 0,
    "startDate": "2019-02-22",
    "startTime": 1530,
    "status": "OPEN"
}

Code Block

language	js
title	PUT /appointments
linenumbers	true
collapse	true

{
    "businessId": 43111,
    "calendarId": 19982707,
    "clientEndDate": "2019-02-08",
    "clientEndTime": 1700,
    "clientReminderHours": 24,
    "clientRescheduleCount": 0,
    "clientStartDate": "2019-02-08",
    "clientStartTime": 1630,
    "coordinatorStaff": {Staff object for coordinator staff of appointment - for more info, see Staff API page},
    "createddate": "2019-02-07 18:18:46",
    "createduser": "JoeSchmo"
    "date": "2019-02-08",
    "endDate": "2019-02-08",
    "endTime": 1700,
    "fields": [{Fields object for scheduler fields of appointment - for more info, see Scheduler Fields API page}],
    "location": {Location object for location of appointment - for more info, see Locations API page},
    "originalDate": "2019-02-08",
    "originalStartTime": 1530,
    "price": 10,
    "reason": {Reason object for service of appointment - for more info, see Services API page},
    "remindClientSmsHrs": 1,
    "remindStaffSmsHrs": 0,
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment - for more info, see Staff API page},
    "staffReminderHours": 24,
    "staffRescheduleCount": 0,
    "staffTimeText": "Friday, Feb 8, 2019 at 15:30 EST",
    "startDate": "2019-02-08",
    "startTime": 1630,
    "status": "OPEN",
    "subStatus": "OPEN"
}

Code Block

language	js
title	GET /appointmentList/report
linenumbers	true
collapse	true

{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Aug 23, 2018 at 12:00 AM EDT",
    "appointmentDateTimeStaff": "Thursday, Aug 23, 2018 at 12:00 AM EDT",
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "calendarId": 17385962,
    "cancelReason": null,
    "cancelUser": null,
    "changeReason": null,
    "classScheduleId": null,
    "client": {Client object for client of appointment - for more info, see Clients API page},
    "clientConfirmedDate": 1532371154462,
    "clientConfirmed": true,
    "clientEndDate": "2018-08-23",
    "clientEndTime": 2400,
    "clientReminderHours": 0,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-08-23",
    "clientStartTime": 0,
    "color": "#668CD9",
    "completedReason": null,
    "coordinatorStaff": null,
    "coupon": null,
    "couponId": null,
    "createddate": "2018-06-27 10:04:36",
    "createduser": "JoeSchmo",
    "customFieldDesc": "",
    "date": "2018-08-23",
    "dateCheckedIn": null,
    "dateCompleted": null,
    "dateStarted": null,
    "discount": null,
    "endDate": "2018-08-23",
    "endTime": 2400,
    "fields": {Fields object for scheduler fields of appointment - for more info, see Scheduler Fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment - for more info, see Locations API page},
    "locationGroup": {Groups object for location group of appointment - for more info, see Groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": null,
    "note": "Need a day off",
    "packageSoldId": null,
    "price": null,
    "reason": {Reason object for service of appointment - for more info, see Services API page},
    "reasonGroup": {Groups object for reason group of appointment - for more info, see Groups API page},
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": null,
    "remindClientSmsHrs": 0,
    "remindStaffSmsHours": 0,
    "resource": {Resource object for resource of appointment - for more info, see Resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment - for more info, see Staff API page},
    "staffReminderHours": 0,
    "staffRescheduleCount": 0,
    "startDate": "2018-07-26",
    "startTime": 945,
    "status": "OPEN",
    "subStatus": "CONFIRMED",
    "transactionFee": null,
    "waitlistId": null
}

Code Block

language	js
title	GET /appointmentList/reportWithCount
linenumbers	true
collapse	true

{
    "appts": [
{
        "addOnReasonIdList": null,
        "addOnReasonList": null,
        "additionalStaffIdList": null,
        "address": null,
        "appointementIdHash": "m0RqfvnNb1",
        "appointmentDateTimeClient": "Thursday, May 17, 2018 at 12:00 PM EDT",
        "appointmentDateTimeStaff": "Thursday, May 17, 2018 at 12:00 PM EDT",
        "apptTZ": null,
        "batchAppointmentId": null,
        "blockResourceIdList": null,
        "blockStaffIdList": [],
        "blockedStaffList": [],
        "businessId": 43111,
        "calTimeSlot": null,
        "calendarId": 17285011,
        "cancelReason": null,
        "cancelUser": null,
        "changeReason": null,
        "classScheduleId": null,
        "classroom": null,
        "client": {Client object for client of appointment - for more info, see Clients API page},
        "clientConfirmDate": null,
        "clientConfirmed": false,
        "clientEndDate": "2018-05-17",
        "clientEndDateTime": 1526563800000,
        "clientEndDateTimeUTC": 1526563800000,
        "clientEndTime": 1330,
        "clientReminderHours": 24,
        "clientRescheduleCount": 0,
        "clientStartDate": "2018-05-17",
        "clientStartDateTime": 1526558400000,
        "clientStartDateTimeUTC": 1526558400000,
        "clientStartTime": 1200,
        "color": null,
        "completedReason": null,
        "coordinatorStaff": {Staff object for coordinator staff of appointment - for more info, see Staff API page},
        "coupon": null,
        "couponId": null,
        "createddate": "2018-07-27 16:10:55",
        "createduser": "MORGANKEARNEY",
        "customField1": null,
        "customField2": null,
        "customField3": null,
        "customFieldData": null,
        "customFieldDesc": "",
        "date": "2018-05-17",
        "dateCheckedIn": null,
        "dateCompleted": 1532708595255,
        "dateStarted": null,
        "discount": null,
        "endDate": "2018-05-17",
        "endDateTimeUTC": 1526577900000,
        "endTime": 1325,
        "externalEventId": null,
        "fields": [{Fields object for scheduler fields of appointment - for more info, see Scheduler Fields API page}],
        "invitationUUId": null,
        "jobRequisitionId": null,
        "location": {Location object for location of appointment - for more info, see Locations API page},
        "locationGroup": {Groups object for location group of appointment - for more info, see Groups API page},
        "locationSuperGroup": null,
        "manageApptUrl": "https://www.timetap.com/businessWeb/web/manage/m0RqfvnNb1",
        "modifieddate": null,
        "modifieduser": null,
        "noPrefSelected": false,
        "noShowReason": null,
        "note": "",
        "packageSoldId": null,
        "price": 8,
        "reason": {Reasons object for service of appointment - for more info, see Services API page},
        "reasonBatchSeriesId": null,
        "reasonDesc": null,
        "reasonGroup": {Groups object for reason group of appointment - for more info, see Groups API page},
        "recall": null,
        "recallDate": null,
        "recallStatus": null,
        "recurringAppointmentId": null,
        "remindClientSmsHrs": 1,
        "remindStaffSmsHrs": 0,
        "resource": {Resources object for resource of appointment - for more info, see Resources API page},
        "seats": 1,
        "sendConfirmationToClient": true,
        "sendConfirmationToStaff": true,
        "showAs": null,
        "staff": {Staff object for staff of appointment - for more info, see Staff API page},
        "staffReminderHours": 24,
        "staffRescheduleCount": 0,
        "staffTimeText": "Thursday, May 17, 2018 at 12:00 PM EDT",
        "startDate": "2018-05-17",
        "startDateTimeUTC": 1526572500000,
        "startTime": 1155,
        "status": "COMPLETED",
        "subStatus": "COMPLETED",
        "subject": null,
        "tax1Amount": null,
        "ticket": null,
        "transactionFee": null,
        "waitListId": null
}],
    "count": 1157}

Code Block

language	js
title	GET /appointments/{appointmentId}
linenumbers	true
collapse	true

{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Jul 26, 2018 at 8:00 AM FNT",
    "appointmentDateTimeStaff": "Thursday, Jul 26, 2018 at 8:00 AM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "calendarId": 16902079,
    "cancelReason": null,
    "cancelUser": null,
    "changeReason": "",
    "classScheduleId": null,
    "client": {Client object for client of appointment - for more info, see Clients API page},
    "clientConfirmedDate": 1532371154462,
    "clientConfirmed": true,
    "clientEndDate": "2018-07-25",
    "clientEndTime": 900,
    "clientReminderHours": 1,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-07-26",
    "clientStartTime": 800,
    "color": "#668CD9",
    "completedReason": null,
    "coordinatorStaff": null,
    "coupon": null,
    "couponId": null,
    "createddate": "2018-06-21 14:45:52",
    "createduser": "JoeSchmo",
    "customFieldDesc": "Comments : Boo!",
    "date": "2018-07-26",
    "dateCheckedIn": null,
    "dateCompleted": null,
    "discount": null,
    "endDate": "2018-07-26",
    "endTime": 930,
    "fields": {Fields object for scheduler fields of appointment - for more info, see Scheduler Fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment - for more info, see Locations API page},
    "locationGroup": {Groups object for location group of appointment - for more info, see Groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": null,
    "note": "",
    "packageSoldId": null,
    "price": null,
    "reason": {Reason object for service of appointment - for more info, see Services API page},
    "reasonGroup": {Groups object for reason group of appointment - for more info, see Groups API page},
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": 101096,
    "remindClientSmsHrs": 2,
    "remindStaffSmsHours": 4,
    "resource": {Resource object for resource of appointment - for more info, see Resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment - for more info, see Staff API page},
    "staffReminderHours": 3,
    "staffRescheduleCount": 9,
    "startDate": "2018-07-26",
    "startTime": 945,
    "status": "OPEN",
    "subStatus": "CONFIRMED",
    "transactionFee": null,
    "waitlistId": null
}

Code Block

language	js
title	GET /appointments/resource/{resourceId}/{resourceId}/{statusList}
linenumbers	true
collapse	true

[{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "appointmentDateTimeStaff": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "calendarId": 17246703,
    "cancelReason": "",
    "cancelUser": "JoeSchmo",
    "changeReason": "",
    "classScheduleId": null,
    "client": null,
    "clientConfirmedDate": 1532371154462,
    "clientConfirmed": false,
    "clientEndDate": "2018-07-26",
    "clientEndTime": 1330,
    "clientReminderHours": 0,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-07-26",
    "clientStartTime": 1200,
    "color": null,
    "completedReason": "",
    "coordinatorStaff": {Staff object for coordinator staff of appointment - for more info, see Staff API page},
    "coupon": null,
    "couponId": null,
    "createddate": "2018-07-24 16:10:52",
    "createduser": "JoeSchmo",
    "customFieldDesc": "".
    "date": "2018-07-26",
    "dateCheckedIn": null,
    "dateCompleted": 1530785153340,
    "dateStarted": 1532525579100,
    "discount": null,
    "endDate": "2018-07-26",
    "endTime": 1325,
    "fields": {Fields object for scheduler field of appointment - for more info, see Scheduler Fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment - for more info, see Locations API page},
    "locationGroup": {Groups object for location group of appointment - for more info, see Groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": "",
    "note": "",
    "packageSoldId": null,
    "price": 8,
    "reason": {Reason object for service of appointment - for more info, see Services API page},
    "reasonGroup": null,
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": null,
    "remindClientSmsHrs": 1,
    "remindStaffSmsHours": 0,
    "resource": {Resource object for resource of appointment - for more info, see Resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment - for more info, see Staff API page},
    "staffReminderHours": 0,
    "staffRescheduleCount": 6,
    "startDate": "2018-07-26",
    "startTime": 1115,
    "status": "COMPLETED",
    "subStatus": "INPROGRESS",
    "transactionFee": null,
    "waitlistId": null
}]

Code Block

language	js
title	GET /appointments/recurringappointments/{recurringappointmentId}
linenumbers	true
collapse	true

{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Jun 28, 2018 at 8:00 AM FNT",
    "appointmentDateTimeStaff": "Thursday, Jun 28, 2018 at 8:00 AM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": null,
    "businessId": 43111,
    "calendarId": 16902075,
    "cancelReason": null,
    "cancelUser": null,
    "changeReason": "",
    "classScheduleId": null,
    "classroom": null,
    "client": {Client object for client of appointment - for more info, see Clients API page},
    "clientConfirmedDate": 1532371154462,
    "clientConfirmed": true,
    "clientEndDate": "2018-06-28",
    "clientEndTime": 900,
    "clientReminderHours": 0,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-06-28",
    "clientStartTime": 800,
    "color": "#668CD9",
    "completedReason": null,
    "coordinatorStaff": {Staff object for coordinator staff of appointment - for more info, see Staff API page},
    "coupon": null,
    "couponId": null,
    "createddate": "2018-06-21 14:45:51",
    "createduser": "JoeSchmo",
    "customFieldDesc": "".
    "date": "2018-06-28",
    "dateCheckedIn": null,
    "dateCompleted": 1530785153340,
    "discount": null,
    "endDate": "2018-06-28",
    "endTime": 900,
    "fields": null,
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment - for more info, see Locations API page},
    "locationGroup": {Groups object for location group of appointment - for more info, see Groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": null,
    "note": "",
    "packageSoldId": null,
    "price": null,
    "reason": {Reason object for service of appointment - for more info, see Services API page},
    "reasonGroup": {Groups object for reason group of appointment - for more info, see Groups API page},
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": 101096,
    "remindClientSmsHrs": 0,
    "remindStaffSmsHours": 0,
    "resource": {Resource object for resource of appointment - for more info, see Resources API page},
    "seats": 1,
    "sendConfirmationToClient": true,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment - for more info, see Staff API page},
    "staffReminderHours": 0,
    "staffRescheduleCount": 0,
    "startDate": "2018-06-28",
    "startTime": 800,
    "status": "COMPLETED",
    "subStatus": "COMPLETED",
    "transactionFee": null,
    "waitlistId": null
}

Code Block

language	js
title	POST /appointments
linenumbers	true
collapse	true

{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "appointmentDateTimeStaff": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "calendarId": 17584855,
    "cancelReason": "",
    "cancelUser": "JoeSchmo",
    "changeReason": "",
    "classScheduleId": 33577312,
    "client": null,
    "clientConfirmedDate": null,
    "clientConfirmed": null,
    "clientEndDate": "2018-09-07",
    "clientEndTime": 1500,
    "clientReminderHours": 24,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-09-07",
    "clientStartTime": 1400,
    "color": null,
    "completedReason": null,
    "coordinatorStaff": null,
    "coupon": null,
    "couponId": null,
    "createddate": "2018-08-23 13:26:59",
    "createduser": "JoeSchmo",
    "customFieldDesc": "".
    "date": "2018-09-07",
    "dateCheckedIn": null,
    "dateCompleted": null,
    "dateStarted": null,
    "discount": null,
    "endDate": "2018-09-07",
    "endTime": 1500,
    "fields": {Fields object for scheduler field of appointment - for more info, see Scheduler Fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment - for more info, see Locations API page},
    "locationGroup": {Groups object for location group of appointment - for more info, see Groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": "",
    "note": "",
    "packageSoldId": null,
    "price": 10,
    "reason": {Reason object for service of appointment - for more info, see Services API page},
    "reasonGroup": null,
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": null,
    "remindClientSmsHrs": 1,
    "remindStaffSmsHours": 0,
    "resource": {Resource object for resource of appointment - for more info, see Resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment - for more info, see Staff API page},
    "staffReminderHours": 24,
    "staffRescheduleCount": 0,
    "startDate": "2018-09-07",
    "startTime": 1400,
    "status": "OPEN",
    "subStatus": "OPEN",
    "transactionFee": null,
    "waitlistId": null
}

Code Block

language	js
title	PUT /appointments/{appointmentId}
linenumbers	true
collapse	true

{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Aug 2, 2018 at 8:00 AM FNT",
    "appointmentDateTimeStaff": "Thursday, Aug 2, 2018 at 8:00 AM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "calendarId": 16902080,
    "cancelReason": null,
    "cancelUser": null,
    "changeReason": "",
    "classScheduleId": null,
    "client": {Client object for client of appointment - for more info, see Clients API page},
    "clientConfirmedDate": 1532371154462,
    "clientConfirmed": false,
    "clientEndDate": "2018-08-02",
    "clientEndTime": 900,
    "clientReminderHours": 0,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-08-02",
    "clientStartTime": 800,
    "color": "#668CD9",
    "completedReason": null,
    "coordinatorStaff": null,
    "coupon": null,
    "couponId": null,
    "createddate": "2018-06-21 14:45:52",
    "createduser": "JoeSchmo",
    "customFieldDesc": "",
    "date": "2018-08-02",
    "dateCheckedIn": null,
    "dateCompleted": null,
    "discount": null,
    "endDate": "2018-08-02",
    "endTime": 930,
    "fields": {Fields object for scheduler fields of appointment - for more info, see Scheduler Fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment - for more info, see Locations API page},
    "locationGroup": {Location group object for location group of appointment - for more info, see Groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": null,
    "note": "",
    "packageSoldId": null,
    "price": null,
    "reason": {Reason object for service of appointment - for more info, see Services API page},
    "reasonGroup": {Reason group object for reason group of appointment - for more info, see Groups API page},
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": 101096,
    "remindClientSmsHrs": 2,
    "remindStaffSmsHours": 4,
    "resource": {Resource object for resource of appointment - for more info, see Resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment - for more info, see Staff API page},
    "staffReminderHours": 3,
    "staffRescheduleCount": 9,
    "startDate": "2018-08-02",
    "startTime": 945,
    "status": "OPEN",
    "subStatus": "CONFIRMED",
    "transactionFee": null,
    "waitlistId": null
}

Code Block

language	js
title	PUT /appointments/{appointmentId}/noshow
linenumbers	true
collapse	true

{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "appointmentDateTimeStaff": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "calendarId": 1726703,
    "cancelReason": null,
    "cancelUser": null,
    "changeReason": "",
    "classScheduleId": null,
    "client": {Client object for client of appointment - for more info, see Clients API page},
    "clientConfirmedDate": 1532478709843,
    "clientConfirmed": false,
    "clientEndDate": "2018-07-26",
    "clientEndTime": 1330,
    "clientReminderHours": 0,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-07-26",
    "clientStartTime": 1200,
    "color": null,
    "completedReason": "",
    "coordinatorStaff": {Staff object for coordinator staff of appointment - for more info, see Staff API page},
    "coupon": null,
    "couponId": null,
    "createddate": "2018-07-24 16:10:52",
    "createduser": "JoeSchmo",
    "customFieldDesc": "",
    "date": "2018-07-26",
    "dateCheckedIn": 1532525743459,
    "dateCompleted": 1532526150687,
    "dateStarted": 1532525579100,
    "discount": null,
    "endDate": "2018-07-26",
    "endTime": 930,
    "fields": {Fields object for scheduler fields of appointment - for more info, see Scheduler Fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment - for more info, see Locations API page},
    "locationGroup": {Groups object for location group of appointment - for more info, see Groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": null,
    "note": "",
    "packageSoldId": null,
    "price": null,
    "reason": {Reason object for service of appointment - for more info, see Services API page},
    "reasonGroup": {Groups object for reason group of appointment - for more info, see Groups API page},
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": 101096,
    "remindClientSmsHrs": 2,
    "remindStaffSmsHours": 4,
    "resource": {Resource object for resource of appointment - for more info, see Resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment - for more info, see Staff API page},
    "staffReminderHours": 3,
    "staffRescheduleCount": 9,
    "startDate": "2018-08-02",
    "startTime": 945,
    "status": "OPEN",
    "subStatus": "CONFIRMED",
    "transactionFee": null,
    "waitlistId": null
}

Code Block

language	java
title	GET/POST /appointmentList/reportCountsByStatus
linenumbers	true
collapse	true

{
    "count": 0,
    "objectName": "Class, no sessions, staff 7",
    "objectType": "REASON",
    "objectId": 95576,
    "'status": "OPEN"
}

Property name	Type	Required	Writable	Description
additionalStaffIdList	array		Yes	Displays staffIds for any additional staff members you add to the appointment so they cannot otherwise be booked for this time slot.
address	string		Yes	Displays the address entered during appointment creation f appointment is set to a location of locationType VARIABLE.
appointmentDateTimeClient	string			Displays the date and time of the appointment as the client sees them.
appointmentDateTimeStaff	string			Displays the date and time of the appointment as the staff sees them. Can be different from client's view if staff has time blocked off between appointments or if staff is in a different timezone than client.
blockStaffIdList	array		Yes	Displays staffIds for any additional staff members you have added so they cannot be otherwise booked for this time slot. Whatever IDs are added to the additionalStaffIdList are automatically added to the blockStaffIdList. The blockStaffIdList is used to automatically block off staff across child accounts in our enterprise set up model.
blockedStaffList	array		Yes	Displays full staff objects for any additional staff members you have added in the blockStaffIdList or additionalStaffIdList.
businessId	integer	Yes		Provides unique numerical ID for the business that offers specified appointment.
calendarId	integer	Yes		Provides unique numerical ID of specified appointment.
cancelReason	string			Displays any reason given for cancelling specified appointment.
cancelUser	string			Displays as username of staff who cancelled specified appointment or as "WebClient" if client cancelled their own appointment. If appointment is marked as COMPLETED, username of the staff person who marked the appointment as completed displays here.
changeReason	string			Displays any reason given for changing specified appointment.
classScheduleId	integer		Yes	If specified appointment is an instance of a class schedule, this field will contain the unique numerical ID for that class schedule.
client	object		Yes	Displays the object of client who is connected to specified appointment - for more info, see Clients API page.
clientConfirmDate	integer		Yes	Displays the date in milliseconds elapsed since January 1 1970 UTC format that client was marked as confirmed for appointment.
clientConfirmed	boolean		Yes	Indicates whether or not the client has confirmed the appointment.
clientEndDate	string		Yes	Displays as date specified appointment is set to end without buffer displayed as YYYY-MM-DD.
clientEndTime	integer		Yes	Displays as time specified appointment is set to end without buffer displayed in military format.
clientReminderHours	integer		Yes	Displays the number of hours before the appointment that an email reminder will be sent to the client.
clientRescheduleCount	integer			Displays the number of times client has rescheduled specified appointment.
clientStartDate	string		Yes	Displays as date specified appointment is set to begin without buffer displayed as YYYY-MM-DD.
clientStartTime	integer		Yes	Displays as time specified appointment is set to begin without buffer displayed in military format.
color	string		Yes	Displays any color chosen to override specified appointment on the backoffice calendar.
completedReason	string			Displays any note the staff may have entered while marking the appointment as completed. Can be injected into completed email template sent to client with tag %COMPLETED_NOTE%.
coordinatorStaff	object		Yes	Displays staff object for the staff member that was the coordinator staff for this appointment. The coordinator staff's schedule is not blocked. For more info, see Staff API page.
coupon	object			If client enters a coupon while booking through the scheduler, the object of the coupon they entered will display here - for more info, see Coupon API page.
couponId	integer			Provides unique numeric ID that is stored on the coupon object.
createddate	string			Displays as date specified appointment was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
createduser	string			Displays as username of the user who created specified appointment. If client booked appointment from scheduler would display as "WebClient".
customFieldDesc	string			Displays the label and value properties of any scheduler preference field objects that have the mode property set to APPT so that users can inject these into email templates with 1 centralized tag which is %CUSTOM_FIELDS%.
date	string	Yes	Yes	Provides string representation of the date specified appointment is taking place displayed as YYYY-MM-DD. If using startDate, endDate, clientStartDate, and clientEndDate are not filled for some reason, this is used for scheduling purposes.
dateCheckedIn	integer		Yes	Displays as date the client checked in to specified appointment.
dateCompleted	integer			Displays as date specified appointment was completed.
dateStarted	integer			Displays as date specified appointment was marked as substatus of INPROGRESS.
discount	integer			If coupon was applied, this displays as the total dollar value that was taken off the price of the service/class booked for.
endDate	string	Yes	Yes	Provides the date that specified appointment ends with buffer time alloted displayed as YYYY-MM-DD.
endTime	integer	Yes	Yes	Provides the end time of the appointment accounting for any buffer on the reason displayed in military format.
fields	array		Yes	Displays an array of any scheduler field objects that were assigned to specified appointment. For more information, see the scheduler fields API page.
invitationUUId	string			If you invite a client to book with you from the clients menu (selecting a client and clicking to send email) and in the invitation template that you send out you have the tag %BOOK_INVITATION_URL%, then when the client clicks the link after receiving the invitation they will be directed to a scheduling landing page with the invitationUUId attached at the end of it. If the client books, we set the invitationUUId from the invitation sent out to the appointment object. This allows us to map the lifecycle of an invitation campaign as shown under Messaging > Monitor Campaigns so we can know if an invitation that was sent out resulted in a booked appointment
jobRequisitionId	integer		Yes	Provides unique numeric ID of specified appointment's job requisition number.
location	object	Yes	Yes	Displays the location object assigned to specified appointment - for more info, see Locations API page.
locationGroup	object		Yes	If you assign the appointment to a specific location group, then this would be the object of that location group - for more info, see Groups API page.
locationSuperGroup	object		Yes	If you assign the location group of specified appointment to a specific location super group, then this would be the object of that location super group.
modifieddate	integer			Displays as date specified appointment was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
modifieduser	string			Displays as username of user who last modified specified appointment. If client on web scheduler was last to modify then it would be displayed as "WebClient".
noPrefSelected	boolean		Yes	Indicates whether or not no preference has been selected for specified appointment.
noShowReason	string			Displays as reason given for a no show.
note	string		Yes	Displays as note added to appointment profile in default comments field.
packageSoldId	integer		Yes	Displays as unique numerical ID of package used to redeem appointment against.
price	string		Yes	Displays as price set for specified appointment after adjusting for any coupons that may have been used.
reason	object		Yes	Displays the reason object connected to specified appointment - for more info, see Services API page.
reasonGroup	object		Yes	If you assign the reason of specified appointment to a specific reason group, then this would be the object of that reason group - for more info, see Groups API page.
recall	object			If a recall campaign has been set up that impacts this appointment, then the object of the recall campaign that the appointment is a part of shows here.
recallDate	integer			Displays as goal date for appointment's recall appointment as determined by the recall object that the appointment is set to. Shows as milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
recallStatus	string			Displays as status of recall of specified appointment if applicable.
recurringAppointmentId	integer			If appointment is part of a repeating appointment series, then this provides unique numerical ID of repeating appointment series.
remindClientSmsHours	integer		Yes	Displays the number of hours before the appointment that an SMS reminder will be sent to the client.
remindStaffSmsHours	integer		Yes	Displays the number of hours before the appointment that an SMS reminder will be sent to the staff.
resource	object		Yes	Displays any resource object connected to specified appointment - for more info, see Resources API page.
seats	integer		Yes	Provides number of seats for specified appointment. Only applicable for reasonType of CLASS where if this number is greater than 1 it would take up as many attendees slots as this number indicates in the class schedule.
sendConfirmationToClient	boolean		Yes	Indicates whether or not a confirmation email should be sent to client on recurring appointment POST or PUT. If set to TRUE, then when specified appointment is created or changed the confirmation will get sent out.
sendConfirmationToStaff	boolean		Yes	Indicates whether or not a confirmation email should be sent to staff on recurring appointment POST or PUT. If set to TRUE, then when specified appointment is created or changed the confirmation will get sent out.
staff	object	Yes	Yes	Displays the staff object for staff member connected to specified appointment - for more info, see Staff API page.
staffReminderHours	integer		Yes	Displays the number of hours before the appointment that an email reminder will be sent to the staff.
staffRescheduleCount	integer			Displays the number of times staf has rescheduled specified appointment.
startDate	string	Yes	Yes	Provides the date specified appointment starts with buffer displayed as YYYY-MM-DD.
startTime	integer	Yes	Yes	Provides the time specified appointment starts displayed in military format.
status	string		Yes	Displays the status of specified appointment. Has acceptable values PENDING, OPEN, NO_SHOW, COMPLETED, CANCELLED, DELETED.
subStatus	string		Yes	Displays the substatus of specified appointment. Substatuses can be customized on Business and Enterprise level accounts, but default substatus values include: PENDING, PENDING_CONFIRMATION, PENDING_WAITLIST, OPEN, CONFIRMED, CHECKEDIN, INPROGRESS, COMPLETED, NO_SHOW, CANCELLED, DELETED.
transactionFee	string			Displays as fee added to transaction added for specified appointment.
waitListId	integer		Yes	If appointment was created by claiming a seat from a waitlist registration, this provides the unique numerical id of the waitlist registration the appointment was claimed from. To create an appointment for a client that is already on a waitlist, you will want to set the waitListId property on the appointment object to that on the waitlist object from which you are creating the new appointment. This will cause the status property on that waitlist object to be set to BOOKED.

To add an appointment to the TimeTap database, you'll need to POST a filled out Appointment JSON object to the "/appointments" endpoint appended to one of the URI prefixes listed on the Introduction page.

A general outline of the steps goes as follows:

Model the Appointment JSON object in your chosen language/platform
Fill in the required values (listed below)
Convert model object to JSON format
Send filled-in Appointment JSON object via POST request to "/appointments" endpoint

A successful POST will receive a response Appointment JSON object mirroring the object you posted. An unsuccessful POST will receive standard HTML error codes.

For more information on adding appointments via the appointments API, see our Webhooks guide.

Please note: for date and time properties, you do not need to do time zone conversion between the client and the staff. Pass the dates and times as you want them set in the staff's time zone and the backend will take care of converting them for the client's timezone in the messages that are sent to the client

Properties/Objects	Required	Type	Details
businessId	true	number	This is generally your API key.
location	true	object	Must include at least the locationId as part of the object passed.
locationGroup	false	object	Must include at least the groupId as part of the object passed.
staff	true	object	Must include at least the professionalId as part of the object passed.
reason	true	object	Must include at least the reasonId as part of the object passed.
reasonGroup	false	object	Must include at least the groupId as part of the object passed.
client	false	object	Must include at least the clientId as part of the object passed.
fields	false	array of objects	In the process of saving the appointment you can make a call to GET schedulerFieldList/reason/{reasonId} passing the id of the selected reason. The returned array will have a list of all fields that are compatible with the reason selected in the booking process. If you loop through those fields, any field objects whose "mode" property is set to "APPT" (meaning appointment fields) and not assigned to "CLIENT" can be passed into this fields array property as the appointment's custom fields. The objects that fill the array need to have the schedulerPreferenceFieldDefnId property filled in, the value filled in, as well as the businessId.
clientStartDate	true	string	This is the start date of the appointment for the client. Should be formatted as YYYY-MM-DD.
clientEndDate	true	string	This should be set to the end date of the appointment for the client. Most of the time this is the same as the clientStartDate, but if the appointment eclipses midnight and ends on a different date, you would need to pass the different date in this field. Should be formatted as YYYY-MM-DD.
startDate	true	string	This is the start date of the appointment for the staff. It is possible (with buffers on services) that the appointment blocks off a different range of dates and times for the staff than the client. For instance, an appointment is an hour long in duration but has a 30 minute buffer before. If the appointment starts at 12:15am on June 1st, 2018 for the client, then for the staff it would start at 11:45pm on May 31st, 2018. While the clientStartDate would get passed as 2018-06-01, the startDate should get passed as 2018-05-31.
endDate	true	string	This is the end date of the appointment for the staff with similar possibilities to the startDate line item listed above. For instance, an appointment is an hour long in duration but has a 30 minute buffer after. If the appointment starts at 10:45pm on May 31st, 2018 for the client, then for the client it would end at 11:45pm on May 31st, but for the staff it would end at 12:15am on June 1st 2018. While the clientEndDate would get passed as 2018-05-31, the startDate should get passed as 2018-06-01.
clientStartTime	true	number	This is the start time of the appointment for the client. Should have military time format. Formatting examples: an appointment that starts at 12:15am should be passed as 15 an appointment that starts at 11:30am should be passed as 1130 an appointment that starts at 2:45pm should be passed as 1445 and so on
clientEndTime	true	number	This is the end time of the appointment for the client. Generally you use the duration of the selected service (i.e. reason) to determine this based off of the clientStartTime. Should be formatted as YYYY-MM-DD.
startTime	true	number	This is the start time of the appointment for the staff. Should be formatted the same as the clientStartTime defined above. Generally this is calculated based on the bufferBefore property set on the selected service/reason. So if an appointment is set to start for the client at 2:00pm but the selected service has a 15 minute bufferBefore value set then the startTime should get set as 1345 (1:45pm). Please note: You can create an appointment by passing the appointment object with this value set to null. If you do this, the backend will automatically set the property based off the selected reason's bufferBefore value. If the bufferBefore value is null, then the startTime will be set to the same value as the clientStartTime.
endTime	true	number	This is the end time of the appointment for the staff. Should be formatted the same as the clientStartTime defined above. Generally this is calculated based on the bufferAfter property set on the selected service/reason. So if an appointment is set to end for the client at 2:00pm but the selected service has a 15 minute bufferAfter value set then the endTime should get set as 1415 (2:15pm). Please note: You can create an appointment by passing the appointment object with this value set to null. If you do this, the backend will automatically set the property based off the selected reason's bufferAfter value. If the bufferAfter value is null, then the endTime will be set to the same value as the clientEndTime.
classScheduleId	true (if selected reason is of reasonType class)	number	If you are adding an appointment for a class session, you have to pass the classScheduleId of the class session you are wanting to put the client into. It is not enough to just pass the date and time of the session to map the client to that session as there could be multiple sessions scheduled for the same date and time at the same location with the same staff for the same reason.
clientReminderHours	true	number	This is the number of hours before the appointment that you want the reminder email to be sent to the client. If you do not want to send an email reminder to the client, set the value to 0. Otherwise, set it to the hour value. Formatting examples If you want the email to go out 12 hours before the start time of the appointment, set the value to 12 If you want the email to go out 1 day before the start time of the appointment, set the value to 24 (1 day = 24 hours) If you want the email to go out 1.5 days before the start time of the appointment, set the value to 36
staffReminderHours	true	number	This is the number of hours before the appointment that you want the reminder email to be sent to the staff. Same formatting rules apply here as apply to the clientReminderHours.
remindClientSmsHrs	true	number	This is the number of hours before the appointment that you want the reminder text message to be sent to the client. Same formatting rules apply here as apply to the clientReminderHours.
remindStaffSmsHrs	true	number	This is the number of hours before the appointment that you want the reminder text message to be sent to the staff. Same formatting rules apply here as apply to the clientReminderHours.
sendConfirmationToClient	true	boolean	If you want the New Appointment by Staff email to send out the the client upon saving the appointment, set this to true. Otherwise, set it to false.
sendConfirmationToStaff	true	boolean	If you want the New Appointment email to send out to the staff upon saving the appointment, set this to true. Otherwise set it to false.
status	true	string	Accepted values: OPEN PENDING_CONFIRMATION (if need to get staff confirmation that they can take the appointment before it is set to OPEN)
pendingConfirmation	false	boolean	If going through the pending confirmation process for an appointment, set this value to true. Otherwise, no need to pass.
resource	false	object	If you have added resources to your account to use, you can make a call while creating the appointment to GET resource/location/{locationId}/reason/{reasonId} Where you pass the locationId of the selected location from the location object and the reasonId of the selected reason from the reason object. This is mostly for service based appointments because class based appointments will have the resource tied to the class session already. You'll receive a list of resources associated with the location and reason as a return from that GET call and if you want to tie one to the appointment you can set the resource property of the appointment to that selected resource. Make sure to include at least the resourceId in the passed object. To check whether the selected resource is available during the date and time that you are trying to put it in for, make a call to GET resource/{resourceId}/isBusy/{apptDate}/{startTime}/{endTime} Pass the resourceId of the selected resource, the date of the appointment (formatted as YYYY-MM-DD), the start time of the appointment (either the clientStartTime or startTime, whichever is earlier) and the end time of the appointment (either the clientEndTime or the endTime, whichever is later). That will return false if the resource is available and true if the resource is busy (meaning it is already in use for another appointment or a class session).
packageSoldId	false	number	Set to value of selected package that you would like to use for the appointment.

To use our round robin logic in order to assign staff to an appointment as it gets created, you will need to make a call to the POST /appointments endpoint with a few modifications. First, in the body/payload of the POST /appointments call, you will need to pass a staff object that has the professionalId object set to null. You will also need to pass a property called "calTimeSlot" in the body/payload, which will be filled with one of the timeslots returned in the timeslots array property that gets returned from the GET /availability/{YYYY}/{MM}/{DD} call. The timeslot that that you fill in the calTimeSlot property will contain an array called units, which will contain all of the various professionalId options and gets used to assign the staff using the round robin logic.

So that you can see what I am referencing here in terms of formatting, I have included a sample JSON payload for the POST /appointments API call:

Code Block

language	java
title	Sample payload from POST /appointments call
linenumbers	true
collapse	true

{
  "businessId": 19663,
  "client": {Client object for client of appointment - for more info, see Clients API page},
  "status": "OPEN",
  "clientStartTime": 1230,
  "startDate": "2022-03-28",
  "clientStartDate": "2022-03-28",
  "endDate": "2022-03-28",
  "clientEndDate": "2022-03-28",
  "clientReminderHours": 24,
  "remindClientSmsHrs": 1,
  "staffReminderHours": 24,
  "remindStaffSmsHrs": null,
  "locationSuperGroup": null,
  "locationGroup": null,
  "reasonGroup": null,
  "address": null,
  "location": {Location object for location of appointment - for more info, see Locations API page},
  "staff": {
    "professionalId": null
  },
  "reason": {Reason object for service of appointment - for more info, see Services API page},
  "duration": {
    "active": true,
    "durationHours": 1,
    "durationMinutes": 45,
    "duration": 105,
    "price": 5,
    "deposit": null,
    "durationName": "1 hour service",
    "internalName": null,
    "staffRateLevel": null,
    "discountedPrice": 5,
    "originalPrice": null,
    "friendlyTime": "1 Hour 45 Minutes",
    "displayName": "1 hour service",
    "currencyPrefix": "$"
  },
  "geocodeMatch": {
    "internalDisplayName": null,
    "formattedAddress": null
  },
  "apptTZ": "America/New York",
  "classScheduleId": null,
  "recurringSchedule": null,
  "clientEndTime": 1415,
  "startTime": 1230,
  "endTime": 1415,
  "calTimeSlot": {
    "staffStartDate": "2022-03-28",
    "staffEndDate": "2022-03-28",
    "staffStartTime": 1230,
    "staffEndTime": 1415,
    "startTime": 1230,
    "endTime": 1415,
    "clientStartDate": "2022-03-28",
    "clientEndDate": "2022-03-28",
    "clientStartTime": 1230,
    "clientEndTime": 1415,
    "timeString": "12:30 PM - 2:15 PM (America/New York) (Available Staff: Lucy Barber 72, Staff 1 Internal Name)",
    "units": [
      {
        "professionalId": 42880,
        "locationId": 39939,
        "reasonId": 95569,
        "resourceId": null,
        "bundleResourceIdList": null,
        "tandemStaffIdList": null,
        "roundRobin": false
      },
      {
        "professionalId": 42879,
        "locationId": 39939,
        "reasonId": 95569,
        "resourceId": null,
        "bundleResourceIdList": null,
        "tandemStaffIdList": null,
        "roundRobin": false
      }
    ],
    "staffStartDateTimeUTC": 1648485000000,
    "staffEndDateTimeUTC": 1648491300000,
    "selected": true
  },
  "reasonDesc": "1 hour service",
  "price": 5,
  "fields": [Fields object for scheduler fields of appointment object - for more info, see Scheduler Fields API page]
}

Versions Compared

Old Version 159

New Version 160

Key

Appointments API Endpoints

Appointments API Parameters

Appointment API Request Body/Payloads

Appointments API Responses

Appointments Object Values

Guide for Adding New Appointments

Creating Appointments Using Round Robin Logic