Bookings

GETGet all bookings

Retrieves a paginated list of all bookings for the authenticated user, team, or organization.

GET/v2/bookings

GET/v2/bookings

Query Parameters

statusarray<string>

Filter bookings by status. If you want to filter by multiple statuses, separate them with a comma.

attendeeEmailstring

Filter bookings by the attendee's email address.

attendeeNamestring

Filter bookings by the attendee's name.

bookingUidstring

Filter bookings by the booking Uid.

eventTypeIdsstring

Filter bookings by event type ids belonging to the user. Event type ids must be separated by a comma.

eventTypeIdstring

Filter bookings by event type id belonging to the user.

teamsIdsstring

Filter bookings by team ids that user is part of. Team ids must be separated by a comma.

teamIdstring

Filter bookings by team id that user is part of

afterStartstring

Filter bookings with start after this date string.

beforeEndstring

Filter bookings with end before this date string.

afterCreatedAtstring

Filter bookings that have been created after this date string.

beforeCreatedAtstring

Filter bookings that have been created before this date string.

afterUpdatedAtstring

Filter bookings that have been updated after this date string.

beforeUpdatedAtstring

Filter bookings that have been updated before this date string.

sortStartstring

Sort results by their start time in ascending or descending order.

Value in: "asc" | "desc"

sortEndstring

Sort results by their end time in ascending or descending order.

Value in: "asc" | "desc"

sortCreatedstring

Sort results by their creation time (when booking was made) in ascending or descending order.

Value in: "asc" | "desc"

sortUpdatedAtstring

Sort results by their updated time (for example when booking status changes) in ascending or descending order.

Value in: "asc" | "desc"

takenumber

The number of items to return

Default: 100

skipnumber

The number of items to skip

Default: 0

Header Parameters

cal-api-versionRequiredstring

Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.

Default: "2024-08-13"

AuthorizationRequiredstring

value must be Bearer <token> where <token> is api key prefixed with cal_ or managed user access token

curl -X GET "https://example.com/v2/bookings?status=%3Fstatus%3Dupcoming%2Cpast&attendeeEmail=example%40domain.com&attendeeName=John+Doe&bookingUid=2NtaeaVcKfpmSZ4CthFdfk&eventTypeIds=%3FeventTypeIds%3D100%2C200&eventTypeId=%3FeventTypeId%3D100&teamsIds=%3FteamIds%3D50%2C60&teamId=%3FteamId%3D50&afterStart=%3FafterStart%3D2025-03-07T10%3A00%3A00.000Z&beforeEnd=%3FbeforeEnd%3D2025-03-07T11%3A00%3A00.000Z&afterCreatedAt=%3FafterCreatedAt%3D2025-03-07T10%3A00%3A00.000Z&beforeCreatedAt=%3FbeforeCreatedAt%3D2025-03-14T11%3A00%3A00.000Z&afterUpdatedAt=%3FafterUpdatedAt%3D2025-03-07T10%3A00%3A00.000Z&beforeUpdatedAt=%3FbeforeUpdatedAt%3D2025-03-14T11%3A00%3A00.000Z&sortStart=%3FsortStart%3Dasc+OR+%3FsortStart%3Ddesc&sortEnd=%3FsortEnd%3Dasc+OR+%3FsortEnd%3Ddesc&sortCreated=%3FsortCreated%3Dasc+OR+%3FsortCreated%3Ddesc&sortUpdatedAt=%3FsortUpdated%3Dasc+OR+%3FsortUpdated%3Ddesc&take=10&skip=0" \
  -H "cal-api-version: 2024-08-13" \
  -H "Authorization: <string>"

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "uid": "booking_uid_123",
      "title": "Consultation",
      "description": "Learn how to integrate scheduling into marketplace.",
      "hosts": [
        {
          "id": 1,
          "name": "Jane Doe",
          "email": "jane100@example.com",
          "displayEmail": "jane100@example.com",
          "username": "jane100",
          "timeZone": "America/Los_Angeles"
        }
      ],
      "status": "accepted",
      "cancellationReason": "User requested cancellation",
      "cancelledByEmail": "canceller@example.com",
      "reschedulingReason": "User rescheduled the event",
      "rescheduledByEmail": "rescheduler@example.com",
      "rescheduledFromUid": "previous_uid_123",
      "rescheduledToUid": "new_uid_456",
      "start": "2024-08-13T15:30:00Z",
      "end": "2024-08-13T16:30:00Z",
      "duration": 60,
      "eventTypeId": 50,
      "eventType": {
        "id": 1,
        "slug": "some-event"
      },
      "meetingUrl": "https://example.com/recurring-meeting",
      "location": "https://example.com/meeting",
      "absentHost": true,
      "createdAt": "2024-08-13T15:30:00Z",
      "updatedAt": "2024-08-13T15:30:00Z",
      "metadata": {
        "key": "value"
      },
      "rating": 4,
      "icsUid": "ics_uid_123",
      "attendees": [
        {
          "name": "John Doe",
          "email": "john@example.com",
          "displayEmail": "john@example.com",
          "timeZone": "America/New_York",
          "language": "en",
          "absent": false,
          "phoneNumber": "+1234567890"
        }
      ],
      "guests": [
        "guest1@example.com",
        "guest2@example.com"
      ],
      "bookingFieldsResponses": {
        "customField": "customValue"
      }
    }
  ],
  "pagination": {
    "totalItems": 123,
    "remainingItems": 103,
    "returnedItems": 10,
    "itemsPerPage": 10,
    "currentPage": 2,
    "totalPages": 13,
    "hasNextPage": true,
    "hasPreviousPage": true
  },
  "error": {}
}

Create a booking

Reserve a slot