Create New Booking [Alpha]

post

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

Overview

Creates a booking for either an appointment with a staff member or registration for a group event.

Relationship to appointments and events

A booking is the lifecycle/action interface for scheduled items:

For an appointment booking, this endpoint creates the appointment on the business calendar and returns it as a booking object.
For an event registration, this endpoint creates a registration (attendance) for the event instance and returns it as a booking object.

When to use

If you are looking for an endpoint to create appointments or register clients to events, this is the endpoint to use.

Authentication

Available for Client and Staff tokens. The endpoint also accepts unauthenticated requests, which is how anonymous client-portal / LiveSite bookings are created: when no token is supplied, the client is resolved (or created) from the email in form_data.fields.

Supply a Client token together with client_id to book on behalf of an existing, known client.

Required fields

business_id is always required. For an appointment booking, service_id, staff_id, start_time and form_data are required as well. For an event registration, supply event_instance_id and form_data instead of service_id / staff_id / start_time.

A missing top-level parameter fails with 400 PARAMETER_MISSING; a missing scheduling-form field fails with 422 FORM_VALIDATION_ERROR.

Prerequisites

service_id and the staff uids that may provide it (providers_staff) come from GET /platform/v1/services.
A bookable start_time comes from GET /platform/v1/staff/availability. Availability slots are returned at a fixed granularity (10 minutes) regardless of the service duration - you must verify that the full service duration fits in a contiguous run of returned slots, otherwise the booking fails with 422 TIMESLOT_UNAVAILABLE.
The form_data.fields uids come from GET /platform/v1/scheduling/scheduling_forms/get_form.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

business_id

string

required

Business uid

campaign

string

Source campaign

channel

string

Source channel

client_id

string

Client uid. Only usable with a Client token. 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

Event instance uid. Required for event registration (not appointment booking).

form_data

object

required

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

Structure

form_data is an object of named sections - fields, service_fields, meeting_details, others, policies, client_settings. Every section is an object, never an array, and fields is keyed by field uid:

{
  "form_data": {
    "fields": {
      "{email_field_id}": "[email protected]",
      "{first_name_field_id}": "John"
    },
    "others": { "notes": null },
    "policies": {}
  }
}

There is no field_id / type / new_data wrapper.

matter_uid

string

Matter uid (conversation context)

portal_id

string

Business uid (same as business_id, for portal context)

service_id

string

Service uid. Required for appointment booking.

source_name

string

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

source_url

string

Source URL

staff_id

string

Staff uid. Required for appointment booking. Must be one of the service's providers_staff (see GET /platform/v1/services).

start_time

string

ISO 8601 format (e.g., "2026-09-16T15:00:00Z"). Required for appointment. Must be a slot where the whole service duration fits - see GET /platform/v1/staff/availability.

time_zone

string

Default is set to UTC if not provided

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

400A mandatory top-level parameter is missing. error is a string.

422Business-rule failure. Note that the type of error depends on error_code: it is a string for TIMESLOT_UNAVAILABLE / ALREADY_REGISTERED, and an object keyed by scheduling-form field uid for FORM_VALIDATION_ERROR.