Waitlist

The Waitlist API is used to access and create the different waitlists and the client registrations on those waitlists on your business' account. The Waitlists API is connected to the Services API, as services will sometimes have a waitlist depending on how many people sign up for it, and is connected to the Staff and Locations APIs, as staff and location objects are both found within the waitlist object. Since waitlists are a way for your clients to sign up for services that are already full and therefore represent a way for you to get more customers, it is crucial for you to familiarize yourself with how to get and create the waitlist registrants on your account.

The purpose of a waitlist is to be able to add clients to a certain list to be notified if a time slot for an appointment that is full has a space open up. For reasonType SERVCE, a client can join a waitlist for an appointment that is not yet full in case the timeslots that are open do not fit his or her schedule. So a client can either have a list of available times OR can be notified of the next available opening. However, for reasonType CLASS a client can only join the waitlist for class sessions that have been filled, and can only select one class session of which to join the waitlist.

On this page

These are the endpoints that are available under the /waitlist path, which lists all the different waitlists and waitlist registrants you have added to your business for scheduling purposes.

Endpoint	Description
GET /waitlist	Returns all waitlist objects on an account in array format.
GET /waitlist/{waitlistId}	Returns a JSON object for specified waitlist registration.
POST /waitlist	Adds a client object to a waitlist. Request body/payload: Must pass a waitlist object in the request body/payload. For these calls, you need to pass a waitlist 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 waitlist object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.
POST /waitlist/cancel/{waitlistId}	Removes specified waitlist registration from a waitlist.

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
clientId	integer	GET /waitlist	Should be set as the ID of client of waitlist to be returned following the GET call.
endDate	string	GET /waitlist	Should be set as the end date of the waitlist to be returned, formatted as YYYY-MM-DD.
locationIdList	integer array	GET /waitlist	Should be set as a comma-separated list of locationIds connected to the waitlists you want returned following the GET call.
order_field	string	GET /waitlist	Should be set as the field that waitlists returned following the GET call should be ordered by.
order_mode	string	GET /waitlist	Should be set as the mode ('asc'ending or 'desc'ending) in which waitlists returned following the GET call should appear.
pageNumber	integer	GET /waitlist	Works with the pageSize parameter to determine how waitlists get returned following the GET call. The pageNumber value represents the number of pages on which the waitlists that get returned appear.
pageSize	integer	GET /waitlist	Works with the pageNumber parameter to determine how waitlists gets returned following the GET call. The pageSize value represents the number of waitlists appearing on each page that gets returned.
reasonIdList	integer array	GET /waitlist	Should be set as a comma-separated list of serviceIds connected to the waitlists you want returned following the GET call. This parameter is optional, and if it is not sent in then the return results will include all reasons.
sendEmailToClient	boolean	POST /waitlist	Flag for whether or not an email will be sent to the client concerning the waitlist addition.
sendEmailToStaff	boolean	POST /waitlist	Flag for whether or not an email will be sent to the staff concerning the waitlist addition.
staffIdList	integer array	GET /waitlist	Should be set as a comma-separated list of the IDs of staff of waitlists to be returned following the GET call.
startDate	string	GET /waitlist	Should be set as the start date of the calendar range to be displayed, formatted as YYYY-MM-DD.
statusList	string array	GET /waitlist	Should be set as a comma-separated list of waitlist statuses to be displayed. Case sensitive. Has acceptable values OPEN, INVITED, REMOVED, BOOKED and EXPIRED.

GET /waitlist

    "statusList": OPEN,
    "classScheduleId": 45662305,
    "order_field": createdDate,
    "order_mode": asc

GET /waitlist/{waitlistId}

    "statusList": OPEN,
    "classScheduleId": 45663562,
    "order_field": createdDate,
    "order_mode": asc

POST /waitlist

{
    "businessId": 43111,
    "client": {Client object for client of waitlist - for more info, see Clients API page},
    "fields": [{Fields object for scheduler fields of waitlist - for more info, see Scheduler Fields API page}],
    "location": {Location object for location of waitlist - for more info, see Locations API page},
    "professional": {Professional object for staff of waitlist - for more info, see Staff API page},
    "reason": {Reason object for service of waitlist - for more info, see Services API page},
    "status": "OPEN",
    "waitListDateList": [{
            "date": 1697414400000,
            "waitListDateTimeList": [{
                    "classScheduleId": 45662305,
                    "endDateTimeUTC": 1697472000000,
                    "endTime": 1200,
                    "startDateTimeUTC": 1697461200000,
                    "startTime": 900
}]}]}

GET /waitlist

[{
    "address": null,
    "auditReferralId": null,
    "businessId": 43111,
    "classScheduleId": 0,
    "client": {Client object for client of waitlist - for more info, see Clients API page},
    "createdDate": 1535380101839,
    "createdUser": null,
    "customFieldData": null,
    "customFieldJson": null,
    "fieldDataList": [{
        "schedulerPreferenceFieldDefnId": 375724
        "value": "15"
    }],
    "fieldDataListJson": (JSON object for scheduler fields data list),
    "fields": {Fields object for scheduler field of waitlist - for more info, see Scheduler Fields API page},
    "lastOfferDate": null,
    "location": {Location object for location of waitlist - for more info, see Locations API page},
    "modifiedDate": 1535380105151,
    "modifiedUser": null,
    "note": null,
    "preferredDate": 1537920000000,
    "preferredTimeOfDay": null,
    "professional": null,
    "reason": {Reason object for service of waitlist - for more info, see Services API page},
    "status": "OPEN",
    "waitListDateList": null,
    "waitListId": 143647
}]

GET /waitlist/{waitlistId}

{
    "address": null,
    "auditReferralId": null,
    "businessId": 43111,
    "classScheduleId": null,
    "client": {Client object for client of waitlist - for more info, see Clients API page},
    "createdDate": 1535553948270,
    "createdUser": null,
    "customFieldData": null,
    "customFieldJson": null,
    "duration": 180,
    "fieldDataList": [{
        "schedulerPreferenceFieldDefnId": 322516,
        "value": "JK"
    }],
    "fieldDataListJson": "[{"schedulerPreferenceFieldDefnId":375724,"value":"15"},{schedulerPreferenceFieldDefnId":386792,"value":"Yes"}]",
    "fields": [{Fields array for scheduler fields of waitlist - for more info, see Scheduler Fields API page}],
    "lastOfferDate": null,
    "location": {Location object for location of waitlist - for more info, see Locations API page},
    "modifiedDate": 1535380105151,
    "modifiedUser": null,
    "note": null,
    "preferredDate": 1537920000000,
    "preferredTimeOfDay": null,
    "professional": null,
    "reason": {Reason object for reason of waitlist - for more info, see Services API page},
    "status": "OPEN",
    "waitListDateList": null,
    "waitListId": 145825
}

POST /waitlist

{
    "address": null,
    "auditReferralId": null,
    "businessId": 43111,
    "classScheduleId": null,
    "client": {Client object for client of waitlist - for more info, see Clients API page},
    "createdDate": 1535380101839,
    "createdUser": "JoeSchmo",
    "customFieldData": null,
    "customFieldJson": null,
    "duration": 180,
    "fieldDataList": [{
        "schedulerPreferenceFieldDefnId": 375724
        "value": "15"
        }],
    "fieldDataListJson": (JSON object for scheduler fields data list),
    "fields": {Fields object for scheduler field of waitlist - for more info, see Scheduler Fields API page},
    "lastOfferDate": null,
    "location": {Location object for location of waitlist - for more info, see Locations API page},
    "modifiedDate": 1535380101839,
    "modifiedUser": "JoeSchmo",
    "note": null,
    "preferredDate": null,
    "preferredTimeOfDay": null,
    "professional": {Professional object for staff of waitlist - for more info, see Staff API page},
    "reason": {Reason object for service of waitlist - for more info, see Services API page},
    "status": "OPEN",
    "waitListDateList": [{
        "active": true,
        "courseSet": null,
        "createdDate": 1697134392847,
        "createdUser": "JoeSchmo",
        "date": 1697446800000,
        "modifiedDate": null,
        "modifiedUser": null,
        "recurringScheduleId": null,
        "waitListDateId": 49485,
        "waitListDateTimeList": [{
            "displayTime": null,
            "endTime": 1030,
            "seq": null,
            "startTime": 1000,
            "waitListDateId": null,
            "waitListDateTimeId": 95490,
        }],
        "waitListId": null
    }],
    "waitListId": null
}

Property name	Type	Required	Description
address	string		Displays the address entered during appointment creation of the specified waitlisted appointment when it is set to a location of locationType VARIABLE.
auditReferralId	string		Provides unique alphanumeric ID that gets placed on an object to inform the audit trail at a later date.
businessId	integer	Yes	Provides unique numerical ID for the business to which the specified waitlist belongs.
classScheduleId	integer		If the specified waitlist is connected to a class that is part of a class schedule, this field will contain the unique numerical ID for that class schedule.
client	object	Yes	Displays the object of any client who is connected to the specified waitlist - for more info, see Clients API page.
createdDate	integer		Displays as the date the specified waitlist was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
createdUser	string		Displays as username of the user who created the specified waitlist. If client booked appointment from scheduler would display as "WebClient".
customFieldData	string		Displays as the contents of all of the specified waitlisted appointment's custom fields, combined.
customFieldJson			Displays a string JSON representing the specified waitlist's customFieldData.
duration	integer		Provides the number of minutes that the specified waitlisted appointment is set to take.
fieldDataList	array		When the specified waitlist registration is made by a client via the web scheduler, this array contains fields objects that were answers to client information questions on the web scheduler.
fieldDataListJson	string		Displays a string JSON representing the fieldDataList array.
fields	array		Displays an array of any scheduler field objects that were assigned to the specified waitlist. For more information, see the Scheduler Field API page.
lastOfferDate	integer		Displays the last offer date for a client when sending an invitation to waitlist registrants, measured in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
location	object		Displays the location object assigned to the specified waitlist - for more info, see Locations API page.
modifiedDate	integer		Displays as the date the specified waitlist 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 the specified waitlist. If client booked appointment from scheduler would display as "WebClient".
note	string		Displays any note added to the specified waitlist.
preferredDate	integer		Displays as the preferred date of the specified waitlist registrant in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
preferredTimeOfDay	string		Displays as preferred time of day of the specified waitlist registrant, only applicable for class session waitlists.
professional	object	Yes	Displays the professional object for the staff member connected to the specified waitlist - for more info, see Staff API page.
reason	object	Yes	Displays the reason object for the service connected to the specified waitlist - for more info, see Services API page.
status	string	Yes	Displays the status of the specified waitlist. Has acceptable values OPEN, INVITED, REMOVED, BOOKED, EXPIRED.
waitListDateList	array		Displays an array of objects pertinent to the date of the specified waitlist.
waitListId	integer		Provides unique numerical ID of the specified waitlist. For information about creating an appointment for a client that is already on a waitlist, see the waitListId property description on the Appointments API page.

TimeTap API

Waitlist

Waitlist API Endpoints

Waitlist API Parameters

Waitlist API Request Body/Payloads

Waitlist API Responses

Waitlist Object Values