> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.default.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Book a meeting
> Books a slot previously returned by [`POST /v1/scheduling/events/{event}/slots`](/api-reference/scheduling/get-available-slots), consuming its reservation. The startTime must be a time the event hosts are available for — on SLOT_TAKEN the reservation stays usable, so fetch slots again and retry with the same reservationId.
Requires the `scheduling:write` scope.
If a book request times out, do not book again. The booking almost always succeeded. A retry returns CONFLICT, RESERVATION\_USED, or RESERVATION\_EXPIRED, and with the same workflowExecutionId it can never create a second meeting for the same workflow run.
## OpenAPI
````yaml /api-reference/openapi.json post /v1/scheduling/meetings
openapi: 3.1.0
info:
title: Default Public API
version: 1.0.0
description: >-
Customer-facing REST API for scheduling and workflow triggers: list events,
fetch availability, book, reschedule, or cancel meetings, and fire API
triggers. Authenticate every request with `Authorization: Bearer `
using an API key created in workspace settings (Settings → API Keys). Keys
carry permissions (`scheduling:read`, `scheduling:write`, `triggers:read`,
`triggers:write`; a write key also satisfies read for its surface) and can
be revoked at any time. Requests are rate limited to 30 per minute per key —
a 429 response carries a `Retry-After` header with the seconds until the
window resets. This is a server-to-server API: no CORS headers are sent, so
it cannot be called directly from a browser.
servers:
- url: https://api.default.com
security:
- apiKey: []
paths:
/v1/scheduling/meetings:
post:
tags:
- Scheduling
summary: Book a meeting
description: >-
Books a slot previously returned by [`POST
/v1/scheduling/events/{event}/slots`](/api-reference/scheduling/get-available-slots),
consuming its reservation. The startTime must be a time the event hosts
are available for — on SLOT_TAKEN the reservation stays usable, so fetch
slots again and retry with the same reservationId.
Requires the `scheduling:write` scope.
operationId: bookMeeting
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
startTime:
type: string
format: date-time
guestFirstName:
type: string
guestLastName:
type: string
guestPhone:
type: string
guestEmails:
maxItems: 10
type: array
items:
type: string
format: email
leadTimezone:
type: string
reservationId:
type: string
format: uuid
responses:
type: object
propertyNames:
type: string
additionalProperties:
type: string
fieldResponses:
type: object
propertyNames:
type: string
additionalProperties:
type: string
event:
description: >-
The same event or scheduling link identifier used to fetch
slots. The reservation is scoped to it. Trigger-routed
bookings pass the schedulingLinkId from the trigger outcome.
type: string
workflowExecutionId:
description: >-
Links the meeting to the workflow run that routed this lead
and resumes it, so CRM writeback and routing assignments
record. Responds 404 when the id does not resolve.
type: string
format: uuid
personEmail:
description: >-
The lead being booked. With workflowExecutionId set this
must match the email the trigger was fired with. A different
value responds 400.
type: string
format: email
required:
- startTime
- reservationId
- event
- personEmail
responses:
'201':
description: Success
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
eventId:
type: string
format: uuid
title:
type: string
status:
type: string
enum:
- scheduled
- rescheduled
- held
- no_show
- canceled
date:
type: string
format: date-time
duration:
type: integer
minimum: -2147483648
maximum: 2147483647
meetingLink:
anyOf:
- type: string
- type: 'null'
conferencingType:
type: string
enum:
- google_meet
- microsoft_teams
- zoom
- zoom_personal
- in_person
- phone
- other
location:
anyOf:
- type: string
- type: 'null'
personEmail:
type: string
format: email
additionalAttendees:
type: array
items:
type: string
cancellationReason:
anyOf:
- type: string
- type: 'null'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- eventId
- title
- status
- date
- duration
- meetingLink
- conferencingType
- location
- personEmail
- additionalAttendees
- cancellationReason
- createdAt
- updatedAt
additionalProperties: false
'400':
description: Error (INVALID_REQUEST, RESERVATION_MISMATCH, WORK_EMAIL_REQUIRED)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- INVALID_REQUEST
- RESERVATION_MISMATCH
- WORK_EMAIL_REQUIRED
message:
type: string
details:
type: array
items:
type: string
examples:
INVALID_REQUEST:
summary: INVALID_REQUEST
value:
error:
code: INVALID_REQUEST
message: Request validation failed
details:
- 'personEmail: Invalid email address'
RESERVATION_MISMATCH:
summary: RESERVATION_MISMATCH
value:
error:
code: RESERVATION_MISMATCH
message: Reservation does not match this event
WORK_EMAIL_REQUIRED:
summary: WORK_EMAIL_REQUIRED
value:
error:
code: WORK_EMAIL_REQUIRED
message: This event requires a work email address
'401':
description: Error (INVALID_API_KEY)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- INVALID_API_KEY
message:
type: string
details:
type: array
items:
type: string
examples:
INVALID_API_KEY:
summary: INVALID_API_KEY
value:
error:
code: INVALID_API_KEY
message: Missing, malformed, or revoked API key
'403':
description: Error (MISSING_SCOPE)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- MISSING_SCOPE
message:
type: string
details:
type: array
items:
type: string
examples:
MISSING_SCOPE:
summary: MISSING_SCOPE
value:
error:
code: MISSING_SCOPE
message: >-
This API key is missing the required 'scheduling:write'
scope
'404':
description: Error (NOT_FOUND)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- NOT_FOUND
message:
type: string
details:
type: array
items:
type: string
examples:
NOT_FOUND:
summary: NOT_FOUND
value:
error:
code: NOT_FOUND
message: Event not found
'409':
description: >-
Error (RESERVATION_EXPIRED, RESERVATION_USED, SLOT_TAKEN,
NO_HOST_AVAILABLE, CONFLICT)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- RESERVATION_EXPIRED
- RESERVATION_USED
- SLOT_TAKEN
- NO_HOST_AVAILABLE
- CONFLICT
message:
type: string
details:
type: array
items:
type: string
examples:
RESERVATION_EXPIRED:
summary: RESERVATION_EXPIRED
value:
error:
code: RESERVATION_EXPIRED
message: >-
Reservation has expired — request slots again to get a
new one
RESERVATION_USED:
summary: RESERVATION_USED
value:
error:
code: RESERVATION_USED
message: >-
Reservation has already been used — an earlier booking
attempt may have succeeded, so confirm before booking
again
SLOT_TAKEN:
summary: SLOT_TAKEN
value:
error:
code: SLOT_TAKEN
message: The selected time is no longer available
NO_HOST_AVAILABLE:
summary: NO_HOST_AVAILABLE
value:
error:
code: NO_HOST_AVAILABLE
message: >-
No host is available at the selected time — pick another
slot
CONFLICT:
summary: CONFLICT
value:
error:
code: CONFLICT
message: >-
The scheduling session has expired — restart the flow
that produced it
'429':
description: Error (RATE_LIMITED)
headers:
Retry-After:
description: Seconds until the current rate-limit window resets.
schema:
type: integer
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- RATE_LIMITED
message:
type: string
details:
type: array
items:
type: string
examples:
RATE_LIMITED:
summary: RATE_LIMITED
value:
error:
code: RATE_LIMITED
message: Rate limit exceeded for this API key
'500':
description: Error (INTERNAL_ERROR)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- INTERNAL_ERROR
message:
type: string
details:
type: array
items:
type: string
examples:
INTERNAL_ERROR:
summary: INTERNAL_ERROR
value:
error:
code: INTERNAL_ERROR
message: Internal server error
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
description: >-
Organization API key, created in workspace settings (Settings → API
Keys). Sent as `Authorization: Bearer `. Shown once at creation;
revocable and permission-scoped per key.
````