Recurring Appointments

The Recurring Appointments API is used to access, create, and modify any recurring appointments on your business' account. The Recurring Appointments API is separate from the Recurring Class Schedule API, since TimeTap treats appointment time slots differently than class time slots as unlike in the case of classes only one customer can book each appointment. It is also separate from the Appointments API, as recurring appointments are set to repeat on a weekly or monthly basis.

Whenever you create a appointment object using a recurringcappointment update, that object will have the recurringAppointmentId property filled. On the TimeTap site these appointments are usually referred to as 'repeating appointments'.

On this page




Recurring Appointments API Endpoints

These are the endpoints that are available under the /recurringappointments path, which shows any appointments you have set up to repeat on a weekly or monthly basis.

Endpoint

Description

GET /recurringappointments/{recurringAppointmentId}

Returns a JSON object for specified recurring appointment series.

POST /recurringappointments

Creates a new recurringappointments object on an account. 

Request body/payload: Must pass a recurringappointments object in the request body/payload.

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

POST /recurringappointments/get/dates

Returns an array of dates in string format that match recurring appointment frequency.

Request body/payload: Must pass a recurringappointments object in the request body/payload.

PUT /recurringappointments/{recurringAppointmentId}

Updates an existing recurringappointments object. If you want to cancel a recurring appointment series you would use this endpoint to set the status property to "Cancelled".

Request body/payload: Must pass a recurringappointments object with the desired changes made in the request body/payload.

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

PUT /recurringappointments/{recurringAppointmentId}/updateByAppt

Updates an existing recurringappointments object by comparing the original appointment to the updatedAppt passed in the body of the PUT call (see below) to see which fields were updated.

Request body/payload: Must pass a recurringappointments object formatted as such:

{
recurringAppt: recurringAppointment object to be updated
updatedAppt: appointment that got updated
}




Recurring Appointments API Parameters

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

Parameters

TypeEndpoints to be used with

Description

dateSelected

stringPUT /recurrringappointments/{recurringAppointmentId}, PUT /recurringappointments/{recurringAppointmentId}/updateByAppt Should be set to the start date of the recurring appointment series you are editing formatted as YYYY-MM-DD.
resetStartDayboolean

PUT /recurrringappointments/{recurringAppointmentId}, PUT /recurringappointments/{recurringAppointmentId}/updateByAppt

Flag for whether or not to send invites to waitlist registrants. If true then will see if anybody is waitlisted for the timeslots that are getting cancelled and will invite them automatically.
sendWaitListInvitesboolean

PUT /recurrringappointments/{recurringAppointmentId}, PUT /recurringappointments/{recurringAppointmentId}/updateByAppt

Flag for whether or not to send invites to waitlist registrants. If true then will see if anybody is waitlisted for the timeslots that are getting cancelled and will invite them automatically.




Recurring Appointments API Request Body/Payloads

The objects below represent the minimum viable objects to pass that are needed to create or update a recurringappointments 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 /recurringappointments
{
    "businessId": "43111",
    "classScheduleList": null,
    "client": {Client object for client of recurring appointment - for more info, see Clients API page},
    "clientEndTime": 1130,
    "clientId": 4932331,
    "clientReminderHours": 24,
    "clientStartTime": 1100,
    "coordinatorStaff": {Staff object for coordinator staff of recurring appointment - for more info, see Staff API page},
    "dates": ["2019-02-12", "2019-02-14", "2019-02-19", "2019-02-21", "2019-02-26"],
    "discount": null,
    "endDate": "2019-02-26",
    "endTime": null,
    "everyXMonths": "0",
    "everyXWeeks": "1",
    "fields": [{Fields object for scheduler fields of recurring appointment - for more info, see Scheduler Fields API page}],
    "fri": false,
    "location": {Location object for location of recurring appointment - for more info, see Locations API page},
    "locationGroup": null,
    "locationId": 81181,
    "locationSuperGroup": null,
    "mon": false,
    "note": "",
    "price": 10,
    "reason": {Reason object for reason of recurring appointment - for more info, see Services API page},
    "reasonId": 255109,
    "remindClientSmsHrs": 1,
    "remindStaffSmsHrs": 0,
    "resource": {Resource object for resource of recurring appointment - for more info, see Resource API page},
    "sat": false,
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of recurring appointment - for more info, see Staff API page},
    "staffId": 298660,
    "staffReminderHours": 24,
    "startDate": "2019-02-12",
    "startTime": null,
    "sun": false,
    "tax1Amount": null,
    "thu": true,
    "timeSlotList": null,
    "tue": true,
    "wed": false
}
PUT /recurringappointments
{
    "businessId": "43111",
    "cancelReson": null,
    "changeReason": null,
    "classScheduleId": null,
    "classScheduleList": null,
    "client": {Client object for client of recurring appointment - for more info, see Clients API page},
    "clientEndTime": 1135,
    "clientId": 4932331,
    "clientReminderHours": 24,
    "clientStartTime": 1105,
    "coordinatorStaff": {Staff object for coordinator staff of recurring appointment - for more info, see Staff API page},
    "createdBy": null,
    "dates": ["2019-02-12", "2019-02-14", "2019-02-19", "2019-02-21", "2019-02-26"],
    "discount": null,
    "endDate": "2019-02-26",
    "endTime": 1135,
    "everyXMonths": 0,
    "everyXWeeks": 1,
    "fields": [{Fields object for scheduler fields of recurring appointment - for more info, see Scheduler Fields API page}],
    "fri": false,
    "getSendConfirmationToClient": null,
    "location": {Location object for location of recurring appointment - for more info, see Locations API page},
    "locationGroup": null,
    "locationId": 81181,
    "locationSuperGroup": null,
    "modifiedBy": null,
    "mon": false,
    "note": "",
    "price": 10,
    "reason": {Reason object for reason of recurring appointment - for more info, see Services API page},
    "reasonId": 255109,
    "recurringAppointmentId": 279024,
    "recurringSchedule": null,
    "remindClientSmsHrs": 1,
    "remindStaffSmsHrs": 0,
    "repeatStaffIds": null,
    "resource": {Resource object for resource of recurring appointment - for more info, see Resource API page},
    "sat": false,
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of recurring appointment - for more info, see Staff API page},
    "staffId": 298660,
    "staffReminderHours": 24,
    "startDate": "2019-02-12",
    "startTime": 1105,
    "sun": false,
    "tax1Amount": null,
    "thu": true,
    "timeSlotList": null,
    "tue": true,
    "wed": false
}




Recurring Appointments API Responses


GET /recurringappointments/{recurringAppointmentId}
{
    "businessId": 43111,
    "cancelReason": null,
    "changeReason": null,
    "classScheduleList": null,
    "client": {Clients object for client of recurring appointment - see Clients API page},
    "clientEndTime": 900,
    "clientId": 4761823,
    "clientReminderHours": 24,
    "clientStartTime": 800,
    "coordinatorStaff": {Staff object for coordinator staff of recurring appointment - see Staff API page},
    "customFieldData": [],
    "discount": null,
    "endDate": null,
    "endTime": 900,
    "everyXMonths": 0,
    "everyXWeeks": 1,
    "fields": [{Fields object for scheduler fields of recurring appointment  -see Scheduler Fields API page}],
    "fri": false,
    "location": {Location object for location of recurring appointment - see Locations API page},
    "locationGroup": {Groups object for location group of recurring appointment - see Groups API page},
    "locationId": 81181,
    "locationSuperGroup": null,
    "mon": true,
    "note": "",
    "reason": {Reason object for service of recurring appointment - see Services API page},
    "reasonId": 240094,
    "recurringAppointmentId": 145055,
    "remindClientSmsHours": 1,
    "remindStaffSmsHours": 0,
    "resource": null,
    "sat": false,
    "seats": 10,
    "staff": {Staff object for staff of recurring appointment - see Staff API page},
    "staffId": 77961,
    "staffReminderHours": 24,
    "startDate": "2018-09-03",
    "startTime": 800,
    "status": "Open",
    "sun": false,
    "thu": true,
    "timeSlotList": null,
    "tue": false,
    "wed": true
}
POST /recurringappointments
[{
    "businessId": 43111,
    "cancelReason": null,
    "changeReason": null,
    "classScheduleList": null,
    "client": {Clients object for client of recurring appointment - see Clients API page},
    "clientEndTime": 1100,
    "clientId": 4761823,
    "clientReminderHours": 0,
    "clientStartTime": 1000,
    "coordinatorStaff": {Staff object for coordinator staff of recurring appointment - see Staff API page},
    "customFieldData": null,
    "discount": null,
    "endDate": null,
    "endTime": 1100,
    "everyXMonths": 0,
    "everyXWeeks": 1,
    "fields": [{Fields object for scheduler fields of recurring appointment - see Scheduler Fields API page}],
    "fri": false,
    "location": {Location object for location of recurring appointment - see locations API page},
    "locationGroup": {Groups object for location group of recurring appointment - see Groups API page},
    "locationId": 81353,
    "locationSuperGroup": null,
    "mon": false,
    "note": "",
    "reason": {Reason object for service of recurring appointment - see Services API page},
    "reasonId": 240094,
    "recurringAppointmentId": 148121,
    "remindClientSmsHours": 1,
    "remindStaffSmsHours": 0,
    "resource": null,
    "sat": false,
    "seats": 10,
    "staff": {Staff object for staff of recurring appointment - see Staff API page},
    "staffId": 80891,
    "staffReminderHours": 24,
    "startDate": "2018-08-16",
    "startTime": 1000,
    "status": "Open",
    "sun": false,
    "thu": true,
    "timeSlotList": null,
    "tue": false,
    "wed": false
}]
PUT /recurringappointments/{recurringAppointmentId}
{
    "businessId": 43111,
    "cancelReason": null,
    "changeReason": null,
    "classScheduleList": null,
    "client": {Clients object for client of recurring appointment - see Clients API page},
    "clientEndTime": 905,
    "clientId": 4761823,
    "clientReminderHours": 24,
    "clientStartTime": 800,
    "coordinatorStaff": {Staff object for coordinator staff of recurring appointment - see Staff API page},
    "customFieldData": [],
    "discount": null,
    "endDate": "2019-05-30",
    "endTime": 905,
    "everyXMonths": 0,
    "everyXWeeks": 1,
    "fields": [{Fields object for scheduler fields of recurring appointment - see Scheduler Fields API page}],
    "fri": false,
    "location": {Location object for location of recurring appointment - see Locations API page},
    "locationGroup": {Groups object for location group of recurring appointment - see Groups API page},
    "locationId": 81181,
    "locationSuperGroup": null,
    "mon": true,
    "note": "",
    "reason": {Reason object for service of recurring appointment - see Services API page},
    "reasonId": 240094,
    "recurringAppointmentId": 145055,
    "remindClientSmsHours": 1,
    "remindStaffSmsHours": 0,
    "resource": null,
    "sat": false,
    "seats": 10,
    "staff": {Staff object for staff of recurring appointment - see Staff API page},
    "staffId": 77961,
    "staffReminderHours": 24,
    "startDate": "2018-09-03",
    "startTime": 800,
    "status": "Open",
    "sun": false,
    "thu": true,
    "timeSlotList": null,
    "tue": false,
    "wed": true
}
PUT /recurringappointments/{recurringAppointmentId}/updateByAppt
{
    "additionalStaffIdList": [],
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "cancelReason": "",
    "changeReason": "",
    "classScheduleList": null,
    "client": {Clients object for client of recurring appointment - see Clients API page},
    "clientEndTime": 1230,
    "clientId": 4922146,
    "clientReminderHours": 24,
    "clientStartTime": 1200,
    "color": null,
    "coordinatorStaff": {Staff object for coordinator staff of recurring appointment - see Staff API page},
    "createdBy": null,
    "customFieldData": [],
    "dateCreated": null,
    "dateModified": null,
    "dates": null,
    "discount": null,
    "endDate": "2020-10-06",
    "endTime": 1230,
    "everyXMonths": 0,
    "everyXWeeks": 1,
    "fields": [{Fields object for scheduler fields of recurring appointment - see Scheduler Fields API page}],
    "fri": false,
    "getSendConfirmationToClient": null,
    "location": {Location object for location of recurring appointment - see Locations API page},
    "locationGroup": null,
    "locationId": 81181,
    "locationSuperGroup": null,
    "modifiedBy": null,
    "mon": false,
    "note": "",
    "price": 10,
    "reason": {Reason object for service of recurring appointment - see Services API page},
    "reasonId": 255109,
    "recurringAppointmentId": 428225,
    "recurringSchedule": null,
    "remindClientSmsHrs": 24,
    "remindStaffSmsHrs": 0,
    "repeatStaffIds": null,
    "resource": null,
    "sat": false,
    "seats": 1,
    "sendConfirmationToClient": null,
    "sendConfirmationToStaff": null,
    "staff": {Staff object for staff of recurring appointment - see Staff API page},
    "staffId": 302120,
    "staffReminderHours": 24,
    "startDate": "2020-09-15",
    "startTime": 1145,
    "status": "Open",
    "sun": false,
    "tax1Amount": null,
    "thu": false,
    "timeSlotList": null,
    "tue": true,
    "wed": false
}




Recurring Appointments Object Values

Property nameTypeRequiredWritableDescription
businessIdintegerYes
Provides unique numeric ID of the business to which the specified appointment belongs.
cancelReasonstring
YesDisplays any reason given for cancelling specified appointment.
changeReasonstring
YesDisplays any reason given for changing specified appointment.
classScheduleListarray
YesDisplays an array of objects representing the available class schedules when adding a recurring appointment of reasonType CLASS.
clientobject
YesDisplays the object of client who is connected to specified appointment - for more info, see Clients API page.
clientEndTimeinteger
YesDisplays as time specified appointment is set to end displayed in military format.
clientIdinteger

Provides unique numeric ID of client who is connected to specified appointment.
clientReminderHoursinteger
YesDisplays the number of hours before the appointment that an email reminder will be sent to the client.
clientStartTimeinteger
YesDisplays as time specified appointment is set to begin displayed in military format.
coordinatorStaffobject
YesDisplays staff object for the staff member that was the coordinator staff for specified appointment. The coordinator staff's schedule is not blocked. For more info, see Staff API page.
customFieldDatastring

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%
discountinteger
YesThis displays as the total dollar value that was taken off the price of specified appointment.
endDatestring
YesProvides a string representation of the date the recurring class session ends written as YYYY-MM-DD; if set to null then the schedule will repeat indefinitely. 
endTimeintegerYesYesProvides the time specified class ends, displayed in military format. 
everyXMonthsinteger
YesDisplays as number of months class schedule is set to recurr on. (Required if type is set to "M")
everyXWeeksinteger
YesDisplays as number of weeks class schedule is set to recurr on. (Required if type is set to "W")
fieldsarray
YesDisplays an array of any custom field objects you have added during the class schedule setup - for more info, see Scheduler Field API page.
friboolean

Indicates whether or not the recurring class schedule is set to repeat on Fridays.
locationobjectYesYes

Displays the location object assigned to the specified class session - for more info, see Locations API page. 

locationGroupobject
YesIf you assign the class session to a specific location group, then this would be the object of that location group - for more info, see Groups API page.

locationSuperGroup

object
YesIf you assign the class session to a specific location super group, then this would be the object of that location super group.
monboolean

Indicates whether or not the recurring class schedule is set to repeat on Mondays.
notestring
YesDisplays as note added to appointment profile in default comments field.
reasonobjectYesYesDisplays the reason object assigned to the specified class session - for more info, see Services API page. 
reasonIdinteger

Provides unique numeric ID for reason of specified appointment.

recurringAppointmentId

integer

Yes, on PUT calls

Provides a unique numeric ID for specified recurring appointment.

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 the recurring appointment - for more info, see Resources API page.
satboolean

Indicates whether or not the recurring appointment is set to repeat on Saturdays.
seatsinteger
YesProvides number of seats for specified recurring appointment.
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 assigned to specified recurring appointment - for more, see Staff API page. 
staffIdinteger

Provides unique numeric ID of the staff assigned to specified recurring appointment.
staffReminderHoursinteger
YesDisplays the number of hours before the appointment that an email reminder will be sent to the staff.
startDatestringYesYesProvides a string representation of the date the recurring appointment starts written as YYYY-MM-DD. 
startTimeintegerYesYesProvides the time the recurring appointment begins, displayed in military format. 
statusstring
YesDisplays the status of specified recurring appointment. Possible values include Open, Closed, or Cancelled.
sunboolean

Indicates whether or not the recurring appointment is set to repeat on Sundays.
thuboolean

Indicates whether or not the recurring appointment is set to repeat on Thursdays.
timeSlotListarray

Displays an array of objects representing the available timeslots when adding a recurring appointment of reasonType CLASS. The timeslots you select get passed in the timeSlotList array and will return on subsequent GET calls.
tueboolean

Indicates whether or not the recurring appointment is set to repeat on Tuesdays.
wedboolean

Indicates whether or not the recurring appointment is set to repeat on Wednesdays.