Appointments

The Appointments API is used to access, create, and modify the appointments on your business' account. The Appointments API is connected to the Locations, StaffServices, 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.



On this page




Appointments API Endpoints

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/reportReturns all appointment objects on an account in array format.
GET /appointmentList/reportWithCountReturns 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

{
    "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

{
    "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

{
    "reason": "",
    "subStatus": "COMPLETED"
}
GET/POST /appointmentList/reportCountReturns number of appointments based on the parameters that get passed. Acceptable parameters can be found in the Appointments API Parameters section.
GET/POST /appointmentList/reportCountsByStatusReturns 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. 




Appointments API Parameters

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

TypeEndpoints to be used with

Description

calendarIdListinteger 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.
classScheduleIdinteger

GET /appointments/report

Should be set as the unique numeric ID of client of appointment to be returned following the API call.
classScheduleIdListinteger 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.
clientIdintegerGET /appointments/reportShould be set as the ID of client of appointment to be returned following the API call.
clientIdListinteger 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.
couponIdListinteger 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.
endDatestring

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. 
excludeTimeOffboolean

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.
locationIdListinteger 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.
locationGroupIdListinteger 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.
onlyTimeOffinteger

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_fieldstring

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_modestring

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.
overridebooleanPOST /appointmentsCan 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.
packageSoldIdListinteger 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.
pageNumberinteger

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.
pageSizeinteger

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.

reasonIdListinteger 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).
recurringApptIdListinteger 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.
resourceIdListinteger 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.
showApptTzboolean

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. 
showClientFormsboolean

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.
staffIdListinteger 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.
startDatestring

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. 
statusListstring 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. 
uninvoicedboolean

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.
waitListIdsinteger 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.




Appointment API Request Body/Payloads

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.

POST /appointments
{
    "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"
}
PUT /appointments
{
    "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"
}




Appointments API Responses

GET /appointmentList/report
{
    "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
}
GET /appointmentList/reportWithCount
{
    "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}
GET /appointments/{appointmentId}
{
    "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
}
GET /appointments/resource/{resourceId}/{resourceId}/{statusList}
[{
    "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
}]
GET /appointments/recurringappointments/{recurringappointmentId}
{
    "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
}
POST /appointments
{
    "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
}
PUT /appointments/{appointmentId}
{
    "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
}
PUT /appointments/{appointmentId}/noshow
{
    "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
}
GET/POST /appointmentList/reportCountsByStatus
{
    "count": 0,
    "objectName": "Class, no sessions, staff 7",
    "objectType": "REASON",
    "objectId": 95576,
    "'status": "OPEN"
}




Appointments Object Values

Property nameTypeRequiredWritableDescription
additionalStaffIdListarray
YesDisplays staffIds for any additional staff members you add to the appointment so they cannot otherwise be booked for this time slot. 
addressstring
YesDisplays the address entered during appointment creation f appointment is set to a location of locationType VARIABLE.
appointmentDateTimeClientstring

Displays the date and time of the appointment as the client sees them.
appointmentDateTimeStaffstring

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.
blockStaffIdListarray
YesDisplays 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.
blockedStaffListarray
YesDisplays full staff objects for any additional staff members you have added in the blockStaffIdList or additionalStaffIdList.
businessIdintegerYes
Provides unique numerical ID for the business that offers specified appointment. 
calendarIdintegerYes
Provides unique numerical ID of specified appointment. 
cancelReasonstring

Displays any reason given for cancelling specified appointment.
cancelUserstring

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.
changeReasonstring

Displays any reason given for changing specified appointment.
classScheduleIdinteger
YesIf specified appointment is an instance of a class schedule, this field will contain the unique numerical ID for that class schedule.
clientobject
YesDisplays the object of client who is connected to specified appointment - for more info, see Clients API page.
clientConfirmDateinteger
YesDisplays the date in milliseconds elapsed since January 1 1970 UTC format that client was marked as confirmed for appointment.
clientConfirmedboolean
YesIndicates whether or not the client has confirmed the appointment.
clientEndDatestring
YesDisplays as date specified appointment is set to end without buffer displayed as YYYY-MM-DD.
clientEndTimeinteger
YesDisplays as time specified appointment is set to end without buffer displayed in military format.
clientReminderHoursinteger
YesDisplays the number of hours before the appointment that an email reminder will be sent to the client.
clientRescheduleCountinteger

Displays the number of times client has rescheduled specified appointment.
clientStartDatestring
YesDisplays as date specified appointment is set to begin without buffer displayed as YYYY-MM-DD.
clientStartTimeinteger
YesDisplays as time specified appointment is set to begin without buffer displayed in military format.
colorstring
YesDisplays any color chosen to override specified appointment on the backoffice calendar.
completedReasonstring

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%.
coordinatorStaffobject
YesDisplays 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.
couponobject

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.
couponIdinteger

Provides unique numeric ID that is stored on the coupon object.
createddatestring

Displays as date specified appointment was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
createduserstring

Displays as username of the user who created specified appointment. If client booked appointment from scheduler would display as "WebClient". 
customFieldDescstring

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%. 
datestringYesYesProvides 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.
dateCheckedIninteger
YesDisplays as date the client checked in to specified appointment.
dateCompletedinteger

Displays as date specified appointment was completed.
dateStartedinteger

Displays as date specified appointment was marked as substatus of INPROGRESS.
discountinteger

If coupon was applied, this displays as the total dollar value that was taken off the price of the service/class booked for.
endDatestringYesYesProvides the date that specified appointment ends with buffer time alloted displayed as YYYY-MM-DD. 
endTimeintegerYesYesProvides the end time of the appointment accounting for any buffer on the reason displayed in military format.
fieldsarray
YesDisplays an array of any scheduler field objects that were assigned to specified appointment. For more information, see the scheduler fields API page.
invitationUUIdstring

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
jobRequisitionIdinteger
YesProvides unique numeric ID of specified appointment's job requisition number.
locationobjectYesYesDisplays the location object assigned to specified appointment - for more info, see Locations API page.
locationGroupobject
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.

locationSuperGroupobject
YesIf 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.
modifieddateinteger

Displays as date specified appointment was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
modifieduserstring

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".
noPrefSelectedboolean
YesIndicates whether or not no preference has been selected for specified appointment.
noShowReasonstring

Displays as reason given for a no show.
notestring
YesDisplays as note added to appointment profile in default comments field.
packageSoldIdinteger
YesDisplays as unique numerical ID of package used to redeem appointment against.
pricestring
YesDisplays as price set for specified appointment after adjusting for any coupons that may have been used.
reasonobject
YesDisplays the reason object connected to specified appointment - for more info, see Services API page.
reasonGroupobject
YesIf 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.
recallobject

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.
recallDateinteger

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.
recallStatusstring

Displays as status of recall of specified appointment if applicable.
recurringAppointmentIdinteger

If appointment is part of a repeating appointment series, then this provides unique numerical ID of repeating appointment series.
remindClientSmsHoursinteger
YesDisplays the number of hours before the appointment that an SMS reminder will be sent to the client.
remindStaffSmsHoursinteger
YesDisplays the number of hours before the appointment that an SMS reminder will be sent to the staff.
resourceobject
YesDisplays any resource object connected to specified appointment - for more info, see Resources API page.
seatsinteger
YesProvides 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.
sendConfirmationToClientboolean
YesIndicates 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.
sendConfirmationToStaffboolean
YesIndicates 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.
staffobjectYesYesDisplays the staff object for staff member connected to specified appointment - for more info, see Staff API page.
staffReminderHoursinteger
YesDisplays the number of hours before the appointment that an email reminder will be sent to the staff.
staffRescheduleCountinteger

Displays the number of times staf has rescheduled specified appointment.
startDatestringYesYesProvides the date specified appointment starts with buffer displayed as YYYY-MM-DD. 
startTimeintegerYesYesProvides the time specified appointment starts displayed in military format.
statusstring
YesDisplays the status of specified appointment. Has acceptable values PENDING, OPEN, NO_SHOW, COMPLETED, CANCELLED, DELETED.
subStatusstring
YesDisplays 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.
transactionFeestring

Displays as fee added to transaction added for specified appointment.
waitListIdinteger
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.




Guide for Adding New Appointments

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

RequiredTypeDetails
businessIdtruenumberThis is generally your API key.
locationtrueobjectMust include at least the locationId as part of the object passed.
locationGroupfalseobjectMust include at least the groupId as part of the object passed.
stafftrueobjectMust include at least the professionalId as part of the object passed.
reasontrueobjectMust include at least the reasonId as part of the object passed.
reasonGroupfalseobjectMust include at least the groupId as part of the object passed.
clientfalseobjectMust include at least the clientId as part of the object passed.
fieldsfalsearray 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.

clientStartDatetruestringThis is the start date of the appointment for the client. Should be formatted as YYYY-MM-DD.
clientEndDatetruestringThis 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.
startDatetruestringThis 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.
endDatetruestringThis 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.
clientStartTimetruenumber

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
clientEndTimetruenumberThis 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.
startTimetruenumber

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.

endTimetruenumber

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.

classScheduleIdtrue (if selected reason is of reasonType class)numberIf 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.
clientReminderHourstruenumber

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
staffReminderHourstruenumberThis 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.
remindClientSmsHrstruenumberThis 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.
remindStaffSmsHrstruenumberThis 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.
sendConfirmationToClienttruebooleanIf 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.
sendConfirmationToStafftruebooleanIf 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.
statustruestring

Accepted values:

  • OPEN
  • PENDING_CONFIRMATION (if need to get staff confirmation that they can take the appointment before it is set to OPEN)
pendingConfirmationfalsebooleanIf going through the pending confirmation process for an appointment, set this value to true. Otherwise, no need to pass.
resourcefalseobject

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).

packageSoldIdfalsenumberSet to value of selected package that you would like to use for the appointment.




Creating Appointments Using Round Robin Logic


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:

Sample payload from POST /appointments call
{
  "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]
}