Create a booking proposal

curl --request POST \
  --url https://api.cal.com/v2/booking-proposals \
  --header 'Content-Type: application/json' \
  --header 'cal-api-version: <cal-api-version>' \
  --data '
{
  "attendee": {
    "name": "John Doe",
    "timeZone": "America/New_York",
    "phoneNumber": "+919876543210",
    "language": "it",
    "email": "john.doe@example.com"
  },
  "requestedTimeslots": [
    "2024-08-13T09:00:00Z",
    "2024-08-14T09:00:00Z"
  ],
  "bookingFieldsResponses": {
    "customField": "customValue"
  },
  "eventTypeId": 123,
  "eventTypeSlug": "my-event-type",
  "username": "john-doe",
  "teamSlug": "john-doe",
  "organizationSlug": "acme-corp",
  "guests": [
    "guest1@example.com",
    "guest2@example.com"
  ],
  "meetingUrl": "https://example.com/meeting",
  "location": {
    "type": "address"
  },
  "metadata": {
    "key": "value"
  },
  "lengthInMinutes": 30,
  "routing": {
    "responseId": 123,
    "teamMemberIds": [
      101,
      102
    ]
  },
  "emailVerificationCode": "123456",
  "allowConflicts": true,
  "allowBookingOutOfBounds": true,
  "skipBookingLimits": true
}
'

import requests

url = "https://api.cal.com/v2/booking-proposals"

payload = {
    "attendee": {
        "name": "John Doe",
        "timeZone": "America/New_York",
        "phoneNumber": "+919876543210",
        "language": "it",
        "email": "john.doe@example.com"
    },
    "requestedTimeslots": ["2024-08-13T09:00:00Z", "2024-08-14T09:00:00Z"],
    "bookingFieldsResponses": { "customField": "customValue" },
    "eventTypeId": 123,
    "eventTypeSlug": "my-event-type",
    "username": "john-doe",
    "teamSlug": "john-doe",
    "organizationSlug": "acme-corp",
    "guests": ["guest1@example.com", "guest2@example.com"],
    "meetingUrl": "https://example.com/meeting",
    "location": { "type": "address" },
    "metadata": { "key": "value" },
    "lengthInMinutes": 30,
    "routing": {
        "responseId": 123,
        "teamMemberIds": [101, 102]
    },
    "emailVerificationCode": "123456",
    "allowConflicts": True,
    "allowBookingOutOfBounds": True,
    "skipBookingLimits": True
}
headers = {
    "cal-api-version": "<cal-api-version>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'cal-api-version': '<cal-api-version>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    attendee: {
      name: 'John Doe',
      timeZone: 'America/New_York',
      phoneNumber: '+919876543210',
      language: 'it',
      email: 'john.doe@example.com'
    },
    requestedTimeslots: ['2024-08-13T09:00:00Z', '2024-08-14T09:00:00Z'],
    bookingFieldsResponses: {customField: 'customValue'},
    eventTypeId: 123,
    eventTypeSlug: 'my-event-type',
    username: 'john-doe',
    teamSlug: 'john-doe',
    organizationSlug: 'acme-corp',
    guests: ['guest1@example.com', 'guest2@example.com'],
    meetingUrl: 'https://example.com/meeting',
    location: {type: 'address'},
    metadata: {key: 'value'},
    lengthInMinutes: 30,
    routing: {responseId: 123, teamMemberIds: [101, 102]},
    emailVerificationCode: '123456',
    allowConflicts: true,
    allowBookingOutOfBounds: true,
    skipBookingLimits: true
  })
};

fetch('https://api.cal.com/v2/booking-proposals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cal.com/v2/booking-proposals",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'attendee' => [
        'name' => 'John Doe',
        'timeZone' => 'America/New_York',
        'phoneNumber' => '+919876543210',
        'language' => 'it',
        'email' => 'john.doe@example.com'
    ],
    'requestedTimeslots' => [
        '2024-08-13T09:00:00Z',
        '2024-08-14T09:00:00Z'
    ],
    'bookingFieldsResponses' => [
        'customField' => 'customValue'
    ],
    'eventTypeId' => 123,
    'eventTypeSlug' => 'my-event-type',
    'username' => 'john-doe',
    'teamSlug' => 'john-doe',
    'organizationSlug' => 'acme-corp',
    'guests' => [
        'guest1@example.com',
        'guest2@example.com'
    ],
    'meetingUrl' => 'https://example.com/meeting',
    'location' => [
        'type' => 'address'
    ],
    'metadata' => [
        'key' => 'value'
    ],
    'lengthInMinutes' => 30,
    'routing' => [
        'responseId' => 123,
        'teamMemberIds' => [
                101,
                102
        ]
    ],
    'emailVerificationCode' => '123456',
    'allowConflicts' => true,
    'allowBookingOutOfBounds' => true,
    'skipBookingLimits' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "cal-api-version: <cal-api-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cal.com/v2/booking-proposals"

	payload := strings.NewReader("{\n  \"attendee\": {\n    \"name\": \"John Doe\",\n    \"timeZone\": \"America/New_York\",\n    \"phoneNumber\": \"+919876543210\",\n    \"language\": \"it\",\n    \"email\": \"john.doe@example.com\"\n  },\n  \"requestedTimeslots\": [\n    \"2024-08-13T09:00:00Z\",\n    \"2024-08-14T09:00:00Z\"\n  ],\n  \"bookingFieldsResponses\": {\n    \"customField\": \"customValue\"\n  },\n  \"eventTypeId\": 123,\n  \"eventTypeSlug\": \"my-event-type\",\n  \"username\": \"john-doe\",\n  \"teamSlug\": \"john-doe\",\n  \"organizationSlug\": \"acme-corp\",\n  \"guests\": [\n    \"guest1@example.com\",\n    \"guest2@example.com\"\n  ],\n  \"meetingUrl\": \"https://example.com/meeting\",\n  \"location\": {\n    \"type\": \"address\"\n  },\n  \"metadata\": {\n    \"key\": \"value\"\n  },\n  \"lengthInMinutes\": 30,\n  \"routing\": {\n    \"responseId\": 123,\n    \"teamMemberIds\": [\n      101,\n      102\n    ]\n  },\n  \"emailVerificationCode\": \"123456\",\n  \"allowConflicts\": true,\n  \"allowBookingOutOfBounds\": true,\n  \"skipBookingLimits\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("cal-api-version", "<cal-api-version>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cal.com/v2/booking-proposals")
  .header("cal-api-version", "<cal-api-version>")
  .header("Content-Type", "application/json")
  .body("{\n  \"attendee\": {\n    \"name\": \"John Doe\",\n    \"timeZone\": \"America/New_York\",\n    \"phoneNumber\": \"+919876543210\",\n    \"language\": \"it\",\n    \"email\": \"john.doe@example.com\"\n  },\n  \"requestedTimeslots\": [\n    \"2024-08-13T09:00:00Z\",\n    \"2024-08-14T09:00:00Z\"\n  ],\n  \"bookingFieldsResponses\": {\n    \"customField\": \"customValue\"\n  },\n  \"eventTypeId\": 123,\n  \"eventTypeSlug\": \"my-event-type\",\n  \"username\": \"john-doe\",\n  \"teamSlug\": \"john-doe\",\n  \"organizationSlug\": \"acme-corp\",\n  \"guests\": [\n    \"guest1@example.com\",\n    \"guest2@example.com\"\n  ],\n  \"meetingUrl\": \"https://example.com/meeting\",\n  \"location\": {\n    \"type\": \"address\"\n  },\n  \"metadata\": {\n    \"key\": \"value\"\n  },\n  \"lengthInMinutes\": 30,\n  \"routing\": {\n    \"responseId\": 123,\n    \"teamMemberIds\": [\n      101,\n      102\n    ]\n  },\n  \"emailVerificationCode\": \"123456\",\n  \"allowConflicts\": true,\n  \"allowBookingOutOfBounds\": true,\n  \"skipBookingLimits\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cal.com/v2/booking-proposals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["cal-api-version"] = '<cal-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"attendee\": {\n    \"name\": \"John Doe\",\n    \"timeZone\": \"America/New_York\",\n    \"phoneNumber\": \"+919876543210\",\n    \"language\": \"it\",\n    \"email\": \"john.doe@example.com\"\n  },\n  \"requestedTimeslots\": [\n    \"2024-08-13T09:00:00Z\",\n    \"2024-08-14T09:00:00Z\"\n  ],\n  \"bookingFieldsResponses\": {\n    \"customField\": \"customValue\"\n  },\n  \"eventTypeId\": 123,\n  \"eventTypeSlug\": \"my-event-type\",\n  \"username\": \"john-doe\",\n  \"teamSlug\": \"john-doe\",\n  \"organizationSlug\": \"acme-corp\",\n  \"guests\": [\n    \"guest1@example.com\",\n    \"guest2@example.com\"\n  ],\n  \"meetingUrl\": \"https://example.com/meeting\",\n  \"location\": {\n    \"type\": \"address\"\n  },\n  \"metadata\": {\n    \"key\": \"value\"\n  },\n  \"lengthInMinutes\": 30,\n  \"routing\": {\n    \"responseId\": 123,\n    \"teamMemberIds\": [\n      101,\n      102\n    ]\n  },\n  \"emailVerificationCode\": \"123456\",\n  \"allowConflicts\": true,\n  \"allowBookingOutOfBounds\": true,\n  \"skipBookingLimits\": true\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "data": {
    "uid": "019205e4-4b3a-7000-8000-2c1a3f5b7d90",
    "eventTypeId": 123,
    "expiresAt": "2024-08-14T09:30:00.000Z",
    "requestedTimeslots": [
      {
        "start": "2024-08-13T09:00:00.000Z",
        "end": "2024-08-13T09:30:00.000Z",
        "hostId": 42
      }
    ]
  }
}

Bookings

Create a booking proposal

A booking proposal is a booking request that carries several candidate times instead of one. The organizer later confirms exactly one of them, and only then does a booking exist.

The request body is the same as POST /v2/bookings, except that the single start is replaced by requestedTimeslots — a list of proposed start times in UTC.

The number of proposed times must exactly match the event type’s bookingProposalCount, and every one of them must be available. If any proposed time is unavailable the whole request is rejected.

Reschedules, recurring event types, seated event types and paid event types do not accept proposals.

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.

POST

booking-proposals

Create a booking proposal

curl --request POST \
  --url https://api.cal.com/v2/booking-proposals \
  --header 'Content-Type: application/json' \
  --header 'cal-api-version: <cal-api-version>' \
  --data '
{
  "attendee": {
    "name": "John Doe",
    "timeZone": "America/New_York",
    "phoneNumber": "+919876543210",
    "language": "it",
    "email": "john.doe@example.com"
  },
  "requestedTimeslots": [
    "2024-08-13T09:00:00Z",
    "2024-08-14T09:00:00Z"
  ],
  "bookingFieldsResponses": {
    "customField": "customValue"
  },
  "eventTypeId": 123,
  "eventTypeSlug": "my-event-type",
  "username": "john-doe",
  "teamSlug": "john-doe",
  "organizationSlug": "acme-corp",
  "guests": [
    "guest1@example.com",
    "guest2@example.com"
  ],
  "meetingUrl": "https://example.com/meeting",
  "location": {
    "type": "address"
  },
  "metadata": {
    "key": "value"
  },
  "lengthInMinutes": 30,
  "routing": {
    "responseId": 123,
    "teamMemberIds": [
      101,
      102
    ]
  },
  "emailVerificationCode": "123456",
  "allowConflicts": true,
  "allowBookingOutOfBounds": true,
  "skipBookingLimits": true
}
'

import requests

url = "https://api.cal.com/v2/booking-proposals"

payload = {
    "attendee": {
        "name": "John Doe",
        "timeZone": "America/New_York",
        "phoneNumber": "+919876543210",
        "language": "it",
        "email": "john.doe@example.com"
    },
    "requestedTimeslots": ["2024-08-13T09:00:00Z", "2024-08-14T09:00:00Z"],
    "bookingFieldsResponses": { "customField": "customValue" },
    "eventTypeId": 123,
    "eventTypeSlug": "my-event-type",
    "username": "john-doe",
    "teamSlug": "john-doe",
    "organizationSlug": "acme-corp",
    "guests": ["guest1@example.com", "guest2@example.com"],
    "meetingUrl": "https://example.com/meeting",
    "location": { "type": "address" },
    "metadata": { "key": "value" },
    "lengthInMinutes": 30,
    "routing": {
        "responseId": 123,
        "teamMemberIds": [101, 102]
    },
    "emailVerificationCode": "123456",
    "allowConflicts": True,
    "allowBookingOutOfBounds": True,
    "skipBookingLimits": True
}
headers = {
    "cal-api-version": "<cal-api-version>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'cal-api-version': '<cal-api-version>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    attendee: {
      name: 'John Doe',
      timeZone: 'America/New_York',
      phoneNumber: '+919876543210',
      language: 'it',
      email: 'john.doe@example.com'
    },
    requestedTimeslots: ['2024-08-13T09:00:00Z', '2024-08-14T09:00:00Z'],
    bookingFieldsResponses: {customField: 'customValue'},
    eventTypeId: 123,
    eventTypeSlug: 'my-event-type',
    username: 'john-doe',
    teamSlug: 'john-doe',
    organizationSlug: 'acme-corp',
    guests: ['guest1@example.com', 'guest2@example.com'],
    meetingUrl: 'https://example.com/meeting',
    location: {type: 'address'},
    metadata: {key: 'value'},
    lengthInMinutes: 30,
    routing: {responseId: 123, teamMemberIds: [101, 102]},
    emailVerificationCode: '123456',
    allowConflicts: true,
    allowBookingOutOfBounds: true,
    skipBookingLimits: true
  })
};

fetch('https://api.cal.com/v2/booking-proposals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cal.com/v2/booking-proposals",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'attendee' => [
        'name' => 'John Doe',
        'timeZone' => 'America/New_York',
        'phoneNumber' => '+919876543210',
        'language' => 'it',
        'email' => 'john.doe@example.com'
    ],
    'requestedTimeslots' => [
        '2024-08-13T09:00:00Z',
        '2024-08-14T09:00:00Z'
    ],
    'bookingFieldsResponses' => [
        'customField' => 'customValue'
    ],
    'eventTypeId' => 123,
    'eventTypeSlug' => 'my-event-type',
    'username' => 'john-doe',
    'teamSlug' => 'john-doe',
    'organizationSlug' => 'acme-corp',
    'guests' => [
        'guest1@example.com',
        'guest2@example.com'
    ],
    'meetingUrl' => 'https://example.com/meeting',
    'location' => [
        'type' => 'address'
    ],
    'metadata' => [
        'key' => 'value'
    ],
    'lengthInMinutes' => 30,
    'routing' => [
        'responseId' => 123,
        'teamMemberIds' => [
                101,
                102
        ]
    ],
    'emailVerificationCode' => '123456',
    'allowConflicts' => true,
    'allowBookingOutOfBounds' => true,
    'skipBookingLimits' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "cal-api-version: <cal-api-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cal.com/v2/booking-proposals"

	payload := strings.NewReader("{\n  \"attendee\": {\n    \"name\": \"John Doe\",\n    \"timeZone\": \"America/New_York\",\n    \"phoneNumber\": \"+919876543210\",\n    \"language\": \"it\",\n    \"email\": \"john.doe@example.com\"\n  },\n  \"requestedTimeslots\": [\n    \"2024-08-13T09:00:00Z\",\n    \"2024-08-14T09:00:00Z\"\n  ],\n  \"bookingFieldsResponses\": {\n    \"customField\": \"customValue\"\n  },\n  \"eventTypeId\": 123,\n  \"eventTypeSlug\": \"my-event-type\",\n  \"username\": \"john-doe\",\n  \"teamSlug\": \"john-doe\",\n  \"organizationSlug\": \"acme-corp\",\n  \"guests\": [\n    \"guest1@example.com\",\n    \"guest2@example.com\"\n  ],\n  \"meetingUrl\": \"https://example.com/meeting\",\n  \"location\": {\n    \"type\": \"address\"\n  },\n  \"metadata\": {\n    \"key\": \"value\"\n  },\n  \"lengthInMinutes\": 30,\n  \"routing\": {\n    \"responseId\": 123,\n    \"teamMemberIds\": [\n      101,\n      102\n    ]\n  },\n  \"emailVerificationCode\": \"123456\",\n  \"allowConflicts\": true,\n  \"allowBookingOutOfBounds\": true,\n  \"skipBookingLimits\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("cal-api-version", "<cal-api-version>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cal.com/v2/booking-proposals")
  .header("cal-api-version", "<cal-api-version>")
  .header("Content-Type", "application/json")
  .body("{\n  \"attendee\": {\n    \"name\": \"John Doe\",\n    \"timeZone\": \"America/New_York\",\n    \"phoneNumber\": \"+919876543210\",\n    \"language\": \"it\",\n    \"email\": \"john.doe@example.com\"\n  },\n  \"requestedTimeslots\": [\n    \"2024-08-13T09:00:00Z\",\n    \"2024-08-14T09:00:00Z\"\n  ],\n  \"bookingFieldsResponses\": {\n    \"customField\": \"customValue\"\n  },\n  \"eventTypeId\": 123,\n  \"eventTypeSlug\": \"my-event-type\",\n  \"username\": \"john-doe\",\n  \"teamSlug\": \"john-doe\",\n  \"organizationSlug\": \"acme-corp\",\n  \"guests\": [\n    \"guest1@example.com\",\n    \"guest2@example.com\"\n  ],\n  \"meetingUrl\": \"https://example.com/meeting\",\n  \"location\": {\n    \"type\": \"address\"\n  },\n  \"metadata\": {\n    \"key\": \"value\"\n  },\n  \"lengthInMinutes\": 30,\n  \"routing\": {\n    \"responseId\": 123,\n    \"teamMemberIds\": [\n      101,\n      102\n    ]\n  },\n  \"emailVerificationCode\": \"123456\",\n  \"allowConflicts\": true,\n  \"allowBookingOutOfBounds\": true,\n  \"skipBookingLimits\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cal.com/v2/booking-proposals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["cal-api-version"] = '<cal-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"attendee\": {\n    \"name\": \"John Doe\",\n    \"timeZone\": \"America/New_York\",\n    \"phoneNumber\": \"+919876543210\",\n    \"language\": \"it\",\n    \"email\": \"john.doe@example.com\"\n  },\n  \"requestedTimeslots\": [\n    \"2024-08-13T09:00:00Z\",\n    \"2024-08-14T09:00:00Z\"\n  ],\n  \"bookingFieldsResponses\": {\n    \"customField\": \"customValue\"\n  },\n  \"eventTypeId\": 123,\n  \"eventTypeSlug\": \"my-event-type\",\n  \"username\": \"john-doe\",\n  \"teamSlug\": \"john-doe\",\n  \"organizationSlug\": \"acme-corp\",\n  \"guests\": [\n    \"guest1@example.com\",\n    \"guest2@example.com\"\n  ],\n  \"meetingUrl\": \"https://example.com/meeting\",\n  \"location\": {\n    \"type\": \"address\"\n  },\n  \"metadata\": {\n    \"key\": \"value\"\n  },\n  \"lengthInMinutes\": 30,\n  \"routing\": {\n    \"responseId\": 123,\n    \"teamMemberIds\": [\n      101,\n      102\n    ]\n  },\n  \"emailVerificationCode\": \"123456\",\n  \"allowConflicts\": true,\n  \"allowBookingOutOfBounds\": true,\n  \"skipBookingLimits\": true\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "data": {
    "uid": "019205e4-4b3a-7000-8000-2c1a3f5b7d90",
    "eventTypeId": 123,
    "expiresAt": "2024-08-14T09:30:00.000Z",
    "requestedTimeslots": [
      {
        "start": "2024-08-13T09:00:00.000Z",
        "end": "2024-08-13T09:30:00.000Z",
        "hostId": 42
      }
    ]
  }
}

Headers

cal-api-version

string

default:2024-08-13

required

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

Example:

"2024-08-13"

Authorization

string

value must be Bearer <token> where <token> is api key prefixed with cal_, managed user access token, or OAuth 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

attendee

object

required

The attendee's details.

Show child attributes

requestedTimeslots

string[]

required

The proposed start times in ISO 8601 format in UTC timezone. The number of times must exactly match the event type's bookingProposalCount, and each must be an available slot.

Minimum array length: 1

Example:

[
  "2024-08-13T09:00:00Z",
  "2024-08-14T09:00:00Z"
]

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:

["guest1@example.com", "guest2@example.com"]

meetingUrl

string<uri>

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

Address · 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.

Show child attributes

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.

Show child attributes

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.

Required range: x >= 1

Example:

30

routing

object

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

Show child attributes

Example:

{
  "responseId": 123,
  "teamMemberIds": [101, 102]
}

emailVerificationCode

string

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

Example:

"123456"

allowConflicts

boolean

When true and the authenticated user is a host of the event type, availability conflict checks are bypassed. If the user is not a host or is unauthenticated, this parameter is silently ignored.

Example:

true

allowBookingOutOfBounds

boolean

When true and the authenticated user is a host of the event type, booking time out-of-bounds checks are bypassed allowing bookings outside the normally permitted scheduling window. If the user is not a host or is unauthenticated, this parameter is silently ignored. Only supported on the 2026-02-25 API version.

Example:

true

skipBookingLimits

boolean

When true and the authenticated user is a host of the event type, booking limit checks (event type, team, and per-host limits such as bookings per day/week/month/year, as well as duration limits) are bypassed, allowing the booking to be created even when a host has reached their limit. If the user is not a host or is unauthenticated, this parameter is silently ignored. Only supported on the 2026-02-25 API version.

Example:

true

Response

201 - application/json

status

enum<string>

required

Available options:

success,

error

Example:

"success"

data

object

required

Show child attributes

Getting Started

CORE

CALENDARS

EVENT TYPES & AUTOMATION

TEAMS

ORGANIZATIONS

AUTH & ACCESS

DEPRECATED

Create a booking proposal

Headers

Body

Response