v1

latestOpenAPI 3.0.02026-07-17121287546.7 KB

Bookings

Get all bookings

<Note>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.</Note>

get/v2/bookings

Query parameters

statusstring[]

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

attendeeEmailstring

Example:example@domain.com

Filter bookings by the attendee's email address.

attendeeNamestring

Example:John Doe

Filter bookings by the attendee's name.

bookingUidstring

Example:2NtaeaVcKfpmSZ4CthFdfk

Filter bookings by the booking Uid.

eventTypeIdsstring

Example:?eventTypeIds=100,200

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

eventTypeIdstring

Example:?eventTypeId=100

Filter bookings by event type id belonging to the user.

teamsIdsstring

Example:?teamIds=50,60

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

teamIdstring

Example:?teamId=50

Filter bookings by team id that user is part of

afterStartstring

Example:?afterStart=2025-03-07T10:00:00.000Z

Filter bookings with start after this date string.

beforeEndstring

Example:?beforeEnd=2025-03-07T11:00:00.000Z

Filter bookings with end before this date string.

afterCreatedAtstring

Example:?afterCreatedAt=2025-03-07T10:00:00.000Z

Filter bookings that have been created after this date string.

beforeCreatedAtstring

Example:?beforeCreatedAt=2025-03-14T11:00:00.000Z

Filter bookings that have been created before this date string.

afterUpdatedAtstring

Example:?afterUpdatedAt=2025-03-07T10:00:00.000Z

Filter bookings that have been updated after this date string.

beforeUpdatedAtstring

Example:?beforeUpdatedAt=2025-03-14T11:00:00.000Z

Filter bookings that have been updated before this date string.

sortStart'asc' | 'desc'

Example:?sortStart=asc OR ?sortStart=desc

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

sortEnd'asc' | 'desc'

Example:?sortEnd=asc OR ?sortEnd=desc

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

sortCreated'asc' | 'desc'

Example:?sortCreated=asc OR ?sortCreated=desc

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

sortUpdatedAt'asc' | 'desc'

Example:?sortUpdated=asc OR ?sortUpdated=desc

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

takenumber

Example:10

The number of items to return

skipnumber

The number of items to skip

Headers

cal-api-versionstring required

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

Authorizationstring required

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

Response

status'success' | 'error' required

errorobject

Example response

{
  "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",
          "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
  }
}