Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Anchor
topOfPage
topOfPage
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.


Info
titleOn this page

Table of Contents





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 Request Body/Payloads


Code Block
languagejs
titleGET /waitlist
linenumberstrue
collapsetrue
    "statusList": OPEN,
    "classScheduleId": 45662305,
    "order_field": createdDate,
    "order_mode": asc


Code Block
languagejs
titlePOST GET /waitlist/{waitlistId}
linenumberstrue
collapsetrue
{
    "businessIdstatusList": 43111OPEN,
    "clientclassScheduleId": {Client45663562,
object for client of waitlist - for more info, see Clients API page} "order_field": createdDate,
    "order_mode": asc


Code Block
languagejs
titlePOST /waitlist
linenumberstrue
collapsetrue
{
    "businessId": 43111,
    "fieldsclient": [{FieldsClient object for scheduler fieldsclient of waitlist - for more info, see SchedulerClients Fields API page}],
    "locationfields": [{LocationFields object for scheduler locationfields of waitlist - for more info, see Locations 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
}]}]}





Waitlist API Responses


Code Block
languagejs
titleGET /waitlist
linenumberstrue
collapsetrue
[{
    "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,
    "customField DatacustomFieldData": 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
}]


Code Block
languagejs
titleGET /waitlist/{waitlistId}
linenumberstrue
collapsetrue
{
    "auditReferralIdaddress": "r08dcf09208194933a33fd9298392dd70"null,
    "auditReferralId": null,
    "businessId": 43111,
    "classScheduleId": null,
    "client": {Client object for client of waitlist - for more info, see Clients API page},
    "createdDate": 1535553948270,
    "createdUser": "WebClient"null,
    "fieldDataListcustomFieldData": [{}],null,
    "fieldDataListJsoncustomFieldJson": "[{"schedulerPreferenceFieldDefnId":375724,"value":"15"},{schedulerPreferenceFieldDefnId":386792,"value":"Yes"}]"null,
    "fieldsduration": null180,
    "lastOfferDatefieldDataList": null,[{
        "locationschedulerPreferenceFieldDefnId": {Location322516,
object for location of waitlist - for more info, see Locations API page} "value": "JK"
    }],
    "modifiedDatefieldDataListJson": 1535380105151,
    "modifiedUser": null,
    "note": null"[{"schedulerPreferenceFieldDefnId":375724,"value":"15"},{schedulerPreferenceFieldDefnId":386792,"value":"Yes"}]",
    "preferredDatefields": 1537920000000,[{Fields array for   "preferredTimeOfDay": null,
    "professional": {Professional object for staff scheduler fields 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"Scheduler Fields API page}],
       "lastOfferDate": null,
    "endTimelocation": 1030,
       {Location object for location of waitlist - for more info, see Locations API page},
    "seqmodifiedDate": 01535380105151,
    "modifiedUser": null,
      "startTimenote": 1000null,
       "preferredDate": 1537920000000,
    "waitListDateIdpreferredTimeOfDay": 50145null,
      "professional": null,
     "waitListDateTimeIdreason": 96117{Reason object for reason of waitlist - for more }]info, see Services API page},
    "waitListIdstatus": 145825"OPEN",
     }]"waitListDateList": null,
    "waitListId": 145825
}


Code Block
languagejs
titlePOST /waitlist
linenumberstrue
collapsetrue
{
    "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
}





Waitlist Object Values


Property nameTypeRequiredDescriptionTypeRequiredDescription
addressstring
Displays the address entered during appointment creation of the specified waitlisted appointment when it is set to a location of locationType VARIABLE. 
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 the specified waitlist belongs.
classScheduleIdinteger
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.
clientobjectYesDisplays the object of any client who is connected to the specified waitlist - for more info, see Clients API page.
createdDateinteger
Displays as the date the specified waitlist was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. createdUserstringDisplays as username of the user who created specified waitlist. If client booked appointment from scheduler would display as "WebClient". form. 
createdUserstring
Displays as username of the user who created the specified waitlist. If client booked appointment from scheduler would display as "WebClient". 
customFieldDatastring
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.
durationinteger
Provides the number of minutes that the specified waitlisted appointment is set to take.
fieldDataListarray
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.
fieldDataListJsonstring
Displays a string JSON representing the fieldDataList array.
fieldsarray
Displays an array of any scheduler field objects that were assigned to the 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 the specified waitlist - for more info, see Locations API page.
modifiedDateinteger
Displays as the date the 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 the specified waitlist. If client booked appointment from scheduler would display as "WebClient". 
notestring
Displays any note added to the specified waitlist.
preferredDateinteger
Displays as the preferred date of the specified waitlist registrant in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
preferredTimeOfDaystring
Displays as preferred time of day of the specified waitlist registrant, only applicable for class session waitlists.
professionalobjectYesDisplays the professional object for the staff member connected to the specified waitlist - for more info, see Staff API page.
reasonobjectYesDisplays the reason object for the service connected to the specified waitlist - for more info, see Services API page.
statusstringYesDisplays the status of the specified waitlist. Has acceptable values OPEN, INVITED, REMOVED, BOOKED, EXPIRED.
waitListDateListarray
Displays an array of objects pertinent to the date of the specified waitlist.
waitListIdinteger

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.