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




Waitlist API Endpoints

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




Waitlist 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

clientIdintegerGET /waitlistShould be set as the ID of client of waitlist to be returned following the GET call.
endDatestringGET /waitlistShould be set as the end date of the waitlist to be returned, formatted as YYYY-MM-DD. 
locationIdListinteger arrayGET /waitlistShould be set as a comma-separated list of locationIds connected to the waitlists you want returned following the GET call.
order_fieldstringGET /waitlistShould be set as the field that waitlists returned following the GET call should be ordered by.
order_modestringGET /waitlistShould be set as the mode ('asc'ending or 'desc'ending) in which waitlists returned following the GET call should appear.
pageNumberintegerGET /waitlistWorks 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.
pageSizeintegerGET /waitlistWorks 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.
reasonIdListinteger arrayGET /waitlistShould 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.
sendEmailToClientbooleanPOST /waitlistFlag for whether or not an email will be sent to the client concerning the waitlist addition.
sendEmailToStaffbooleanPOST /waitlistFlag for whether or not an email will be sent to the staff concerning the waitlist addition.
staffIdListinteger arrayGET /waitlistShould be set as a comma-separated list of the IDs of staff of waitlists to be returned following the GET call.
startDatestringGET /waitlistShould be set as the start date of the calendar range to be displayed, formatted as YYYY-MM-DD. 
statusListstring arrayGET /waitlistShould be set as a comma-separated list of waitlist statuses to be displayed. Case sensitive. Has acceptable values OPEN, INVITED, REMOVED, BOOKED and EXPIRED.




Waitlist API Responses

GET /waitlist
[{
    "auditReferralId": null,
    "businessId": 43111,
    "classScheduleId": 0,
    "client": {Client object for client of waitlist - for more info, see Clients API page},
    "createdDate": 1535380101839,
    "createdUser": "JoeSchmo",
    "fieldDataList": null,
    "fieldDataListJson": "[{"schedulerPreferenceFieldDefnId":375724,"value":"15"},{schedulerPreferenceFieldDefnId":386792,"value":"Yes"}]",
    "fields": null,
    "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": {Professional object for staff of waitlist - for more info, see Staff API page},
    "reason": {Reason object for reason of waitlist - for more info, see Services API page},
    "status": "OPEN",
    "waitListDateList": null,
    "waitListId": 143647
}]
GET /waitlist/{waitlistId}
{
    "auditReferralId": "r08dcf09208194933a33fd9298392dd70",
    "businessId": 43111,
    "classScheduleId": null,
    "client": {Client object for client of waitlist - for more info, see Clients API page},
    "createdDate": 1535553948270,
    "createdUser": "WebClient",
    "fieldDataList": [{}],
    "fieldDataListJson": "[{"schedulerPreferenceFieldDefnId":375724,"value":"15"},{schedulerPreferenceFieldDefnId":386792,"value":"Yes"}]",
    "fields": null,
    "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": {Professional object for staff of waitlist - for more info, see Staff API page},
    "reason": {Reason object for reason of waitlist - for more info, see Services API page},
    "status": "OPEN",
    "waitListDateList": [{
        "createdDate": null,
        "createdUser": null,
        "date": 1535932800000,
        "modifiedDate": null,
        "modifiedUser": null,
        "waitListDateId": 50145,
        "waitListDateTimeList": [{
            "displayTime": "10:00 am - 10:30 am",
            "endTime": 1030,
            "seq": 0,
            "startTime": 1000,
            "waitListDateId": 50145,
            "waitListDateTimeId": 96117
        }],
        "waitListId": 145825
    }],
    "waitListId": 145825
}
POST /waitlist
{
    "auditReferralId": null,
    "businessId": 43111,
    "classScheduleId": null,
    "client": {Client object for client of waitlist - for more info, see Clients API page},
    "createdDate": 1535380101839,
    "createdUser": "JoeSchmo",
    "fieldDataList": null,
    "fieldDataListJson": null,
    "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 reason of waitlist - for more info, see Services API page},
    "status": "OPEN",
    "waitListDateList": [{
        "createdDate": null,
        "createdUser": null,
        "date": 1537934400000,
        "modifiedDate": null,
        "modifiedUser": null,
        "waitListDateId": 49485,
        "waitListDateTimeList": [{
            "displayTime": null,
            "endTime": 1030,
            "seq": null,
            "startTime": 1000,
            "waitListDateId": null,
            "waitListDateTimeId": 95490,
        }],
        "waitListId": null
    }],
    "waitListId": null
}




Waitlist Object Values

Property nameTypeRequiredDescription
auditReferralIdstring
Provides unique alphanumeric ID that gets placed on an object to inform the audit trail at a later date.
businessIdintegerYesProvides unique numerical ID for the business to which specified waitlist belongs.
classScheduleIdinteger
If 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.
clientobjectYesDisplays the object of any client who is connected to specified waitlist - for more info, see Clients API page.
createdDateinteger
Displays as date specified waitlist was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
createdUserstring
Displays as username of the user who created specified waitlist. If client booked appointment from scheduler would display as "WebClient". 
fieldDataListarray
When 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.
fieldDataListJsonstring
Displays a string JSON representing the fieldDataList array.
fieldsarray
Displays an array of any scheduler field objects that were assigned to specified waitlist. For more information, see the Scheduler Field API page.
lastOfferDateinteger
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.
locationobject
Displays the location object assigned to specified waitlist - for more info, see Locations API page.
modifiedDateinteger
Displays as date specified waitlist 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 waitlist. If client booked appointment from scheduler would display as "WebClient". 
notestring
Displays any note added to specified waitlist.
preferredDateinteger
Displays as preferred date of waitlist registrant in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
preferredTimeOfDaystring
Displays as preferred time of day of waitlist registrant, only applicable for class session waitlists.
professionalobjectYesDisplays the professional object for staff member connected to specified waitlist - for more info, see Staff API page.
reasonobjectYesDisplays the reason object for service connected to specified waitlist - for more info, see Services API page.
statusstringYesDisplays the status of specified waitlist. Has acceptable values OPEN, INVITED, REMOVED, BOOKED, EXPIRED.
waitListDateListarray
Displays an array of objects pertinent to the date of specified waitlist.
waitListIdinteger

Provides unique numerical ID of 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.