> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.neetocal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create booking
> Create a booking. Omit `slot_date` and `slot_start_time` to book the first available slot.
This endpoint is part of API v1, which is deprecated. Please use the [v2 API](/getting-started/introduction) instead.
Replace `{your-subdomain}` with your workspace’s subdomain.
Learn how to find your subdomain in [Workspace subdomain](/getting-started/workspace-subdomain).
## OpenAPI
````yaml bundled-v1/bookings.yaml POST /bookings
openapi: 3.0.3
info:
title: NeetoCal Bookings APIs
version: 1.0.0
servers:
- description: NeetoCal APIs
url: https://{your-subdomain}.neetocal.com/api/external/v1
variables:
your-subdomain:
default: spinkart
description: >-
Replace **spinkart** with your [workspace's
subdomain](/getting-started/workspace-subdomain).
security: []
tags:
- name: Bookings
description: APIs to create, list, reschedule, and cancel bookings.
paths:
/bookings:
post:
tags:
- Bookings
summary: Create a booking
description: >-
Create a booking. Omit `slot_date` and `slot_start_time` to book the
first available slot.
parameters:
- $ref: '#/components/parameters/api_key_header'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
meeting_slug:
type: string
description: Slug of scheduling link you want to book.
example: meeting-with-oliver-smith
name:
type: string
description: Name of person making the booking.
example: Eve Smith
email:
type: string
description: Email of person making the booking.
example: eve@example.com
slot_date:
type: string
description: >-
Date on which you want to book. This should be in
"YYYY-MM-DD" format. If `slot_date` and `slot_start_time`
are not provided then the first available slot will be
booked.
example: '2025-07-15'
slot_start_time:
type: string
description: >-
Start time for the booking. This should be in "HH:MM AM/PM"
format.
example: 01:30 PM
time_zone:
type: string
description: Time zone of person making the booking.
example: Asia/Kolkata
preferred_meeting_spot:
type: string
description: >
Your preferred meeting place. This field is optional. Before
passing this value, ensure that the corresponding meeting
place is configured in the "Where" section of the scheduling
link.
example: jitsi
enum:
- custom
- jitsi
- in_person
- daily
- zoom
- whereby
- google_meet
- teams
default: jitsi
form_responses:
type: object
description: >-
Responses for the questions of booking form (optional). The
key of the field should be the field code of the question.
The field code can be found in scheduling link's Settings ->
Questions -> 3 dot menu of the question -> Edit -> Advanced
properties. You can specify guest emails using the
`guest_email_s` field code.
properties:
guest_email_s:
type: array
description: >-
Array of guest emails for the booking. The default field
code is "guest_email_s". You can change this by editing
the Guest email(s) question, and changing the field code
in advanced properties.
items:
type: string
example:
guest_email_s:
- sam@example.com
- charlie@example.com
language: English
reserve_slot:
type: boolean
description: >
When `true`, the booking is created with `pre_booked` status
and the slot is reserved for a paid booking. The scheduling
link must have a fee configured. If `send_payment_link` is
not explicitly set to `false`, a payment link email will be
sent to the client.
default: false
send_payment_link:
type: boolean
description: >
Only applicable when `reserve_slot` is `true`. When `true`,
a payment link email is sent to the client after the slot is
reserved. When `false`, the slot is reserved without sending
any payment link email.
default: true
metadata:
type: object
description: >
Additional data to be stored with the booking. To pre-create
future bookings, pass `pre_bookings` containing the duration
(in minutes) and UTC start datetime of each booking that
should be created ahead of time.
Note: If the provided slot time is not available, that slot
will be skipped. Please use the [List available slots
API](/api-reference/slots/list) to get the available slots
before creating pre-bookings.
Pre-bookings are made asynchronously. Use the
[associated-bookings
endpoint](/api-reference/bookings/get-associated) to check
the status of the pre-bookings.
properties:
fee_id:
type: string
description: >-
The ID of the fee to be used for the paid booking
reservation. Only applicable when `reserve_slot` is
`true`. You can get the fee ID from the `fees` array in
the [Get scheduling
link](/api-reference-v1/scheduling-links/get) response.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
pre_bookings:
type: array
maxItems: 20
description: >-
List of future bookings to be created along with the
primary booking.
items:
type: object
required:
- duration
- starts_at
properties:
duration:
type: integer
description: Duration of the pre booking in minutes.
example: 15
starts_at:
type: string
format: date-time
description: >-
Start time of the pre booking in ISO 8601 format
(UTC offset required).
example: '2025-11-28T02:30:00+00:00'
example:
metadata:
pre_bookings:
- duration: 15
starts_at: '2025-11-28T02:30:00+00:00'
- duration: 15
starts_at: '2025-12-05T02:30:00+00:00'
required:
- meeting_slug
- name
- email
- time_zone
responses:
'200':
description: OK - Request succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/booking'
components:
parameters:
api_key_header:
in: header
name: X-Api-Key
description: >-
Use the X-Api-Key header to provide your workspace API key. Refer to
[Authentication](/getting-started/authentication) for more information.
required: true
schema:
type: string
schemas:
booking:
type: object
properties:
id:
type: string
description: Unique identifier for the booking.
sid:
type: string
description: Short identifier (SID) for the booking, used in URLs and API calls.
parent_booking_id:
type: string
nullable: true
description: Reference to the parent booking if this is a group booking.
email:
type: string
description: Email address of the person who made the booking.
name:
type: string
description: Name of the person who made the booking.
host_name:
type: string
description: Name of the primary host for the meeting.
host_email:
type: string
description: Email address of the primary host for the meeting.
is_multihost:
type: boolean
description: Whether the meeting has multiple hosts.
multihosts:
type: array
items:
type: object
properties:
name:
type: string
description: Name of the host.
email:
type: string
description: Email address of the host.
description: List of all hosts for the meeting when is_multihost is true.
starts_at:
type: string
format: date-time
description: Start time of the booking in UTC.
ends_at:
type: string
format: date-time
description: End time of the booking in UTC.
time_zone:
type: string
description: Time zone of the booking location.
starts_at_for_client:
type: string
description: Start time of the booking in the client's local time zone.
ends_at_for_client:
type: string
description: End time of the booking in the client's local time zone.
status:
type: string
description: >-
Current status of the booking (e.g., confirmed, cancelled,
awaiting_approval, rejected).
cancel_reason:
type: string
nullable: true
description: Reason provided when the booking was cancelled.
cancelled_by:
type: string
nullable: true
description: Name of the person who cancelled the booking.
reschedule_requested:
type: boolean
description: Whether a reschedule has been requested for this booking.
preferred_meeting_spot:
type: string
description: Preferred meeting platform or location type selected by the client.
room_type:
type: string
nullable: true
description: |
Type of meeting room or platform being used.
enum:
- daily
- zoom
- jitsi
- google_meet
- teams
- whereby
- in_person
- custom
- phone_call
room_url:
type: string
nullable: true
description: URL for the meeting room or platform.
room_id:
type: string
nullable: true
description: Unique identifier for the meeting room or platform.
spot_details:
type: string
nullable: true
description: Additional details about the meeting place.
created_at:
type: string
format: date-time
description: Timestamp when the booking was created.
updated_at:
type: string
format: date-time
description: Timestamp when the booking was last updated.
meeting_id:
type: string
description: Unique identifier of the scheduling link this booking belongs to.
meeting:
type: object
properties:
name:
type: string
description: Name of the scheduling link.
description: Basic information about the associated meeting.
no_show:
type: boolean
description: Whether the booking is marked as no-show by the host.
meeting_outcome:
nullable: true
description: Meeting outcome assigned to the booking.
allOf:
- $ref: '#/components/schemas/meeting_outcome'
notes_url:
type: string
nullable: true
description: URL to access notes or additional information about the booking.
internal_notes:
type: string
nullable: true
description: Internal notes about the booking visible only to hosts and admins.
metadata:
type: object
nullable: true
description: Additional custom data associated with the booking.
admin_booking_url:
type: string
description: URL for hosts and admins to view and manage the booking.
client_booking_url:
type: string
description: URL for clients to view their booking details.
form_responses:
type: array
items:
type: object
properties:
field:
type: string
description: Display name of the form field.
value:
type: string
description: Value submitted for the form field.
type:
type: string
description: Type of the form field (e.g., name, email, additional_guests).
field_code:
type: string
description: Internal code identifier for the form field.
description: Responses submitted through the booking form.
form_responses_as_hash:
type: object
description: Form responses organized as key-value pairs for easier access.
additionalProperties:
type: string
payment:
nullable: true
description: >-
Payment details for the booking. Included only when a payment exists
for the booking.
allOf:
- $ref: '#/components/schemas/booking_payment'
meeting_outcome:
type: object
properties:
id:
type: string
description: Unique identifier for the meeting outcome.
example: 59413def-60eb-47c6-b390-098fcf583b66
name:
type: string
description: Name of the meeting outcome.
example: Pricing Discussion
color:
type: string
description: Color assigned to the meeting outcome.
enum:
- blue
- orange
- gray
- red
- yellow
- violet
- pink
- teal
- cyan
- green
example: yellow
kind:
type: string
description: Kind of the meeting outcome.
example: custom
color_hex:
type: string
description: Hex color code for the meeting outcome.
example: '#EAB308'
is_system:
type: boolean
description: >-
Whether this is a system-defined meeting outcome. System outcomes
cannot be modified or deleted.
example: false
is_organization_owned:
type: boolean
description: Whether this outcome belongs to the organization.
example: true
booking_payment:
type: object
description: >
Payment details associated with the booking. Present only when a payment
exists for the booking.
properties:
id:
type: string
format: uuid
description: Unique identifier of the payment record.
example: f46c9ddf-221d-4238-afb2-280c1c6b3185
external_id:
type: string
nullable: true
description: Payment reference ID from the payment provider.
example: pi_3ThCkv2c3CtEndqE1BwejQno
provider:
type: string
description: Payment provider that processed the payment.
example: stripe
amount:
type: string
description: Payment amount.
example: '100.0'
currency:
type: string
description: Currency code. Follows the ISO 4217 standard.
example: USD
status:
type: string
description: Current status of the payment.
example: successful
successful:
type: boolean
description: Whether the payment was completed successfully.
example: true
payment_at:
type: string
format: date-time
nullable: true
description: Timestamp when the payment was made.
example: '2026-06-11T17:51:09.321Z'
````