> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/calcom/cal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bookings

> Manage bookings through the Cal.com API

The Bookings API allows you to create, retrieve, update, and cancel bookings programmatically.

## API Version

All booking endpoints require the `cal-api-version` header:

```bash theme={null}
cal-api-version: 2024-08-13
```

## Authentication

Booking endpoints support multiple authentication methods:

* **API Key**: Pass via `Authorization: Bearer <api-key>` header
* **Access Token**: OAuth access token
* **Client Credentials**: For public bookings, use `x-cal-client-id` and `x-cal-secret-key` headers
* **Optional Auth**: Some endpoints allow unauthenticated access

## Create a Booking

Create a new booking, recurring booking, or instant booking.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.cal.com/v2/bookings \
    --header 'cal-api-version: 2024-08-13' \
    --header 'Content-Type: application/json' \
    --data '{
      "start": "2024-12-10T09:00:00Z",
      "eventTypeId": 123,
      "attendee": {
        "name": "John Doe",
        "email": "john@example.com",
        "timeZone": "America/New_York"
      },
      "meetingUrl": "https://meet.example.com/meeting-123"
    }'
  ```
</CodeGroup>

### Request Body

<ParamField body="eventTypeId" type="number">
  The ID of the event type to book
</ParamField>

<ParamField body="start" type="string" required>
  Start time in UTC ISO 8601 format (e.g., "2024-12-10T09:00:00Z")
</ParamField>

<ParamField body="attendee" type="object" required>
  Attendee information

  <Expandable>
    <ParamField body="name" type="string" required>
      Attendee's full name
    </ParamField>

    <ParamField body="email" type="string" required>
      Attendee's email address
    </ParamField>

    <ParamField body="timeZone" type="string" required>
      Attendee's timezone (e.g., "America/New\_York")
    </ParamField>

    <ParamField body="phoneNumber" type="string">
      Phone number in international format (required if SMS reminders are enabled)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="meetingUrl" type="string">
  Custom meeting URL (optional)
</ParamField>

<ParamField body="instant" type="boolean">
  Set to true for instant meetings (team event types only)
</ParamField>

<ParamField body="eventTypeSlug" type="string">
  Alternative to eventTypeId: provide slug with username/teamSlug
</ParamField>

<ParamField body="username" type="string">
  Username for individual user bookings (used with eventTypeSlug)
</ParamField>

<ParamField body="teamSlug" type="string">
  Team slug for team bookings (used with eventTypeSlug)
</ParamField>

### Response

<ResponseField name="status" type="string">
  Status of the response ("success" or "error")
</ResponseField>

<ResponseField name="data" type="object">
  Booking details

  <Expandable>
    <ResponseField name="id" type="number">
      Unique booking ID
    </ResponseField>

    <ResponseField name="uid" type="string">
      Unique booking identifier
    </ResponseField>

    <ResponseField name="title" type="string">
      Booking title
    </ResponseField>

    <ResponseField name="start" type="string">
      Start time in ISO 8601 format
    </ResponseField>

    <ResponseField name="end" type="string">
      End time in ISO 8601 format
    </ResponseField>

    <ResponseField name="status" type="string">
      Booking status ("accepted", "pending", "cancelled")
    </ResponseField>

    <ResponseField name="attendees" type="array">
      Array of attendee objects
    </ResponseField>
  </Expandable>
</ResponseField>

## Get a Booking

Retrieve a booking by its UID.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.cal.com/v2/bookings/{bookingUid} \
    --header 'cal-api-version: 2024-08-13'
  ```
</CodeGroup>

### Path Parameters

<ParamField path="bookingUid" type="string" required>
  The unique identifier of the booking. Can be:

  * UID of a normal booking
  * UID of one recurring booking recurrence
  * UID of recurring booking (returns all recurrences)
</ParamField>

## Get All Bookings

List all bookings for the authenticated user.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.cal.com/v2/bookings?status=upcoming&limit=10' \
    --header 'Authorization: Bearer <api-key>' \
    --header 'cal-api-version: 2024-08-13'
  ```
</CodeGroup>

### Query Parameters

<ParamField query="status" type="string">
  Filter by booking status: "upcoming", "past", "cancelled"
</ParamField>

<ParamField query="limit" type="number">
  Number of bookings to return (default: 10)
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor for next page
</ParamField>

## Reschedule a Booking

Change the time of an existing booking.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.cal.com/v2/bookings/{bookingUid}/reschedule \
    --header 'cal-api-version: 2024-08-13' \
    --header 'Content-Type: application/json' \
    --data '{
      "start": "2024-12-11T10:00:00Z",
      "reschedulingReason": "Conflict with another meeting"
    }'
  ```
</CodeGroup>

### Request Body

<ParamField body="start" type="string" required>
  New start time in UTC ISO 8601 format
</ParamField>

<ParamField body="reschedulingReason" type="string">
  Reason for rescheduling
</ParamField>

## Cancel a Booking

Cancel an existing booking.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.cal.com/v2/bookings/{bookingUid}/cancel \
    --header 'cal-api-version: 2024-08-13' \
    --header 'Content-Type: application/json' \
    --data '{
      "cancellationReason": "Unable to attend"
    }'
  ```
</CodeGroup>

### Request Body

<ParamField body="cancellationReason" type="string">
  Reason for cancellation
</ParamField>

<ParamField body="seatUid" type="string">
  For seated bookings: specific seat to cancel
</ParamField>

## Additional Endpoints

### Confirm a Booking

Confirm a pending booking (requires authentication as booking owner).

```bash theme={null}
POST /v2/bookings/{bookingUid}/confirm
```

### Decline a Booking

Decline a pending booking (requires authentication as booking owner).

```bash theme={null}
POST /v2/bookings/{bookingUid}/decline
```

### Mark Absent

Mark an attendee as absent from a booking.

```bash theme={null}
POST /v2/bookings/{bookingUid}/mark-absent
```

### Reassign Booking

Reassign a round-robin booking to a different host.

```bash theme={null}
POST /v2/bookings/{bookingUid}/reassign
POST /v2/bookings/{bookingUid}/reassign/{userId}
```

### Get Calendar Links

Get "Add to Calendar" links for a booking.

```bash theme={null}
GET /v2/bookings/{bookingUid}/calendar-links
```

### Get Recordings

Fetch Cal Video recordings for a booking (requires proper authorization).

```bash theme={null}
GET /v2/bookings/{bookingUid}/recordings
```

### Get Transcripts

Get Cal Video transcript download links (valid for 1 hour).

```bash theme={null}
GET /v2/bookings/{bookingUid}/transcripts
```

## Notes

* The `start` time must be in UTC. For example, if a meeting should start at 11:00 in Rome (GMT+2), pass 09:00 UTC.
* For seated bookings with hidden attendees, authentication as event owner/host/team admin/org admin is required to view attendees.
* Recurring bookings are created by passing an event type ID that is configured as recurring.
* For SMS reminder workflows, include the attendee's `phoneNumber` in international format.