> ## Documentation Index
> Fetch the complete documentation index at: https://cal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a booking proposal
>
A booking proposal is a booking request that carries several candidate times instead of one. The organizer later confirms exactly one of them, and only then does a booking exist.
The request body is the same as `POST /v2/bookings`, except that the single `start` is replaced by `requestedTimeslots` — a list of proposed start times in UTC.
The number of proposed times must exactly match the event type's `bookingProposalCount`, and every one of them must be available. If any proposed time is unavailable the whole request is rejected.
Reschedules, recurring event types, seated event types and paid event types do not accept proposals.
Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.
## OpenAPI
````yaml /api-reference/v2/openapi.json post /v2/booking-proposals
openapi: 3.0.0
info:
title: Cal.com API v2
description: ''
version: 1.0.0
contact: {}
servers: []
security: []
tags: []
paths:
/v2/booking-proposals:
post:
tags:
- Booking proposals
summary: Create a booking proposal
description: |2-
A booking proposal is a booking request that carries several candidate times instead of one. The organizer later confirms exactly one of them, and only then does a booking exist.
The request body is the same as `POST /v2/bookings`, except that the single `start` is replaced by `requestedTimeslots` — a list of proposed start times in UTC.
The number of proposed times must exactly match the event type's `bookingProposalCount`, and every one of them must be available. If any proposed time is unavailable the whole request is rejected.
Reschedules, recurring event types, seated event types and paid event types do not accept proposals.
Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.
operationId: BookingProposalsController_2024_08_13_createBookingProposal
parameters:
- name: cal-api-version
in: header
description: >-
Must be set to 2024-08-13. If not set to this value, the endpoint
will default to an older version.
required: true
schema:
type: string
example: '2024-08-13'
default: '2024-08-13'
- name: Authorization
in: header
description: >-
value must be `Bearer ` where `` is api key prefixed
with cal_, managed user access token, or OAuth access token
required: false
schema:
type: string
- name: x-cal-secret-key
in: header
description: For platform customers - OAuth client secret key
required: false
schema:
type: string
- name: x-cal-client-id
in: header
description: For platform customers - OAuth client ID
required: false
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBookingProposalInput_2024_08_13'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBookingProposalOutput_2024_08_13'
components:
schemas:
CreateBookingProposalInput_2024_08_13:
type: object
properties:
attendee:
description: The attendee's details.
allOf:
- $ref: '#/components/schemas/CreateBookingAttendee'
bookingFieldsResponses:
type: object
additionalProperties: true
description: >-
Booking field responses consisting of an object with booking field
slug as keys and user response as values for custom booking fields
added by you.
example:
customField: customValue
eventTypeId:
type: number
description: >-
The ID of the event type that is booked. Required unless
eventTypeSlug and username are provided as an alternative to
identifying the event type.
example: 123
eventTypeSlug:
type: string
description: >-
The slug of the event type. Required along with username / teamSlug
and optionally organizationSlug if eventTypeId is not provided.
example: my-event-type
username:
type: string
description: >-
The username of the event owner. Required along with eventTypeSlug
and optionally organizationSlug if eventTypeId is not provided.
example: john-doe
teamSlug:
type: string
description: >-
Team slug for team that owns event type for which slots are fetched.
Required along with eventTypeSlug and optionally organizationSlug if
the team is part of organization
example: john-doe
organizationSlug:
type: string
description: >-
The organization slug. Optional, only used when booking with
eventTypeSlug + username or eventTypeSlug + teamSlug.
example: acme-corp
guests:
description: An optional list of guest emails attending the event.
example:
- guest1@example.com
- guest2@example.com
type: array
items:
type: string
meetingUrl:
type: string
format: uri
description: >-
Deprecated - use 'location' instead. Meeting URL just for this
booking. Displayed in email and calendar event. If not provided then
cal video link will be generated.
example: https://example.com/meeting
deprecated: true
location:
description: >-
One of the event type locations. If instead of passing one of the
location objects as required by schema you are still passing a
string please use an object.
oneOf:
- $ref: '#/components/schemas/BookingInputAddressLocation_2024_08_13'
title: Address
- $ref: >-
#/components/schemas/BookingInputAttendeeAddressLocation_2024_08_13
title: Attendee Address
- $ref: >-
#/components/schemas/BookingInputAttendeeDefinedLocation_2024_08_13
title: Attendee Defined
- $ref: >-
#/components/schemas/BookingInputAttendeePhoneLocation_2024_08_13
title: Attendee Phone
- $ref: '#/components/schemas/BookingInputIntegrationLocation_2024_08_13'
title: Integration
- $ref: '#/components/schemas/BookingInputLinkLocation_2024_08_13'
title: Link
- $ref: '#/components/schemas/BookingInputPhoneLocation_2024_08_13'
title: Phone
- $ref: >-
#/components/schemas/BookingInputOrganizersDefaultAppLocation_2024_08_13
title: Organizer Default App
metadata:
type: object
additionalProperties:
type: string
description: >-
You can store any additional data you want here. Metadata must have
at most 50 keys, each key up to 40 characters, and string values up
to 500 characters.
example:
key: value
lengthInMinutes:
type: number
minimum: 1
example: 30
description: >-
If it is an event type that has multiple possible lengths that
attendee can pick from, you can pass the desired booking length
here.
If not provided then event type default length will be used for the booking.
routing:
description: >-
Routing information from routing forms that determined the booking
assignment. Both responseId and teamMemberIds are required if
provided.
example:
responseId: 123
teamMemberIds:
- 101
- 102
allOf:
- $ref: '#/components/schemas/Routing'
emailVerificationCode:
type: string
description: >-
Email verification code required when event type has email
verification enabled.
example: '123456'
allowConflicts:
type: boolean
description: >-
When true and the authenticated user is a host of the event type,
availability conflict checks are bypassed. If the user is not a host
or is unauthenticated, this parameter is silently ignored.
example: true
allowBookingOutOfBounds:
type: boolean
description: >-
When true and the authenticated user is a host of the event type,
booking time out-of-bounds checks are bypassed allowing bookings
outside the normally permitted scheduling window. If the user is not
a host or is unauthenticated, this parameter is silently ignored.
Only supported on the 2026-02-25 API version.
example: true
skipBookingLimits:
type: boolean
description: >-
When true and the authenticated user is a host of the event type,
booking limit checks (event type, team, and per-host limits such as
bookings per day/week/month/year, as well as duration limits) are
bypassed, allowing the booking to be created even when a host has
reached their limit. If the user is not a host or is
unauthenticated, this parameter is silently ignored. Only supported
on the 2026-02-25 API version.
example: true
requestedTimeslots:
minItems: 1
description: >-
The proposed start times in ISO 8601 format in UTC timezone. The
number of times must exactly match the event type's
`bookingProposalCount`, and each must be an available slot.
example:
- '2024-08-13T09:00:00Z'
- '2024-08-14T09:00:00Z'
type: array
items:
type: string
required:
- attendee
- requestedTimeslots
CreateBookingProposalOutput_2024_08_13:
type: object
properties:
status:
enum:
- success
- error
type: string
example: success
data:
$ref: '#/components/schemas/BookingProposalOutput_2024_08_13'
required:
- status
- data
CreateBookingAttendee:
type: object
properties:
name:
type: string
description: The name of the attendee.
example: John Doe
timeZone:
type: string
description: The time zone of the attendee.
example: America/New_York
phoneNumber:
type: string
description: The phone number of the attendee in international format.
example: '+919876543210'
language:
enum:
- ar
- ca
- de
- es
- eu
- he
- id
- ja
- lv
- pl
- ro
- sr
- th
- vi
- az
- cs
- el
- es-419
- fi
- hr
- it
- km
- nl
- pt
- ru
- sv
- tr
- zh-CN
- bg
- da
- en
- et
- fr
- hu
- iw
- ko
- 'no'
- pt-BR
- sk
- ta
- uk
- zh-TW
- bn
type: string
description: >-
The preferred language of the attendee. Used for booking
confirmation.
example: it
default: en
email:
type: string
description: The email of the attendee.
example: john.doe@example.com
required:
- name
- timeZone
BookingInputAddressLocation_2024_08_13:
type: object
properties:
type:
type: string
example: address
description: >-
only allowed value for type is `address` - it refers to address
defined by the organizer.
required:
- type
BookingInputAttendeeAddressLocation_2024_08_13:
type: object
properties:
type:
type: string
example: attendeeAddress
description: only allowed value for type is `attendeeAddress`
address:
type: string
minLength: 1
example: 123 Example St, City, Country
required:
- type
- address
BookingInputAttendeeDefinedLocation_2024_08_13:
type: object
properties:
type:
type: string
example: attendeeDefined
description: only allowed value for type is `attendeeDefined`
location:
type: string
minLength: 1
example: 321 Example St, City, Country
required:
- type
- location
BookingInputAttendeePhoneLocation_2024_08_13:
type: object
properties:
type:
type: string
example: attendeePhone
description: only allowed value for type is `attendeePhone`
phone:
type: string
example: '+37120993151'
required:
- type
- phone
BookingInputIntegrationLocation_2024_08_13:
type: object
properties:
type:
type: string
example: integration
description: only allowed value for type is `integration`
integration:
enum:
- cal-video
- google-meet
- zoom
- whereby-video
- whatsapp-video
- webex-video
- telegram-video
- tandem
- sylaps-video
- skype-video
- sirius-video
- signal-video
- shimmer-video
- salesroom-video
- roam-video
- riverside-video
- ping-video
- office365-video
- mirotalk-video
- jitsi
- jelly-video
- jelly-conferencing
- huddle
- facetime-video
- element-call-video
- eightxeight-video
- discord-video
- demodesk-video
- campfire-video
type: string
example: cal-video
required:
- type
- integration
BookingInputLinkLocation_2024_08_13:
type: object
properties:
type:
type: string
example: link
description: >-
only allowed value for type is `link` - it refers to link defined by
the organizer.
required:
- type
BookingInputPhoneLocation_2024_08_13:
type: object
properties:
type:
type: string
example: phone
description: >-
only allowed value for type is `phone` - it refers to phone defined
by the organizer.
required:
- type
BookingInputOrganizersDefaultAppLocation_2024_08_13:
type: object
properties:
type:
type: string
example: organizersDefaultApp
description: >-
only available for team event types and the only allowed value for
type is `organizersDefaultApp` - it refers to the default app
defined by the organizer.
required:
- type
Routing:
type: object
properties:
queuedResponseId:
type: string
nullable: true
description: >-
The ID of the queued form response. Only present if the form
response was queued.
example: '123'
responseId:
type: number
nullable: true
description: The ID of the routing form response.
example: 123
teamMemberIds:
description: Array of team member IDs that were routed to handle this booking.
example:
- 101
- 102
type: array
items:
type: number
teamMemberEmail:
type: string
description: The email of the team member assigned to handle this booking.
example: john.doe@example.com
skipContactOwner:
type: boolean
description: Whether to skip contact owner assignment from CRM integration.
example: true
crmAppSlug:
type: string
description: The CRM application slug for integration.
example: salesforce
crmOwnerRecordType:
type: string
description: The CRM owner record type for contact assignment.
example: Account
crmRecordOwnerFallbackTeamMemberIds:
description: >-
Eligible CRM owner fallback team member IDs to pass to the booking
API.
example:
- 103
- 104
type: array
items:
type: number
crmRecordOwnerFallbackMode:
enum:
- relationship
- attributeRules
type: string
description: The CRM owner fallback strategy used for this routing result.
example: relationship
required:
- teamMemberIds
BookingProposalOutput_2024_08_13:
type: object
properties:
uid:
type: string
example: 019205e4-4b3a-7000-8000-2c1a3f5b7d90
eventTypeId:
type: number
example: 123
expiresAt:
type: string
description: >-
When the proposal can no longer be confirmed, which is the end of
its latest proposed timeslot.
example: '2024-08-14T09:30:00.000Z'
format: date-time
requestedTimeslots:
type: array
items:
$ref: '#/components/schemas/BookingProposalSlotOutput_2024_08_13'
required:
- uid
- eventTypeId
- expiresAt
- requestedTimeslots
BookingProposalSlotOutput_2024_08_13:
type: object
properties:
start:
type: string
example: '2024-08-13T09:00:00.000Z'
format: date-time
end:
type: string
example: '2024-08-13T09:30:00.000Z'
format: date-time
hostId:
type: number
nullable: true
description: >-
The host this timeslot would be booked with. Present for round robin
event types only; null otherwise, because the organizer of a
collective or personal event does not vary by timeslot.
example: 42
required:
- start
- end
````