POST
/
v2
/
bookings
Create a booking
curl --request POST \
  --url https://api.cal.com/v2/bookings \
  --header 'Content-Type: application/json' \
  --header 'cal-api-version: <cal-api-version>' \
  --data '{
  "start": "2024-08-13T09:00:00Z",
  "attendee": {
    "name": "John Doe",
    "email": "[email protected]",
    "timeZone": "America/New_York",
    "phoneNumber": "+919876543210",
    "language": "it"
  },
  "bookingFieldsResponses": {
    "customField": "customValue"
  },
  "eventTypeId": 123,
  "eventTypeSlug": "my-event-type",
  "username": "john-doe",
  "teamSlug": "john-doe",
  "organizationSlug": "acme-corp",
  "guests": [
    "[email protected]",
    "[email protected]"
  ],
  "meetingUrl": "https://example.com/meeting",
  "location": {
    "type": "address"
  },
  "metadata": {
    "key": "value"
  },
  "lengthInMinutes": 30,
  "routing": {
    "responseId": 123,
    "teamMemberIds": [
      101,
      102
    ]
  },
  "emailVerificationCode": "123456"
}'
{
  "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": "[email protected]",
        "username": "jane100",
        "timeZone": "America/Los_Angeles"
      }
    ],
    "status": "accepted",
    "cancellationReason": "User requested cancellation",
    "cancelledByEmail": "[email protected]",
    "reschedulingReason": "User rescheduled the event",
    "rescheduledByEmail": "[email protected]",
    "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": "[email protected]",
        "timeZone": "America/New_York",
        "language": "en",
        "absent": false,
        "phoneNumber": "+1234567890"
      }
    ],
    "guests": [
      "[email protected]",
      "[email protected]"
    ],
    "bookingFieldsResponses": {
      "customField": "customValue"
    }
  }
}

Headers

​
cal-api-version
string
default:2024-08-13
required

Must be set to 2024-08-13

​
Authorization
string

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

​
x-cal-secret-key
string

For platform customers - OAuth client secret key

​
x-cal-client-id
string

For platform customers - OAuth client ID

Body

application/json

Accepts different types of booking input: Create Booking (Option 1), Create Instant Booking (Option 2), or Create Recurring Booking (Option 3)

​
start
string
required

The start time of the booking in ISO 8601 format in UTC timezone.

Example:

"2024-08-13T09:00:00Z"

​
attendee
object
required

The attendee's details.

​
bookingFieldsResponses
object

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
number

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
string

The slug of the event type. Required along with username / teamSlug and optionally organizationSlug if eventTypeId is not provided.

Example:

"my-event-type"

​
username
string

The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.

Example:

"john-doe"

​
teamSlug
string

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
string

The organization slug. Optional, only used when booking with eventTypeSlug + username or eventTypeSlug + teamSlug.

Example:

"acme-corp"

​
guests
string[]

An optional list of guest emails attending the event.

Example:
["[email protected]", "[email protected]"]
​
meetingUrl
string
deprecated

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"

​
location
object

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.

​
metadata
object

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
number

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.

Example:

30

​
routing
object

Routing information from routing forms that determined the booking assignment. Both responseId and teamMemberIds are required if provided.

Example:
{
  "responseId": 123,
  "teamMemberIds": [101, 102]
}
​
emailVerificationCode
string

Email verification code required when event type has email verification enabled.

Example:

"123456"

Response

201 - application/json
​
status
enum<string>
required
Available options:
success,
error
Example:

"success"

​
data
required

Booking data, which can be either a BookingOutput object or an array of RecurringBookingOutput objects