> ## 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.
# List bookings
> List bookings in the workspace. Supports filtering by client email, host email, booking type, and meeting start/end time.
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 GET /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:
get:
tags:
- Bookings
summary: List bookings
description: >-
List bookings in the workspace. Supports filtering by client email, host
email, booking type, and meeting start/end time.
parameters:
- $ref: '#/components/parameters/api_key_header'
- in: query
name: type
description: >-
To get the bookings of a particular type only. The available types
are upcoming, past, cancelled, and incomplete. If no value is passed
it will default to all bookings.
required: false
schema:
type: string
- $ref: '#/components/parameters/page_number_param'
- $ref: '#/components/parameters/page_size_param'
- in: query
name: host_email
description: To get the bookings of a particular host only.
required: false
schema:
type: string
- in: query
name: client_email
description: To get the bookings of a particular client only.
required: false
schema:
type: string
- in: query
name: filters
description: Apply filters on your bookings.
required: false
schema:
type: object
properties:
starts_at:
type: object
description: >
To filter bookings by meeting start time, use deep object
style in the query string, e.g.:
`?filters[starts_at][rule]=after&filters[starts_at][value]=2027-12-19T06:00:00.000Z`
- Supported rules: at, after, before, between
- Value: a single UTC datetime string for at/after/before, or
two comma-separated UTC datetime strings for between.
properties:
rule:
type: string
enum:
- at
- after
- before
- between
description: The rule to be used for comparing with the starts_at value
value:
type: string
ends_at:
type: object
description: >
To filter bookings by meeting end time, use deep object style
in the query string, e.g.:
`?filters[ends_at][rule]=before&filters[ends_at][value]=2027-12-19T10:00:00.000Z`
- Supported rules: at, after, before, between
- Value: a single UTC datetime string for at/after/before, or
two comma-separated UTC datetime strings for between.
properties:
rule:
type: string
enum:
- at
- after
- before
- between
description: The rule to be used for comparing with the ends_at value
value:
type: string
starts_at_for_host:
type: object
description: >
To filter bookings by meeting start time in the host's
timezone, use deep object style in the query string, e.g.:
`?host_email=host@example.com&filters[starts_at_for_host][rule]=on&filters[starts_at_for_host][value]=2025-08-11T10:00:00.000+05:30`
- **Required**: This filter only works when `host_email`
parameter is provided
- Supported rules: on, after, before, between
- Value: accepts both date (YYYY-MM-DD) and datetime strings
in host's timezone. For precise filtering, use datetime format
with timezone offset.
- For between rule: use two comma-separated values
- The filter uses the host's timezone for date comparison
properties:
rule:
type: string
enum:
- 'on'
- after
- before
- between
description: >-
The rule to be used for comparing with the
starts_at_for_host value
value:
type: string
- in: query
name: sorting_order
description: Sort bookings by booking creation date. The default value is `desc`.
required: false
schema:
type: string
enum:
- asc
- desc
responses:
'200':
description: OK - Request succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/booking_list_response'
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
page_number_param:
in: query
name: page_number
description: >-
Retrieve paginated results by specifying the desired page number. If
this parameter is absent, all results will be returned.
required: false
schema:
type: integer
page_size_param:
in: query
name: page_size
description: >-
Set the number of results returned in the response. Defaulting to 30
when omitted.
required: false
schema:
type: integer
schemas:
booking_list_response:
allOf:
- type: object
properties:
bookings:
type: array
items:
$ref: '#/components/schemas/booking'
description: List of bookings.
pagination:
$ref: '#/components/schemas/pagination'
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'
pagination:
type: object
properties:
total_records:
type: integer
description: Total number of records.
total_pages:
type: integer
description: Total number of pages available.
current_page_number:
type: integer
description: Current page number.
page_size:
type: integer
description: Number of records per page.
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'
````