Create event Waitlist

post

https://api.vcita.biz/platform/v1/scheduling/waitlist

Overview

Join an event waitlist.

Booking note

To register a client directly to an event instance (instead of joining the waitlist), create a booking using POST /platform/v1/scheduling/bookings and provide event_instance_id.

Available for Staff, App, Directory, and Client tokens.

Client Identification

Client tokens: The client is identified from the token.
Staff/App/Directory tokens: Must provide client_id to identify which client to add to the waitlist.

Required fields

business_id and event_instance_id are always required. With a Staff, App or Directory token, client_id and form_data are required as well: the request is validated against the business's scheduling form, and every field marked required: true there (by default Email and First Name) must be supplied in form_data.fields, even though client_id already identifies the client. A missing scheduling-form field fails with 422 FORM_VALIDATION_ERROR, and this check runs before the event instance is looked up.

Prerequisites

event_instance_id is a scheduled event instance, not a service. Joining a waitlist needs an existing occurrence of an event-type service; passing the service uid fails with 422 Unauthorized.
The event instance must be full: its confirmed registrations plus active pending bookings must have reached max_attendance. A waitlist is only for an event with no free spot, so joining one that still has room fails with 422 Event is not full - register the client with POST /platform/v1/scheduling/bookings instead.
The form_data.fields uids come from GET /platform/v1/scheduling/scheduling_forms/get_form?business_id={business_id}. They differ per business, so look them up rather than hard-coding them.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

business_id

string

required

Business UID. Required.

channel

string

Source channel for tracking.

client_id

string

Client UID. Required for Staff/App/Directory tokens. Does not exempt the request from scheduling-form validation: fields marked required: true must still be supplied via form_data.fields, otherwise the request fails with 422 FORM_VALIDATION_ERROR.

event_instance_id

string

required

UID of a scheduled event instance - one dated occurrence of an event-type service, as returned in data.event_instance.uid by GET /platform/v1/scheduling/event_instance/{event_instance_id}. Required. It is not the service uid: an event instance refers to its service through its own service_id. A value that is not an event instance of this business - a service uid included - fails with 422 Unauthorized.

form_data

object

Client form data for the business's scheduling form. Required for Staff/App/Directory tokens - every field marked required: true in the form definition must be present, even when client_id is supplied. Field uids come from GET /platform/v1/scheduling/scheduling_forms/get_form?business_id={business_id}.

Structure

fields is an object keyed by field uid - the same shape as form_data on POST /platform/v1/scheduling/bookings:

{
  "form_data": {
    "fields": {
      "{email_field_id}": "[email protected]",
      "{first_name_field_id}": "John"
    }
  }
}

matter_uid

string

Matter/conversation UID to associate with this waitlist entry.

source_name

string

Source name for tracking (e.g., 'client_portal', 'api').

source_url

string

Source URL for tracking.

time_zone

string

Time zone for the waitlist entry.

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

Structure

201Success